Movatterモバイル変換

ps: List, Query, Manipulate System Processes

Description

List, query and manipulate all system processes, on 'Windows', 'Linux' and 'macOS'.

Author(s)

Maintainer: Gábor Csárdicsardi.gabor@gmail.com

Authors:

• Jay Loden

• Dave Daeschler

• Giampaolo Rodola'

Other contributors:

• Posit Software, PBC [copyright holder, funder]

See Also

Useful links:

• https://github.com/r-lib/ps

• https://ps.r-lib.org/

• Report bugs athttps://github.com/r-lib/ps/issues

testthat reporter that checks if child processes are cleaned up in tests

Description

CleanupReporter takes an existing testthatReporter object, andwraps it, so it checks for leftover child processes, at the specifiedplace, see theproc_unit argument below.

Usage

CleanupReporter(reporter = testthat::ProgressReporter)

Arguments

Details

Child processes can be reported via a failed expectation, cleaned upsilently, or cleaned up and reported (the default).

If atest_that() block has an error,CLeanupReporter does notemit any expectations at the end of that block. The error will lead to atest failure anyway. It will still perform the cleanup, if requested,however.

The constructor of theCleanupReporter class has options:

• file: the output file, if any, this is passed toreporter.

• proc_unit: when to perform the child process check and cleanup.Possible values:

  • "test": at the end of eachtestthat::test_that() block(the default),

  • "testsuite": at the end of the test suite.

• proc_cleanup: Logical scalar, whether to kill the leftoverprocesses,TRUE by default.

• proc_fail: Whether to create an expectation, that fails if thereare any processes alive,TRUE by default.

• proc_timeout: How long to wait for the processes to quit. This issometimes needed, because even if some kill signals were sent tochild processes, it might take a short time for these to take effect.It defaults to one second.

• rconn_unit: When to perform the R connection cleanup. Possible valuesare"test" and"testsuite", like forproc_unit.

• rconn_cleanup: Logical scalar, whether to clean up leftover Rconnections.TRUE by default.

• rconn_fail: Whether to fail for leftover R connections.TRUE bydefault.

• file_unit: When to check for open files. Possible values are"test" and"testsuite", like forproc_unit.

• file_fail: Whether to fail for leftover open files.TRUE bydefault.

• conn_unit: When to check for open network connections.Possible values are"test" and"testsuite", like forproc_unit.

• conn_fail: Whether to fail for leftover network connections.TRUE by default.

Value

New reporter class that behaves exactly likereporter,but it checks for, and optionally cleans up child processes, at thespecified granularity.

Examples

This is how to use this reporter intestthat.R:

library(testthat)library(mypackage)if  (ps::ps_is_supported()) {  reporter <- ps::CleanupReporter(testthat::ProgressReporter)$new(    proc_unit = "test", proc_cleanup = TRUE)} else {  ## ps does not support this platform  reporter <- "progress"}test_check("mypackage", reporter = reporter)

Note

Some IDEs, like RStudio, start child processes frequently, andsometimes crash when these are killed, only use this reporter in aterminal session. In particular, you can always use it in theidiomatictestthat.R file, that callstest_check() during⁠R CMD check⁠.

List of 'errno' error codes

Description

For the errors that are not used on the current platform,value isNA_integer_.

Usage

errno()

Details

A data frame with columns:name,value,description.

Examples

errno()

Process table

Description

Data frame with the currently running processes.

Usage

ps(user = NULL, after = NULL, columns = NULL)

Arguments

Details

Columns shown by default, ifcolumns is not given orNULL:

• pid: Process ID.

• ppid: Process ID of parent process.

• name: Process name.

• username: Name of the user (real uid on POSIX).

• status: I.e.running,sleeping, etc.

• user: User CPU time.

• system: System CPU time.

• rss: Resident set size, the amount of memory the process currentlyuses. Does not include memory that is swapped out. It does includeshared libraries.

• vms: Virtual memory size. All memory the process has access to.

• created: Time stamp when the process was created.

• ps_handle:ps_handle objects, in a list column.

Additional columns that can be requested viacolumns:

• cmdline: Command line, in a single string, fromps_cmdline().

• vcmdline: Likecmdline, but each command line argument in aseparate string.

• cwd: Current working directory, fromps_cwd().

• exe: Path of the executable of the process, fromps_exe().

• num_fds: Number of open file descriptors, fromps_num_fds().

• num_threads: Number of threads, fromps_num_threads().

• cpu_children_user: Seeps_cpu_times().

• cpu_children_system: Seeps_cpu_times().

• terminal: Terminal device, fromps_terminal().

• uid_real: Real user id, fromps_uids().

• uid_effective: Effective user id, fromps_uids().

• uid_saved: Saved user id, fromps_uids().

• gid_real: Real group id, fromps_gids().

• gid_effective: Effective group id, fromps_gids().

• gid_saved: Saved group id, fromps_gids().

• mem_shared: Seeps_memory_info().

• mem_text: Seeps_memory_info().

• mem_data: Seeps_memory_info().

• mem_lib: Seeps_memory_info().

• mem_dirty: Seeps_memory_info().

• mem_pfaults: Seeps_memory_info().

• mem_pageins: Seeps_memory_info().

• mem_maxrss: Seeps_memory_full_info().

• mem_uss: Seeps_memory_full_info().

• mem_pss: Seeps_memory_full_info().

• mem_swap: Seeps_memory_full_info().

Use"*" incolumns to include all columns.

Value

Data frame, see columns below.

List currently running applications

Description

This function currently only works on macOS.

Usage

ps_apps()

Value

A data frame with columns:

• pid: integer process id.

• name: process name.

• bundle_identifier: bundle identifier, e.g.com.apple.dock.

• bundle_url: bundle URL, a⁠file://⁠ URL to the app bundle.

• arch: executable architecture, possible values arearm64, i386, x86_64, ppc, ppc64.

• executable_url:⁠file://⁠ URL to the executable file.

• launch_date: launch time stamp, aPOSIXct object, may beNA.

• finished_launching: whether the app has finished launching.

• active: whether the app is active.

• activation_policy: one of the following values:

  • regular: the application is an ordinary app that appears in theDock and may have a user interface.

  • accessory: the application doesn’t appear in the Dock anddoesn’t have a menu bar, but it may be activated programmaticallyor by clicking on one of its windows.

  • prohibited: the application doesn’t appear in the Dock and maynot create windows or be activated.

Examples

ps_apps()

Boot time of the system

Description

Boot time of the system

Usage

ps_boot_time()

Value

APOSIXct object.

List of child processes (process objects) of the process. Note thatthis typically requires enumerating all processes on the system, soit is a costly operation.

Description

List of child processes (process objects) of the process. Note thatthis typically requires enumerating all processes on the system, soit is a costly operation.

Usage

ps_children(p = ps_handle(), recursive = FALSE)

Arguments

Value

List ofps_handle objects.

See Also

Other process handle functions:ps_cmdline(),ps_connections(),ps_cpu_times(),ps_create_time(),ps_cwd(),ps_descent(),ps_environ(),ps_exe(),ps_handle(),ps_interrupt(),ps_is_running(),ps_kill(),ps_memory_info(),ps_name(),ps_num_fds(),ps_num_threads(),ps_open_files(),ps_pid(),ps_ppid(),ps_resume(),ps_send_signal(),ps_shared_libs(),ps_status(),ps_suspend(),ps_terminal(),ps_terminate(),ps_uids(),ps_username()

Examples

p <- ps_parent(ps_handle())ps_children(p)

Command line of the process

Description

Command line of the process, i.e. the executable and the command linearguments, in a character vector. On Unix the program might change itscommand line, and some programs actually do it.

Usage

ps_cmdline(p = ps_handle())

Arguments

Details

For a zombie process it throws azombie_process error.

Value

Character vector.

See Also

Other process handle functions:ps_children(),ps_connections(),ps_cpu_times(),ps_create_time(),ps_cwd(),ps_descent(),ps_environ(),ps_exe(),ps_handle(),ps_interrupt(),ps_is_running(),ps_kill(),ps_memory_info(),ps_name(),ps_num_fds(),ps_num_threads(),ps_open_files(),ps_pid(),ps_ppid(),ps_resume(),ps_send_signal(),ps_shared_libs(),ps_status(),ps_suspend(),ps_terminal(),ps_terminate(),ps_uids(),ps_username()

Examples

p <- ps_handle()pps_name(p)ps_exe(p)ps_cmdline(p)

List network connections of a process

Description

For a zombie process it throws azombie_process error.

Usage

ps_connections(p = ps_handle())

Arguments

Value

Data frame, with columns:

• fd: integer file descriptor on POSIX systems,NA on Windows.

• family: Address family, string, typicallyAF_UNIX,AF_INET orAF_INET6.

• type: Socket type, string, typicallySOCK_STREAM (TCP) orSOCK_DGRAM (UDP).

• laddr: Local address, string,NA for UNIX sockets.

• lport: Local port, integer,NA for UNIX sockets.

• raddr: Remote address, string,NA for UNIX sockets. This isalwaysNA forAF_INET sockets on Linux.

• rport: Remote port, integer,NA for UNIX sockets.

• state: Socket state, e.g.CONN_ESTABLISHED, etc. It isNAfor UNIX sockets.

See Also

Other process handle functions:ps_children(),ps_cmdline(),ps_cpu_times(),ps_create_time(),ps_cwd(),ps_descent(),ps_environ(),ps_exe(),ps_handle(),ps_interrupt(),ps_is_running(),ps_kill(),ps_memory_info(),ps_name(),ps_num_fds(),ps_num_threads(),ps_open_files(),ps_pid(),ps_ppid(),ps_resume(),ps_send_signal(),ps_shared_libs(),ps_status(),ps_suspend(),ps_terminal(),ps_terminate(),ps_uids(),ps_username()

Examples

p <- ps_handle()ps_connections(p)sc <- socketConnection("httpbin.org", port = 80)ps_connections(p)close(sc)ps_connections(p)

Number of logical or physical CPUs

Description

If cannot be determined, it returnsNA. It also returnsNA on olderWindows systems, e.g. Vista or older and Windows Server 2008 or older.

Usage

ps_cpu_count(logical = TRUE)

Arguments

Value

Integer scalar.

Examples

ps_cpu_count(logical = TRUE)ps_cpu_count(logical = FALSE)

CPU times of the process

Description

All times are measured in seconds:

• user: Amount of time that this process has been scheduled in usermode.

• system: Amount of time that this process has been scheduled inkernel mode

• children_user: On Linux, amount of time that this process'swaited-for children have been scheduled in user mode.

• children_system: On Linux, Amount of time that this process'swaited-for children have been scheduled in kernel mode.

Usage

ps_cpu_times(p = ps_handle())

Arguments

Details

Throws azombie_process() error for zombie processes.

Value

Named real vector or length four:user,system,children_user,children_system. The last two areNA onnon-Linux systems.

See Also

Other process handle functions:ps_children(),ps_cmdline(),ps_connections(),ps_create_time(),ps_cwd(),ps_descent(),ps_environ(),ps_exe(),ps_handle(),ps_interrupt(),ps_is_running(),ps_kill(),ps_memory_info(),ps_name(),ps_num_fds(),ps_num_threads(),ps_open_files(),ps_pid(),ps_ppid(),ps_resume(),ps_send_signal(),ps_shared_libs(),ps_status(),ps_suspend(),ps_terminal(),ps_terminate(),ps_uids(),ps_username()

Examples

p <- ps_handle()pps_cpu_times(p)proc.time()

Start time of a process

Description

The pid and the start time pair serves as the identifier of the process,as process ids might be reused, but the chance of starting two processeswith identical ids within the resolution of the timer is minimal.

Usage

ps_create_time(p = ps_handle())

Arguments

Details

This function works even if the process has already finished.

Value

POSIXct object, start time, in GMT.

See Also

Other process handle functions:ps_children(),ps_cmdline(),ps_connections(),ps_cpu_times(),ps_cwd(),ps_descent(),ps_environ(),ps_exe(),ps_handle(),ps_interrupt(),ps_is_running(),ps_kill(),ps_memory_info(),ps_name(),ps_num_fds(),ps_num_threads(),ps_open_files(),ps_pid(),ps_ppid(),ps_resume(),ps_send_signal(),ps_shared_libs(),ps_status(),ps_suspend(),ps_terminal(),ps_terminate(),ps_uids(),ps_username()

Examples

p <- ps_handle()pps_create_time(p)

Process current working directory as an absolute path.

Description

For a zombie process it throws azombie_process error.

Usage

ps_cwd(p = ps_handle())

Arguments

Value

String scalar.

See Also

Other process handle functions:ps_children(),ps_cmdline(),ps_connections(),ps_cpu_times(),ps_create_time(),ps_descent(),ps_environ(),ps_exe(),ps_handle(),ps_interrupt(),ps_is_running(),ps_kill(),ps_memory_info(),ps_name(),ps_num_fds(),ps_num_threads(),ps_open_files(),ps_pid(),ps_ppid(),ps_resume(),ps_send_signal(),ps_shared_libs(),ps_status(),ps_suspend(),ps_terminal(),ps_terminate(),ps_uids(),ps_username()

Examples

p <- ps_handle()pps_cwd(p)

Query the ancestry of a process

Description

Query the parent processes recursively, up to the first process.(On some platforms, like Windows, the process tree is not a treeand may contain loops, in which caseps_descent() only goes upuntil the first repetition.)

Usage

ps_descent(p = ps_handle())

Arguments

Value

A list of process handles, starting withp, each oneis the parent process of the previous one.

See Also

Other process handle functions:ps_children(),ps_cmdline(),ps_connections(),ps_cpu_times(),ps_create_time(),ps_cwd(),ps_environ(),ps_exe(),ps_handle(),ps_interrupt(),ps_is_running(),ps_kill(),ps_memory_info(),ps_name(),ps_num_fds(),ps_num_threads(),ps_open_files(),ps_pid(),ps_ppid(),ps_resume(),ps_send_signal(),ps_shared_libs(),ps_status(),ps_suspend(),ps_terminal(),ps_terminate(),ps_uids(),ps_username()

Examples

ps_descent()

System-wide disk I/O counters

Description

Returns a data.frame of system-wide disk I/O counters.

Usage

ps_disk_io_counters()

Details

Includes the following non-NA fields for all supported platforms:

• read_count: number of reads

• write_count: number of writes

• read_bytes: number of bytes read

• write_bytes: number of bytes written

And for only some platforms:

• read_time: time spent reading from disk (in milliseconds)

• write_time: time spent writing to disk (in milliseconds)

• busy_time: time spent doing actual I/Os (in milliseconds)

• read_merged_count: number of merged reads (see iostats doc)

• write_merged_count: number of merged writes (see iostats doc)

Value

A data frame of one row per disk of I/O stats, with columnsname,read_countread_merged_countread_bytes,read_time,write_count,write_merged_count,write_byteswrite_time, andbusy_time.

See Also

Other disk functions:ps_disk_partitions(),ps_disk_usage()

Examples

ps_disk_io_counters()

List all mounted partitions

Description

The output is similar the Unixmount anddf commands.

Usage

ps_disk_partitions(all = FALSE)

Arguments

Value

A data frame with columnsdevice,mountpoint,fstype andoptions.

See Also

Other disk functions:ps_disk_io_counters(),ps_disk_usage()

Examples

ps_disk_partitions(all = TRUE)ps_disk_partitions()

Disk usage statistics, per partition

Description

The output is similar to the Unixdf command.

Usage

ps_disk_usage(paths = ps_disk_partitions()$mountpoint)

Arguments

Details

Note that on Unix a small percentage of the disk space (5% typically)is reserved for the superuser.ps_disk_usage() returns the spaceavailable to the calling user.

Value

A data frame with columnsmountpoint,total,used,available andcapacity.

See Also

Other disk functions:ps_disk_io_counters(),ps_disk_partitions()

Examples

ps_disk_usage()

Environment variables of a process

Description

ps_environ() returns the environment variables of the process, in anamed vector, similarly to the return value ofSys.getenv()(without arguments).

Usage

ps_environ(p = ps_handle())ps_environ_raw(p = ps_handle())

Arguments

Details

Note: this usually does not reflect changes made after the processstarted.

ps_environ_raw() is similar top$environ() but returns theunparsed"var=value" strings. This is faster, and sometimes goodenough.

These functions throw azombie_process error for zombie processes.

Value

ps_environ() returns a named character vector (that has aDlist class, so it is printed nicely),ps_environ_raw() returns acharacter vector.

macOS issues

ps_environ() usually does not work on macOS nowadays. This is becausemacOS does not allow reading the environment variables of anotherprocess. Accoding to the Darwin source code,ps_environ will work isone of these conditions hold:

• You are running a development or debug kernel, i.e. if you aredebugging the macOS kernel itself.

• The target process is same as the calling process.

• SIP if off.

• The target process is not restricted, e.g. it is running a binarythat was not signed.

• The calling process has thecom.apple.private.read-environment-variables entitlement. Howeveradding this entitlement to the R binary makes R crash on startup.

Otherwiseps_environ will return an empty set of environment variableson macOS.

Issue 121 might have more information about this.

See Also

Other process handle functions:ps_children(),ps_cmdline(),ps_connections(),ps_cpu_times(),ps_create_time(),ps_cwd(),ps_descent(),ps_exe(),ps_handle(),ps_interrupt(),ps_is_running(),ps_kill(),ps_memory_info(),ps_name(),ps_num_fds(),ps_num_threads(),ps_open_files(),ps_pid(),ps_ppid(),ps_resume(),ps_send_signal(),ps_shared_libs(),ps_status(),ps_suspend(),ps_terminal(),ps_terminate(),ps_uids(),ps_username()

Examples

p <- ps_handle()penv <- ps_environ(p)env[["R_HOME"]]

Full path of the executable of a process

Description

Path to the executable of the process. May also be an empty string orNA if it cannot be determined.

Usage

ps_exe(p = ps_handle())

Arguments

Details

For a zombie process it throws azombie_process error.

Value

Character scalar.

See Also

Other process handle functions:ps_children(),ps_cmdline(),ps_connections(),ps_cpu_times(),ps_create_time(),ps_cwd(),ps_descent(),ps_environ(),ps_handle(),ps_interrupt(),ps_is_running(),ps_kill(),ps_memory_info(),ps_name(),ps_num_fds(),ps_num_threads(),ps_open_files(),ps_pid(),ps_ppid(),ps_resume(),ps_send_signal(),ps_shared_libs(),ps_status(),ps_suspend(),ps_terminal(),ps_terminate(),ps_uids(),ps_username()

Examples

p <- ps_handle()pps_name(p)ps_exe(p)ps_cmdline(p)

File system information for files

Description

File system information for files

Usage

ps_fs_info(paths = "/")

Arguments

Value

Data frame with file system information for eachpath inpaths, one row per path. Common columns for alloperating systems:

• path: The input paths, i.e. thepaths argument.

• mountpoint: Directory where the file system is mounted.On Linux there is a small chance that it was not possible tolook this up, and it isNA_character_. This is the drive letteror the mount directory on Windows, with a trailing⁠\⁠.

• name: Device name.On Linux there is a small chance that it was not possible tolook this up, and it isNA_character_. On Windows this is thevolume GUID path of the form⁠\\?\Volume{GUID}\⁠.

• type: File system type (character).On Linux there is a tiny chance that it was not possible tolook this up, and it isNA_character_.

• block_size: File system block size. This is the sector size onWindows, in bytes.

• transfer_block_size: Pptimal transfer block size. On Linux it iscurrently always the same asblock_size. This is the cluster sizeon Windows, in bytes.

• total_data_blocks: Total data blocks in file system. On Windowsthis is the number of sectors.

• free_blocks: Free blocks in file system. On Windows this is thenumber of free sectors.

• free_blocks_non_superuser: Free blocks for a non-superuser, whichmight be different on Unix. On Windows this is the number of freesectors for the calling user.

• id: File system id. This is a raw vector. On Linux it isoften all zeros. It is alwaysNULL on Windows.

• owner: User that mounted the file system. On Linux and Windowsthis is currently alwaysNA_real_.

• type_code: Type of file system, a numeric code. On Windows thisthis isNA_real_.

• subtype_code: File system subtype (flavor). On Linux and Windowsthis is alwaysNA_real_.

The rest of the columns are flags, and they are operating systemdependent.

macOS:

• RDONLY: A read-only filesystem.

• SYNCHRONOUS: File system is written to synchronously.

• NOEXEC: Can't exec from filesystem.

• NOSUID: Setuid bits are not honored on this filesystem.

• NODEV: Don't interpret special files.

• UNION: Union with underlying filesysten.

• ASYNC: File system written to asynchronously.

• EXPORTED: File system is exported.

• LOCAL: File system is stored locally.

• QUOTA: Quotas are enabled on this file system.

• ROOTFS: This file system is the root of the file system.

• DOVOLFS: File system supports volfs.

• DONTBROWSE: File system is not appropriate path to user data.

• UNKNOWNPERMISSIONS: VFS will ignore ownership information onfilesystem filesystemtem objects.

• AUTOMOUNTED: File system was mounted by automounter.

• JOURNALED: File system is journaled.

• DEFWRITE: File system should defer writes.

• MULTILABEL: MAC support for individual labels.

• CPROTECT: File system supports per-file encrypted data protection.

Linux:

• MANDLOCK: Mandatory locking is permitted on the filesystem(seefcntl(2)).

• NOATIME: Do not update access times; seemount(2).

• NODEV: Disallow access to device special files on this filesystem.

• NODIRATIME: Do not update directory access times; see mount(2).

• NOEXEC: Execution of programs is disallowed on this filesystem.

• NOSUID: The set-user-ID and set-group-ID bits are ignored byexec(3) for executable files on this filesystem

• RDONLY: This filesystem is mounted read-only.

• RELATIME: Update atime relative to mtime/ctime; seemount(2).

• SYNCHRONOUS: Writes are synched to the filesystem immediately(see the description ofO_SYNC in 'open(2)“).

• NOSYMFOLLOW: Symbolic links are not followed when resolving paths;see 'mount(2)“.

Windows:

• CASE_SENSITIVE_SEARCH: Supports case-sensitive file names.

• CASE_PRESERVED_NAMES: Supports preserved case of file names whenit places a name on disk.

• UNICODE_ON_DISK: Supports Unicode in file names as they appear ondisk.

• PERSISTENT_ACLS: Preserves and enforces access control lists(ACL). For example, the NTFS file system preserves and enforcesACLs, and the FAT file system does not.

• FILE_COMPRESSION: Supports file-based compression.

• VOLUME_QUOTAS: Supports disk quotas.

• SUPPORTS_SPARSE_FILES: Supports sparse files.

• SUPPORTS_REPARSE_POINTS: Supports reparse points.

• SUPPORTS_REMOTE_STORAGE: Supports remote storage.

• RETURNS_CLEANUP_RESULT_INFO: On a successful cleanup operation,the file system returns information that describes additionalactions taken during cleanup, such as deleting the file. Filesystem filters can examine this information in their post-cleanupcallback.

• SUPPORTS_POSIX_UNLINK_RENAME: Supports POSIX-style delete andrename operations.

• VOLUME_IS_COMPRESSED: It is a compressed volume, for example, aDoubleSpace volume.

• SUPPORTS_OBJECT_IDS: Supports object identifiers.

• SUPPORTS_ENCRYPTION: Supports the Encrypted File System (EFS).

• NAMED_STREAMS: Supports named streams.

• READ_ONLY_VOLUME: It is read-only.

• SEQUENTIAL_WRITE_ONCE: Supports a single sequential write.

• SUPPORTS_TRANSACTIONS: Supports transactions.

• SUPPORTS_HARD_LINKS: The volume supports hard links.

• SUPPORTS_EXTENDED_ATTRIBUTES: Supports extended attributes.

• SUPPORTS_OPEN_BY_FILE_ID: Supports open by FileID.

• SUPPORTS_USN_JOURNAL: Supports update sequence number (USN)journals.

• SUPPORTS_INTEGRITY_STREAMS: Supports integrity streams.

• SUPPORTS_BLOCK_REFCOUNTING: The volume supports sharing logicalclusters between files on the same volume.

• SUPPORTS_SPARSE_VDL: The file system tracks whether each clusterof a file contains valid data (either from explicit file writes orautomatic zeros) or invalid data (has not yet been written to orzeroed).

• DAX_VOLUME: The volume is a direct access (DAX) volume.

• SUPPORTS_GHOSTING: Supports ghosting.

Examples

ps_fs_info(c("/", "~", "."))

Find the mount point of a file or directory

Description

Find the mount point of a file or directory

Usage

ps_fs_mount_point(paths)

Arguments

Value

Character vector, paths to the mount points of the inputpaths.

Examples

ps_fs_mount_point(".")

File status

Description

This function is currently not implemented on Windows.

Usage

ps_fs_stat(paths, follow = TRUE)

Arguments

Value

Data frame with one row for each path inpaths. Columns:

• path: Expandedpaths.

• dev_major: Major device ID of the device the path resides on.

• dev_minor: Minor device ID of the device the path resodes on.

• inode: Inode number.

• mode: File type and mode (permissions). It is easier to use thetype andpermissions columns.

• type: File type, character. One ofregular file, directory, character device, block device, FIFO, symbolic link, socket.

• permissions: Permissions, numeric code in an integer column.

• nlink: Number of hard links.

• uid: User id of owner.

• gid: Group id of owner.

• rdev_major: If the path is a device, its major device id,otherwiseNA_integer_.

• rdev_minor: IF the path is a device, its minor device id,otherwiseNA_integer_.

• size: File size in bytes.

• block_size: Block size for filesystem I/O.

• blocks: Number of 512B blocks allocated.

• access_time: Time of last access.

• modification_time: Time of last modification.

• change_time: Time of last status change.

Examples

ps_fs_stat(c(".", tempdir()))

Query or set CPU affinity

Description

ps_get_cpu_affinity() queries theCPU affinity ofa process.ps_set_cpu_affinity() sets the CPU affinity of a process.

Usage

ps_get_cpu_affinity(p = ps_handle())ps_set_cpu_affinity(p = ps_handle(), affinity)

Arguments

Details

CPU affinity consists in telling the OS to run a process on a limitedset of CPUs only (on Linux cmdline, thetaskset command is typicallyused).

These functions are only supported on Linux and Windows. They error on macOS.

Value

ps_get_cpu_affinity() returns an integer vector of CPUnumbers, starting with zero.

ps_set_cpu_affinity() returnsNULL, invisibly.

Examples

# currentorig <- ps_get_cpu_affinity()orig# restrictps_set_cpu_affinity(affinity = 0:0)ps_get_cpu_affinity()# restoreps_set_cpu_affinity(affinity = orig)ps_get_cpu_affinity()

Create a process handle

Description

Create a process handle

Usage

ps_handle(pid = NULL, time = NULL)## S3 method for class 'ps_handle'as.character(x, ...)## S3 method for class 'ps_handle'format(x, ...)## S3 method for class 'ps_handle'print(x, ...)

Arguments

Value

ps_handle() returns a process handle (classps_handle).

See Also

Other process handle functions:ps_children(),ps_cmdline(),ps_connections(),ps_cpu_times(),ps_create_time(),ps_cwd(),ps_descent(),ps_environ(),ps_exe(),ps_interrupt(),ps_is_running(),ps_kill(),ps_memory_info(),ps_name(),ps_num_fds(),ps_num_threads(),ps_open_files(),ps_pid(),ps_ppid(),ps_resume(),ps_send_signal(),ps_shared_libs(),ps_status(),ps_suspend(),ps_terminal(),ps_terminate(),ps_uids(),ps_username()

Examples

p <- ps_handle()p

Interrupt a process

Description

SendsSIGINT on POSIX, and 'CTRL+C' or 'CTRL+BREAK' on Windows.

Usage

ps_interrupt(p = ps_handle(), ctrl_c = TRUE)

Arguments

See Also

Other process handle functions:ps_children(),ps_cmdline(),ps_connections(),ps_cpu_times(),ps_create_time(),ps_cwd(),ps_descent(),ps_environ(),ps_exe(),ps_handle(),ps_is_running(),ps_kill(),ps_memory_info(),ps_name(),ps_num_fds(),ps_num_threads(),ps_open_files(),ps_pid(),ps_ppid(),ps_resume(),ps_send_signal(),ps_shared_libs(),ps_status(),ps_suspend(),ps_terminal(),ps_terminate(),ps_uids(),ps_username()

Checks whether a process is running

Description

It returnsFALSE if the process has already finished.

Usage

ps_is_running(p = ps_handle())

Arguments

Details

It uses the start time of the process to work around pid reuse. I.e.

Value

Logical scalar.

See Also

Other process handle functions:ps_children(),ps_cmdline(),ps_connections(),ps_cpu_times(),ps_create_time(),ps_cwd(),ps_descent(),ps_environ(),ps_exe(),ps_handle(),ps_interrupt(),ps_kill(),ps_memory_info(),ps_name(),ps_num_fds(),ps_num_threads(),ps_open_files(),ps_pid(),ps_ppid(),ps_resume(),ps_send_signal(),ps_shared_libs(),ps_status(),ps_suspend(),ps_terminal(),ps_terminate(),ps_uids(),ps_username()

Examples

p <- ps_handle()pps_is_running(p)

Kill one or more processes

Description

Kill the process with SIGKILL preemptively checking whether PID hasbeen reused. On Windows it usesTerminateProcess().

Usage

ps_kill(p = ps_handle(), grace = 200)

Arguments

Details

Note that since ps version 1.8,ps_kill() does not error if thep process (or some processes ifp is a list) are already terminated.

Value

Character vector, with one element for each process handle inp. If the process was already dead beforeps_kill() tried to killit, the corresponding return value is"dead". Ifps_kill() justkilled it, it is"killed".

See Also

Other process handle functions:ps_children(),ps_cmdline(),ps_connections(),ps_cpu_times(),ps_create_time(),ps_cwd(),ps_descent(),ps_environ(),ps_exe(),ps_handle(),ps_interrupt(),ps_is_running(),ps_memory_info(),ps_name(),ps_num_fds(),ps_num_threads(),ps_open_files(),ps_pid(),ps_ppid(),ps_resume(),ps_send_signal(),ps_shared_libs(),ps_status(),ps_suspend(),ps_terminal(),ps_terminate(),ps_uids(),ps_username()

Examples

px <- processx::process$new("sleep", "10")p <- ps_handle(px$get_pid())pps_kill(p)pps_is_running(p)px$get_exit_status()

Return the average system load over the last 1, 5 and 15 minutes as atuple.

Description

The “load” represents the processes which are in a runnablestate, either using the CPU or waiting to use the CPU (e.g. waiting fordisk I/O). On Windows this is emulated by using a Windows API thatspawns a thread which keeps running in background and updates resultsevery 5 seconds, mimicking the UNIX behavior. Thus, on Windows, thefirst time this is called and for the next 5 seconds it will return ameaningless (0.0, 0.0, 0.0) vector. The numbers returned only make senseif related to the number of CPU cores installed on the system. So, forinstance, a value of 3.14 on a system with 10 logical CPUs means thatthe system load was 31.4% percent over the last N minutes.

Usage

ps_loadavg()

Value

Numeric vector of length 3.

Examples

ps_loadavg()

Mark a process and its (future) child tree

Description

ps_mark_tree() generates a random environment variable name and setsit in the current R process. This environment variable will be (bydefault) inherited by all child (and grandchild, etc.) processes, andwill help finding these processes, even if and when they are (no longer)related to the current R process. (I.e. they are not connected in theprocess tree.)

Usage

ps_mark_tree()with_process_cleanup(expr)ps_find_tree(marker)ps_kill_tree(marker, sig = signals()$SIGKILL, grace = 200)

Arguments

Details

ps_find_tree() finds the processes that set the supplied environmentvariable and returns them in a list.

ps_kill_tree() finds the processes that set the supplied environmentvariable, and kills them (or sends them the specified signal on Unix).

with_process_cleanup() evaluates an R expression, and cleans up allexternal processes that were started by the R process while evaluatingthe expression. This includes child processes of child processes, etc.,recursively. It returns a list with entries:result is the result ofthe expression,visible is TRUE if the expression should be printedto the screen, andprocess_cleanup is a named integer vector of thecleaned pids, names are the process names.

Ifexpr throws an error, then so doeswith_process_cleanup(), thesame error. Nevertheless processes are still cleaned up.

Value

ps_mark_tree() returns the name of the environment variable,which can be used as themarker inps_kill_tree().

ps_find_tree() returns a list ofps_handle objects.

ps_kill_tree() returns the pids of the killed processes, in a namedinteger vector. The names are the file names of the executables, whenavailable.

with_process_cleanup() returns the value of the evaluated expression.

macOS issues

These functions do not work on macOS, unless specific criteria aremet. Seeps_environ() for details.

Note

Note thatwith_process_cleanup() is problematic if the R process ismulti-threaded and the other threads start subprocesses.with_process_cleanup() cleans up those processes as well, which isprobably not what you want. This is an issue for example in RStudio.Do not usewith_process_cleanup(), unless you are sure that theR process is single-threaded, or the other threads do not startsubprocesses. E.g. using it in package test cases is usually fine,because RStudio runs these in a separate single-threaded process.

The same holds for manually runningps_mark_tree() and thenps_find_tree() orps_kill_tree().

A safe way to use process cleanup is to use the processx package tostart subprocesses, and set thecleanup_tree = TRUE inprocessx::run() or theprocessx::process constructor.

Memory usage information

Description

Memory usage information

Usage

ps_memory_info(p = ps_handle())ps_memory_full_info(p = ps_handle())

Arguments

Details

ps_memory_info() returns information about memory usage.

It returns a named vector. Portable fields:

• rss: "Resident Set Size", this is the non-swapped physical memory aprocess has used (bytes). On UNIX it matches "top"‘s 'RES' column (see doc). OnWindows this is an alias forwset field and it matches "Memory"column oftaskmgr.exe.

• vmem: "Virtual Memory Size", this is the total amount of virtualmemory used by the process (bytes). On UNIX it matches "top"‘s 'VIRT' column(see doc). On Windows this is an alias for thepagefile field andit matches the "Working set (memory)" column oftaskmgr.exe.

Non-portable fields:

• shared: (Linux) memory that could be potentially shared with otherprocesses (bytes). This matches "top"‘s 'SHR' column (see doc).

• text: (Linux): aka 'TRS' (text resident set) the amount of memorydevoted to executable code (bytes). This matches "top"‘s 'CODE' column (seedoc).

• data: (Linux): aka 'DRS' (data resident set) the amount of physicalmemory devoted to other than executable code (bytes). It matches "top"‘s'DATA' column (see doc).

• lib: (Linux): the memory used by shared libraries (bytes).

• dirty: (Linux): the amount of memory in dirty pages (bytes).

• pfaults: (macOS): number of page faults.

• pageins: (macOS): number of actual pageins.

For the explanation of Windows fields see thePROCESS_MEMORY_COUNTERS_EXstructure.

ps_memory_full_info() returns all fields asps_memory_info(), plusadditional information, but typically takes slightly longer to run, andmight not have access to some processes thatps_memory_info() canquery:

• maxrss maximum resident set size over the process's lifetime. Thisonly works for the calling process, otherwise it isNA_real_.

• uss: Unique Set Size, this is the memory which is unique to aprocess and which would be freed if the process was terminated rightnow.

• pss (Linux only): Proportional Set Size, is the amount of memoryshared with other processes, accounted in a way that the amount isdivided evenly between the processes that share it. I.e. if a processhas 10 MBs all to itself and 10 MBs shared with another process itsPSS will be 15 MBs.

• swap (Linux only): amount of memory that has been swapped out todisk.

They both throw azombie_process() error for zombie processes.

Value

Named real vector.

See Also

Other process handle functions:ps_children(),ps_cmdline(),ps_connections(),ps_cpu_times(),ps_create_time(),ps_cwd(),ps_descent(),ps_environ(),ps_exe(),ps_handle(),ps_interrupt(),ps_is_running(),ps_kill(),ps_name(),ps_num_fds(),ps_num_threads(),ps_open_files(),ps_pid(),ps_ppid(),ps_resume(),ps_send_signal(),ps_shared_libs(),ps_status(),ps_suspend(),ps_terminal(),ps_terminate(),ps_uids(),ps_username()

Examples

p <- ps_handle()pps_memory_info(p)ps_memory_full_info(p)

Process name

Description

The name of the program, which is typically the name of the executable.

Usage

ps_name(p = ps_handle())

Arguments

Details

On Unix this can change, e.g. via an exec*() system call.

ps_name() works on zombie processes.

Value

Character scalar.

See Also

Other process handle functions:ps_children(),ps_cmdline(),ps_connections(),ps_cpu_times(),ps_create_time(),ps_cwd(),ps_descent(),ps_environ(),ps_exe(),ps_handle(),ps_interrupt(),ps_is_running(),ps_kill(),ps_memory_info(),ps_num_fds(),ps_num_threads(),ps_open_files(),ps_pid(),ps_ppid(),ps_resume(),ps_send_signal(),ps_shared_libs(),ps_status(),ps_suspend(),ps_terminal(),ps_terminate(),ps_uids(),ps_username()

Examples

p <- ps_handle()pps_name(p)ps_exe(p)ps_cmdline(p)

Number of open file descriptors

Description

Note that in some IDEs, e.g. RStudio or R.app on macOS, the IDE itselfopens files from other threads, in addition to the files opened from themain R thread.

Usage

ps_num_fds(p = ps_handle())

Arguments

Details

For a zombie process it throws azombie_process error.

Value

Integer scalar.

See Also

Other process handle functions:ps_children(),ps_cmdline(),ps_connections(),ps_cpu_times(),ps_create_time(),ps_cwd(),ps_descent(),ps_environ(),ps_exe(),ps_handle(),ps_interrupt(),ps_is_running(),ps_kill(),ps_memory_info(),ps_name(),ps_num_threads(),ps_open_files(),ps_pid(),ps_ppid(),ps_resume(),ps_send_signal(),ps_shared_libs(),ps_status(),ps_suspend(),ps_terminal(),ps_terminate(),ps_uids(),ps_username()

Examples

p <- ps_handle()ps_num_fds(p)f <- file(tmp <- tempfile(), "w")ps_num_fds(p)close(f)unlink(tmp)ps_num_fds(p)

Number of threads

Description

Throws azombie_process() error for zombie processes.

Usage

ps_num_threads(p = ps_handle())

Arguments

Value

Integer scalar.

See Also

Other process handle functions:ps_children(),ps_cmdline(),ps_connections(),ps_cpu_times(),ps_create_time(),ps_cwd(),ps_descent(),ps_environ(),ps_exe(),ps_handle(),ps_interrupt(),ps_is_running(),ps_kill(),ps_memory_info(),ps_name(),ps_num_fds(),ps_open_files(),ps_pid(),ps_ppid(),ps_resume(),ps_send_signal(),ps_shared_libs(),ps_status(),ps_suspend(),ps_terminal(),ps_terminate(),ps_uids(),ps_username()

Examples

p <- ps_handle()pps_num_threads(p)

Open files of a process

Description

Note that in some IDEs, e.g. RStudio or R.app on macOS, the IDE itselfopens files from other threads, in addition to the files opened from themain R thread.

Usage

ps_open_files(p = ps_handle())

Arguments

Details

For a zombie process it throws azombie_process error.

Value

Data frame with columns:fd andpath.fd is numericfile descriptor on POSIX systems,NA on Windows.path is anabsolute path to the file.

See Also

Other process handle functions:ps_children(),ps_cmdline(),ps_connections(),ps_cpu_times(),ps_create_time(),ps_cwd(),ps_descent(),ps_environ(),ps_exe(),ps_handle(),ps_interrupt(),ps_is_running(),ps_kill(),ps_memory_info(),ps_name(),ps_num_fds(),ps_num_threads(),ps_pid(),ps_ppid(),ps_resume(),ps_send_signal(),ps_shared_libs(),ps_status(),ps_suspend(),ps_terminal(),ps_terminate(),ps_uids(),ps_username()

Examples

p <- ps_handle()ps_open_files(p)f <- file(tmp <- tempfile(), "w")ps_open_files(p)close(f)unlink(tmp)ps_open_files(p)

Query the type of the OS

Description

Query the type of the OS

Usage

ps_os_type()ps_is_supported()

Value

ps_os_type returns a named logical vector. The rest of thefunctions return a logical scalar.

ps_is_supported() returnsTRUE if ps supports the current platform.

Examples

ps_os_type()ps_is_supported()

Pid of a process handle

Description

This function works even if the process has already finished.

Usage

ps_pid(p = ps_handle())

Arguments

Value

Process id.

See Also

Other process handle functions:ps_children(),ps_cmdline(),ps_connections(),ps_cpu_times(),ps_create_time(),ps_cwd(),ps_descent(),ps_environ(),ps_exe(),ps_handle(),ps_interrupt(),ps_is_running(),ps_kill(),ps_memory_info(),ps_name(),ps_num_fds(),ps_num_threads(),ps_open_files(),ps_ppid(),ps_resume(),ps_send_signal(),ps_shared_libs(),ps_status(),ps_suspend(),ps_terminal(),ps_terminate(),ps_uids(),ps_username()

Examples

p <- ps_handle()pps_pid(p)ps_pid(p) == Sys.getpid()

Ids of all processes on the system

Description

Ids of all processes on the system

Usage

ps_pids()

Value

Integer vector of process ids.

Parent pid or parent process of a process

Description

ps_ppid() returns the parent pid,ps_parent() returns aps_handleof the parent.

Usage

ps_ppid(p = ps_handle())ps_parent(p = ps_handle())

Arguments

Details

On POSIX systems, if the parent process terminates, another process(typically the pid 1 process) is marked as parent.ps_ppid() andps_parent() will return this process then.

Bothps_ppid() andps_parent() work for zombie processes.

Value

ps_ppid() returns and integer scalar, the pid of the parentofp.ps_parent() returns aps_handle.

See Also

Other process handle functions:ps_children(),ps_cmdline(),ps_connections(),ps_cpu_times(),ps_create_time(),ps_cwd(),ps_descent(),ps_environ(),ps_exe(),ps_handle(),ps_interrupt(),ps_is_running(),ps_kill(),ps_memory_info(),ps_name(),ps_num_fds(),ps_num_threads(),ps_open_files(),ps_pid(),ps_resume(),ps_send_signal(),ps_shared_libs(),ps_status(),ps_suspend(),ps_terminal(),ps_terminate(),ps_uids(),ps_username()

Examples

p <- ps_handle()pps_ppid(p)ps_parent(p)

Resume (continue) a stopped process

Description

Resume process execution with SIGCONT preemptively checkingwhether PID has been reused. On Windows this has the effect of resumingall process threads.

Usage

ps_resume(p = ps_handle())

Arguments

See Also

Other process handle functions:ps_children(),ps_cmdline(),ps_connections(),ps_cpu_times(),ps_create_time(),ps_cwd(),ps_descent(),ps_environ(),ps_exe(),ps_handle(),ps_interrupt(),ps_is_running(),ps_kill(),ps_memory_info(),ps_name(),ps_num_fds(),ps_num_threads(),ps_open_files(),ps_pid(),ps_ppid(),ps_send_signal(),ps_shared_libs(),ps_status(),ps_suspend(),ps_terminal(),ps_terminate(),ps_uids(),ps_username()

Examples

px <- processx::process$new("sleep", "10")p <- ps_handle(px$get_pid())pps_suspend(p)ps_status(p)ps_resume(p)ps_status(p)ps_kill(p)

Send signal to a process

Description

Send a signal to the process. Not implemented on Windows. Seesignals() for the list of signals on the current platform.

Usage

ps_send_signal(p = ps_handle(), sig)

Arguments

Details

It checks if the process is still running, before sending the signal,to avoid signalling the wrong process, because of pid reuse.

See Also

Other process handle functions:ps_children(),ps_cmdline(),ps_connections(),ps_cpu_times(),ps_create_time(),ps_cwd(),ps_descent(),ps_environ(),ps_exe(),ps_handle(),ps_interrupt(),ps_is_running(),ps_kill(),ps_memory_info(),ps_name(),ps_num_fds(),ps_num_threads(),ps_open_files(),ps_pid(),ps_ppid(),ps_resume(),ps_shared_libs(),ps_status(),ps_suspend(),ps_terminal(),ps_terminate(),ps_uids(),ps_username()

Examples

px <- processx::process$new("sleep", "10")p <- ps_handle(px$get_pid())pps_send_signal(p, signals()$SIGINT)pps_is_running(p)px$get_exit_status()

List all processes that loaded a shared library

Description

List all processes that loaded a shared library

Usage

ps_shared_lib_users(paths, user = ps_username(), filter = NULL)

Arguments

Details

Notes:

This function currently only works on Windows.

On Windows, a 32 bit R process can only list other 32 bit processes.Similarly, a 64 bit R process can only list other 64 bit processes.This is a limitation of the Windows API.

Even though Windows file systems are (almost always) caseinsensitive, the matching ofpaths,user and alsofilterare case sensitive. This might change in the future.

This function can be very slow on Windows, because it needs toenumerate all shared libraries of all processes in the system,unless thefilter argument is set. Make sure you setfilterif you can.

If you want to look up multiple shared libraries, list all of theminpaths, instead of callingps_shared_lib_users for eachindividually.

If you are after libraries loaded by R processes, you might want tosetfilter toc("Rgui.exe", "Rterm.exe", "rsession.exe") Thelast one is for RStudio.

Value

A data frame with columns:

• dll: the file name of the dll file, without the path,

• path: path to the shared library,

• pid: process ID of the process,

• name: name of the process,

• username: username of process owner,

• ps_handle:ps_handle object, that can be used to furtherquery and manipulate the process.

See Also

Other shared library tools:ps_shared_libs()

Examples

dlls <- vapply(getLoadedDLLs(), "[[", character(1), "path")psdll <- dlls[["ps"]][[1]]r_procs <- c("Rgui.exe", "Rterm.exe", "rsession.exe")ps_shared_lib_users(psdll, filter = r_procs)

List the dynamically loaded libraries of a process

Description

Note: this function currently only works on Windows.

Usage

ps_shared_libs(p = ps_handle())

Arguments

Value

Data frame with one column currently:path, theabsolute path to the loaded module or shared library. On Windowsthe list includes the executable file itself.

See Also

Other process handle functions:ps_children(),ps_cmdline(),ps_connections(),ps_cpu_times(),ps_create_time(),ps_cwd(),ps_descent(),ps_environ(),ps_exe(),ps_handle(),ps_interrupt(),ps_is_running(),ps_kill(),ps_memory_info(),ps_name(),ps_num_fds(),ps_num_threads(),ps_open_files(),ps_pid(),ps_ppid(),ps_resume(),ps_send_signal(),ps_status(),ps_suspend(),ps_terminal(),ps_terminate(),ps_uids(),ps_username()

Other shared library tools:ps_shared_lib_users()

Examples

# The loaded DLLs of the current processps_shared_libs()

Current process status

Description

One of the following:

• "idle": Process being created by fork, or process has been sleepingfor a long time. macOS only.

• "running": Currently runnable on macOS and Windows. Actuallyrunning on Linux.

• "sleeping" Sleeping on a wait or poll.

• "disk_sleep" Uninterruptible sleep, waiting for an I/O operation(Linux only).

• "stopped" Stopped, either by a job control signal or because itis being traced.

• "uninterruptible" Process is in uninterruptible wait. macOS only.

• "tracing_stop" Stopped for tracing (Linux only).

• "zombie" Zombie. Finished, but parent has not read out the exitstatus yet.

• "dead" Should never be seen (Linux).

• "wake_kill" Received fatal signal (Linux only).

• "waking" Paging (Linux only, not valid since the 2.6.xx kernel).

Usage

ps_status(p = ps_handle())

Arguments

Details

It might returnNA_character_ on macOS.

Works for zombie processes.

Value

Character scalar.

Note on macOS

On macOSps_status() often falls back to calling the externalpsprogram, because macOS does not let R access the status of most otherprocesses. Notably, it is usually able to access the status of other Rprocesses.

The externalps program always runs as the root user, andit also has special entitlements, so it can typically access the statusof most processes.

If this behavior is problematic for you, e.g. because calling anexternal program is too slow, set theps.no_external_ps option toTRUE:

options(ps.no_external_ps = TRUE)

Note that setting this option toTRUE will causeps_status() toreturnNA_character_ for most processes.

See Also

Other process handle functions:ps_children(),ps_cmdline(),ps_connections(),ps_cpu_times(),ps_create_time(),ps_cwd(),ps_descent(),ps_environ(),ps_exe(),ps_handle(),ps_interrupt(),ps_is_running(),ps_kill(),ps_memory_info(),ps_name(),ps_num_fds(),ps_num_threads(),ps_open_files(),ps_pid(),ps_ppid(),ps_resume(),ps_send_signal(),ps_shared_libs(),ps_suspend(),ps_terminal(),ps_terminate(),ps_uids(),ps_username()

Examples

p <- ps_handle()pps_status(p)

Suspend (stop) the process

Description

Suspend process execution withSIGSTOP preemptively checkingwhether PID has been reused. On Windows this has the effect ofsuspending all process threads.

Usage

ps_suspend(p = ps_handle())

Arguments

See Also

Other process handle functions:ps_children(),ps_cmdline(),ps_connections(),ps_cpu_times(),ps_create_time(),ps_cwd(),ps_descent(),ps_environ(),ps_exe(),ps_handle(),ps_interrupt(),ps_is_running(),ps_kill(),ps_memory_info(),ps_name(),ps_num_fds(),ps_num_threads(),ps_open_files(),ps_pid(),ps_ppid(),ps_resume(),ps_send_signal(),ps_shared_libs(),ps_status(),ps_terminal(),ps_terminate(),ps_uids(),ps_username()

Examples

px <- processx::process$new("sleep", "10")p <- ps_handle(px$get_pid())pps_suspend(p)ps_status(p)ps_resume(p)ps_status(p)ps_kill(p)

System CPU times.

Description

Every attribute represents the seconds the CPU has spent in the givenmode. The attributes availability varies depending on the platform:

• user: time spent by normal processes executing in user mode;on Linux this also includes guest time.

• system: time spent by processes executing in kernel mode.

• idle: time spent doing nothing.

Usage

ps_system_cpu_times()

Details

Platform-specific fields:

• nice (UNIX): time spent by niced (prioritized) processes executingin user mode; on Linux this also includes guest_nice time.

• iowait (Linux): time spent waiting for I/O to complete. This is notaccounted in idle time counter.

• irq (Linux): time spent for servicing hardware interrupts.

• softirq (Linux): time spent for servicing software interrupts.

• steal (Linux 2.6.11+): time spent by other operating systemsrunning in a virtualized environment.

• guest (Linux 2.6.24+): time spent running a virtual CPU for guestoperating systems under the control of the Linux kernel.

• guest_nice (Linux 3.2.0+): time spent running a niced guest(virtual CPU for guest operating systems under the control of theLinux kernel).

Value

Named list

Examples

ps_system_cpu_times()

Statistics about system memory usage

Description

Statistics about system memory usage

Usage

ps_system_memory()

Value

Named list. All numbers are in bytes:

• total: total physical memory (exclusive swap).

• avail the memory that can be given instantly to processes withoutthe system going into swap. This is calculated by summing differentmemory values depending on the platform and it is supposed to be usedto monitor actual memory usage in a cross platform fashion.

• percent: Percentage of memory that is taken.

• used: memory used, calculated differently depending onthe platform and designed for informational purposes only.total -free does not necessarily matchused.

• free: memory not being used at all (zeroed) that isreadily available; note that this doesn’t reflect the actual memoryavailable (useavailable instead).total -used does notnecessarily matchfree.

• active: (Unix only) memory currently in use or very recently used,and so it is in RAM.

• inactive: (Unix only) memory that is marked as not used.

• wired: (macOS only) memory that is marked to always stay in RAM. Itis never moved to disk.

• buffers: (Linux only) cache for things like file system metadata.

• cached: (Linux only) cache for various things.

• shared: (Linux only) memory that may be simultaneously accessed bymultiple processes.

• slab: (Linux only) in-kernel data structures cache.

See Also

Other memory functions:ps_system_swap()

Examples

ps_system_memory()

System swap memory statistics

Description

System swap memory statistics

Usage

ps_system_swap()

Value

Named list. All numbers are in bytes:

• total: total swap memory.

• used: used swap memory.

• free: free swap memory.

• percent: the percentage usage.

• sin: the number of bytes the system has swapped in from disk(cumulative). This isNA on Windows.

• sout: the number of bytes the system has swapped out from disk(cumulative). This isNA on Windows.

See Also

Other memory functions:ps_system_memory()

Examples

ps_system_swap()

Terminal device of the process

Description

Returns the terminal of the process. Not implemented on Windows, alwaysreturnsNA_character_. On Unix it returnsNA_character_ if theprocess has no terminal.

Usage

ps_terminal(p = ps_handle())

Arguments

Details

Works for zombie processes.

Value

Character scalar.

See Also

Other process handle functions:ps_children(),ps_cmdline(),ps_connections(),ps_cpu_times(),ps_create_time(),ps_cwd(),ps_descent(),ps_environ(),ps_exe(),ps_handle(),ps_interrupt(),ps_is_running(),ps_kill(),ps_memory_info(),ps_name(),ps_num_fds(),ps_num_threads(),ps_open_files(),ps_pid(),ps_ppid(),ps_resume(),ps_send_signal(),ps_shared_libs(),ps_status(),ps_suspend(),ps_terminate(),ps_uids(),ps_username()

Examples

p <- ps_handle()pps_terminal(p)

Terminate a Unix process

Description

Send aSIGTERM signal to the process. Not implemented on Windows.

Usage

ps_terminate(p = ps_handle())

Arguments

Details

Checks if the process is still running, to work around pid reuse.

See Also

Other process handle functions:ps_children(),ps_cmdline(),ps_connections(),ps_cpu_times(),ps_create_time(),ps_cwd(),ps_descent(),ps_environ(),ps_exe(),ps_handle(),ps_interrupt(),ps_is_running(),ps_kill(),ps_memory_info(),ps_name(),ps_num_fds(),ps_num_threads(),ps_open_files(),ps_pid(),ps_ppid(),ps_resume(),ps_send_signal(),ps_shared_libs(),ps_status(),ps_suspend(),ps_terminal(),ps_uids(),ps_username()

Examples

px <- processx::process$new("sleep", "10")p <- ps_handle(px$get_pid())pps_terminate(p)pps_is_running(p)px$get_exit_status()

Query the size of the current terminal

Description

If the standard output of the current R process is not a terminal,e.g. because it is redirected to a file, or the R process is running ina GUI, then it will throw an error. You need to handle this error ifyou want to use this function in a package.

Usage

ps_tty_size()

Details

If an error happens, the error message is different depending onwhat type of device the standard output is. Some common error messagesare:

• "Inappropriate ioctl for device."

• "Operation not supported on socket."

• "Operation not supported by device."

Whatever the error message,ps_tty_size always fails with an error ofclassps_unknown_tty_size, which you can catch.

Examples

# An example that falls back to the 'width' optiontryCatch(  ps_tty_size(),  ps_unknown_tty_size = function(err) {    c(width = getOption("width"), height = NA_integer_)  })

User ids and group ids of the process

Description

User ids and group ids of the process. Both return integer vectors withnames:real,effective andsaved.

Usage

ps_uids(p = ps_handle())ps_gids(p = ps_handle())

Arguments

Details

Both work for zombie processes.

They are not implemented on Windows, they throw anot_implementederror.

Value

Named integer vector of length 3, with names:real,effective andsaved.

See Also

ps_username() returns a username and works on allplatforms.

Other process handle functions:ps_children(),ps_cmdline(),ps_connections(),ps_cpu_times(),ps_create_time(),ps_cwd(),ps_descent(),ps_environ(),ps_exe(),ps_handle(),ps_interrupt(),ps_is_running(),ps_kill(),ps_memory_info(),ps_name(),ps_num_fds(),ps_num_threads(),ps_open_files(),ps_pid(),ps_ppid(),ps_resume(),ps_send_signal(),ps_shared_libs(),ps_status(),ps_suspend(),ps_terminal(),ps_terminate(),ps_username()

Examples

p <- ps_handle()pps_uids(p)ps_gids(p)

Owner of the process

Description

The name of the user that owns the process. On Unix it is calculatedfrom the real user id.

Usage

ps_username(p = ps_handle())

Arguments

Details

On Unix, a numeric uid id returned if the uid is not in the userdatabase, thus a username cannot be determined.

Works for zombie processes.

Value

String scalar.

See Also

Other process handle functions:ps_children(),ps_cmdline(),ps_connections(),ps_cpu_times(),ps_create_time(),ps_cwd(),ps_descent(),ps_environ(),ps_exe(),ps_handle(),ps_interrupt(),ps_is_running(),ps_kill(),ps_memory_info(),ps_name(),ps_num_fds(),ps_num_threads(),ps_open_files(),ps_pid(),ps_ppid(),ps_resume(),ps_send_signal(),ps_shared_libs(),ps_status(),ps_suspend(),ps_terminal(),ps_terminate(),ps_uids()

Examples

p <- ps_handle()pps_username(p)

List users connected to the system

Description

List users connected to the system

Usage

ps_users()

Value

A data frame with columnsusername,tty,hostname,start_time,pid.tty andpidareNA on Windows.pid is the process id of the login process.For local users thehostname column is the empty string.

Wait for one or more processes to terminate, with a timeout

Description

This function supports interruption with SIGINT on Unix, or CTRL+Cor CTRL+BREAK on Windows.

Usage

ps_wait(p, timeout = -1)

Arguments

Value

Logical vector, with one value of each process inp.For processes that terminated it contains aTRUE value. Forprocesses that are still running it contains aFALSE value.

Examples

# this example calls `sleep`, so it only works on Unixp1 <- processx::process$new("sleep", "100")p2 <- processx::process$new("sleep", "100")# returns c(FALSE, FALSE) immediately if p1 and p2 are runningps_wait(list(p1$as_ps_handle(), p2$as_ps_handle()), 0)# timeouts at one secondps_wait(list(p1$as_ps_handle(), p2$as_ps_handle()), 1000)p1$kill()p2$kill()# returns c(TRUE, TRUE) immediatelyps_wait(list(p1$as_ps_handle(), p2$as_ps_handle()), 1000)

Get or set the priority of a process

Description

ps_get_nice() returns the current priority,ps_set_nice() sets anew priority,ps_windows_nice_values() list the possible priorityvalues on Windows.

Usage

ps_windows_nice_values()ps_get_nice(p = ps_handle())ps_set_nice(p = ps_handle(), value)

Arguments

Details

Priority values are different on Windows and Unix.

On Unix, priority is an integer, which is maximum 20. 20 is the lowestpriority.

Rules:

• On Windows you can only set the priority of the processes the currentuser hasPROCESS_SET_INFORMATION access rights to. This typicallymeans your own processes.

• On Unix you can only set the priority of the your own processes.The superuser can set the priority of any process.

• On Unix you cannot set a higher priority, unless you are the superuser.(I.e. you cannot set a lower number.)

• On Unix the default priority of a process is zero.

Value

ps_windows_nice_values() return a character vector of possiblepriority values on Windows.

ps_get_nice() returns a string fromps_windows_nice_values() on Windows. On Unix it returns an integersmaller than or equal to 20.

ps_set_nice() returnNULL invisibly.

List of all supported signals

Description

Only the signals supported by the current platform are included.

Usage

signals()

Value

List of integers, named by signal names.