Package 'processx'

Description

Base64 Encoding and Decoding

Usage

base64_decode(x)

base64_encode(x)

Arguments

Value

Raw vector, result of the encoding / decoding.

Description

These functions are currently experimental and will change in the future. Note that processx connections are not compatible with R's built-in connection system.

Usage

conn_create_fd(fd, encoding = "", close = TRUE)

conn_file_name(con)

conn_create_pipepair(encoding = "", nonblocking = c(TRUE, FALSE))

conn_read_chars(con, n = -1)

## S3 method for class 'processx_connection'
conn_read_chars(con, n = -1)

processx_conn_read_chars(con, n = -1)

conn_read_lines(con, n = -1)

## S3 method for class 'processx_connection'
conn_read_lines(con, n = -1)

processx_conn_read_lines(con, n = -1)

conn_is_incomplete(con)

## S3 method for class 'processx_connection'
conn_is_incomplete(con)

processx_conn_is_incomplete(con)

conn_write(con, str, sep = "\n", encoding = "")

## S3 method for class 'processx_connection'
conn_write(con, str, sep = "\n", encoding = "")

processx_conn_write(con, str, sep = "\n", encoding = "")

conn_create_file(filename, read = NULL, write = NULL)

conn_set_stdout(con, drop = TRUE)

conn_set_stderr(con, drop = TRUE)

conn_get_fileno(con)

conn_disable_inheritance()

## S3 method for class 'processx_connection'
close(con, ...)

processx_conn_close(con, ...)

is_valid_fd(fd)

Arguments

Details

conn_create_fd() creates a connection from a file descriptor.

conn_file_name() returns the name of the file associated with the connection. For connections that do not refer to a file in the file system it returns NA_character(). Except for named pipes on Windows, where it returns the full name of the pipe.

conn_create_pipepair() creates a pair of connected connections, the first one is writeable, the second one is readable.

conn_read_chars() reads UTF-8 characters from the connections. If the connection itself is not UTF-8 encoded, it re-encodes it.

conn_read_lines() reads lines from a connection.

conn_is_incomplete() returns FALSE if the connection surely has no more data.

conn_write() writes a character or raw vector to the connection. It might not be able to write all bytes into the connection, in which case it returns the leftover bytes in a raw vector. Call conn_write() again with this raw vector.

conn_create_file() creates a connection to a file.

conn_set_stdout() set the standard output of the R process, to the specified connection.

conn_set_stderr() set the standard error of the R process, to the specified connection.

conn_get_fileno() return the integer file desciptor that belongs to the connection.

conn_disable_inheritance() can be called to disable the inheritance of all open handles. Call this function as soon as possible in a new process to avoid inheriting the inherited handles even further. The function is best effort to close the handles, it might still leave some handles open. It should work for stdin, stdout and stderr, at least.

is_valid_fd() returns TRUE if fd is a valid open file descriptor. You can use it to check if the R process has standard input, output or error. E.g. R processes running in GUI (like RGui) might not have any of the standard streams available.

If a stream is redirected to the null device (e.g. in a callr subprocess), that is is still a valid file descriptor.

Examples

is_valid_fd(0L)      # stdin
is_valid_fd(1L)      # stdout
is_valid_fd(2L)      # stderr

Description

Create a FIFO for inter-process communication Note that these functions are currently experimental.

Usage

conn_create_fifo(
  filename = NULL,
  read = NULL,
  write = NULL,
  encoding = "",
  nonblocking = TRUE
)

conn_connect_fifo(
  filename,
  read = NULL,
  write = NULL,
  encoding = "",
  nonblocking = TRUE
)

Arguments

Details

conn_create_fifo() creates a FIFO and connects to it. On Unix this is a proper FIFO in the file system, in the R temporary directory. On Windows it is a named pipe.

Use conn_file_name() to query the name of the FIFO, and conn_connect_fifo() to connect to the other end.

conn_connect_fifo() connects to a FIFO created with conn_create_fifo(), typically in another process. filename refers to the name of the pipe on Windows.

On Windows, conn_connect_fifo() may be successful even if the FIFO does not exist, but then later poll() or read/write operations will fail. We are planning on changing this behavior in the future, to make conn_connect_fifo() fail immediately, like on Unix.

Notes

In general Unix domain sockets work better than FIFOs, so we suggest

you use sockets if you can. See conn_create_unix_socket().

Creating the read end of the FIFO

This case is simpler. To wait for a writer to connect to the FIFO you can use poll() as usual. Then use conn_read_chars() or conn_read_lines() to read from the FIFO, as usual. Use conn_is_incomplete() after a read to check if there is more data, or the writer is done.

Creating the write end of the FIFO

This is somewhat trickier. Creating the (non-blocking) FIFO does not block. However, there is no easy way to tell if a reader is connected to the other end of the FIFO or not. On Unix you can start using conn_write() to try to write to it, and this will succeed, until the buffer gets full, even if there is no reader. (When the buffer is full it will return the data that was not written, as usual.)

On Windows, using conn_write() to write to a FIFO without a reader fails with an error. This is not great, we are planning to improve it later.

Right now, one workaround for this behavior is for the reader to connunicate to the writer process independenctly that it has connected to the FIFO. (E.g. another FIFO in the opposite direction can do that.)

See Also

processx internals

Examples

# Example for a non-blocking FIFO

# Need to open the reading end first, otherwise Unix fails
reader <- conn_create_fifo()

# Always use poll() before you read, with a timeout if you like.
# If you read before the other end of the FIFO is connected, then
# the OS (or processx?) assumes that the FIFO is done, and you cannot
# read anything.
# Now poll() tells us that there is no data yet.
poll(list(reader), 0)

writer <- conn_connect_fifo(conn_file_name(reader), write = TRUE)
conn_write(writer, "hello\nthere!\n")

poll(list(reader), 1000)
conn_read_lines(reader, 1)
conn_read_chars(reader)

conn_is_incomplete(reader)

close(writer)
conn_read_chars(reader)
conn_is_incomplete(reader)

close(reader)

Description

Cross platform point-to-point inter-process communication with Unix=domain sockets, implemented via named pipes on Windows. These connection are always bidirectional, i.e. you can read from them and also write to them.

Usage

conn_create_unix_socket(filename = NULL, encoding = "")

conn_connect_unix_socket(filename, encoding = "")

conn_accept_unix_socket(con)

conn_unix_socket_state(con)

Arguments

Details

conn_create_unix_socket() creates a server socket. The new socket is listening at filename. See filename above.

conn_connect_unix_socket() creates a client socket and connects it to a server socket.

conn_accept_unix_socket() accepts a client connection at a server socket.

conn_unix_socket_state() returns the state of the socket. Currently it can return: "listening", "connected_server", "connected_client". It is possible that other states (e.g. for a closed socket) will be added in the future.

Notes

• poll() works on sockets, but only polls for data to read, and currently ignores the write-end of the socket.

• poll() also works for accepting client connections. It will return "connect"is a client connection is available for a server socket. After this you can call conn_accept_unix_socket() to accept the client connection.

Value

A new socket connection.

See Also

processx internals

Description

Create a pollable object from a curl multi handle's file descriptors

Usage

curl_fds(fds)

Arguments

Value

Pollable object, that be used with poll() directly.

Description

Default options for pseudo terminals (ptys)

Usage

default_pty_options()

Value

Named list of default values of pty options.

Options and default values:

• echo whether to keep the echo on the terminal. FALSE turns echo off.

• rows the (initial) terminal size, number of rows.

• cols the (initial) terminal size, number of columns.

Description

Wait until one of the specified connections or processes produce standard output or error, terminates, or a timeout occurs.

Usage

poll(processes, ms)

Arguments

Value

A list of character vectors of length one or three. There is one list element for each connection/process, in the same order as in the input list. For connections the result is a single string scalar. For processes the character vectors' elements are named output, error and process. Possible values for each individual result are: nopipe, ready, timeout, closed, silent. See details about these below. process refers to the poll connection, see the poll_connection argument of the process initializer.

Explanation of the return values

• nopipe means that the stdout or stderr from this process was not captured.

• ready means that the connection or the stdout or stderr from this process are ready to read from. Note that end-of-file on these outputs also triggers ready.

• timeout': the connections or processes are not ready to read from and a timeout happened.

• closed: the connection was already closed, before the polling started.

• silent: the connection is not ready to read from, but another connection was.

Examples

# Different commands to run for windows and unix
cmd1 <- switch(
  .Platform$OS.type,
  "unix" = c("sh", "-c", "sleep 1; ls"),
  c("cmd", "/c", "ping -n 2 127.0.0.1 && dir /b")
)
cmd2 <- switch(
  .Platform$OS.type,
  "unix" = c("sh", "-c", "sleep 2; ls 1>&2"),
  c("cmd", "/c", "ping -n 2 127.0.0.1 && dir /b 1>&2")
)

## Run them. p1 writes to stdout, p2 to stderr, after some sleep
p1 <- process$new(cmd1[1], cmd1[-1], stdout = "|")
p2 <- process$new(cmd2[1], cmd2[-1], stderr = "|")

## Nothing to read initially
poll(list(p1 = p1, p2 = p2), 0)

## Wait until p1 finishes. Now p1 has some output
p1$wait()
poll(list(p1 = p1, p2 = p2), -1)

## Close p1's connection, p2 will have output on stderr, eventually
close(p1$get_output_connection())
poll(list(p1 = p1, p2 = p2), -1)

## Close p2's connection as well, no nothing to poll
close(p2$get_error_connection())
poll(list(p1 = p1, p2 = p2), 0)

Description

Managing external processes from R is not trivial, and this class aims to help with this deficiency. It is essentially a small wrapper around the system base R function, to return the process id of the started process, and set its standard output and error streams. The process id is then used to manage the process.

Batch files

Running Windows batch files (.bat or .cmd files) may be complicated because of the cmd.exe command line parsing rules. For example you cannot easily have whitespace in both the command (path) and one of the arguments. To work around these limitations you need to start a cmd.exe shell explicitly and use its call command. For example:

process$new("cmd.exe", c("/c", "call", bat_file, "arg 1", "arg 2"))

This works even if bat_file contains whitespace characters. For more information about this, see this processx issue: https://github.com/r-lib/processx/issues/301

The detailed parsing rules are at https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/cmd

A very good practical guide is at https://ss64.com/nt/syntax-esc.html

Polling

The poll_io() function polls the standard output and standard error connections of a process, with a timeout. If there is output in either of them, or they are closed (e.g. because the process exits) poll_io() returns immediately.

In addition to polling a single process, the poll() function can poll the output of several processes, and returns as soon as any of them has generated output (or exited).

Cleaning up background processes

processx kills processes that are not referenced any more (if cleanup is set to TRUE), or the whole subprocess tree (if cleanup_tree is also set to TRUE).

The cleanup happens when the references of the processes object are garbage collected. To clean up earlier, you can call the kill() or kill_tree() method of the process(es), from an on.exit() expression, or an error handler:

process_manager <- function() {
  on.exit({
    try(p1$kill(), silent = TRUE)
    try(p2$kill(), silent = TRUE)
  }, add = TRUE)
  p1 <- process$new("sleep", "3")
  p2 <- process$new("sleep", "10")
  p1$wait()
  p2$wait()
}
process_manager()

If you interrupt process_manager() or an error happens then both p1 and p2 are cleaned up immediately. Their connections will also be closed. The same happens at a regular exit.

Methods

Public methods

• process$new()

• process$finalize()

• process$kill()

• process$kill_tree()

• process$signal()

• process$interrupt()

• process$get_pid()

• process$is_alive()

• process$wait()

• process$get_exit_status()

• process$format()

• process$print()

• process$get_start_time()

• process$is_supervised()

• process$supervise()

• process$read_output()

• process$read_error()

• process$read_output_lines()

• process$read_error_lines()

• process$is_incomplete_output()

• process$is_incomplete_error()

• process$has_input_connection()

• process$has_output_connection()

• process$has_error_connection()

• process$has_poll_connection()

• process$get_input_connection()

• process$get_output_connection()

• process$get_error_connection()

• process$read_all_output()

• process$read_all_error()

• process$read_all_output_lines()

• process$read_all_error_lines()

• process$write_input()

• process$get_input_file()

• process$get_output_file()

• process$get_error_file()

• process$poll_io()

• process$get_poll_connection()

• process$get_result()

• process$as_ps_handle()

• process$get_name()

• process$get_exe()

• process$get_cmdline()

• process$get_status()

• process$get_username()

• process$get_wd()

• process$get_cpu_times()

• process$get_memory_info()

• process$suspend()

• process$resume()

Method new()

Start a new process in the background, and then return immediately.

Usage

process$new(
  command = NULL,
  args = character(),
  stdin = NULL,
  stdout = NULL,
  stderr = NULL,
  pty = FALSE,
  pty_options = list(),
  connections = list(),
  poll_connection = NULL,
  env = NULL,
  cleanup = TRUE,
  cleanup_tree = FALSE,
  wd = NULL,
  echo_cmd = FALSE,
  supervise = FALSE,
  windows_verbatim_args = FALSE,
  windows_hide_window = FALSE,
  windows_detached_process = !cleanup,
  encoding = "",
  post_process = NULL
)

Arguments

Returns

R6 object representing the process.

Method finalize()

Cleanup method that is called when the process object is garbage collected. If requested so in the process constructor, then it eliminates all processes in the process's subprocess tree.

Usage

process$finalize()

Method kill()

Terminate the process. It also terminate all of its child processes, except if they have created a new process group (on Unix), or job object (on Windows). It returns TRUE if the process was terminated, and FALSE if it was not (because it was already finished/dead when processx tried to terminate it).

Usage

process$kill(grace = 0.1, close_connections = TRUE)

Arguments

Method kill_tree()

Process tree cleanup. It terminates the process (if still alive), together with any child (or grandchild, etc.) processes. It uses the ps package, so that needs to be installed, and ps needs to support the current platform as well. Process tree cleanup works by marking the process with an environment variable, which is inherited in all child processes. This allows finding descendents, even if they are orphaned, i.e. they are not connected to the root of the tree cleanup in the process tree any more. ⁠$kill_tree()⁠ returns a named integer vector of the process ids that were killed, the names are the names of the processes (e.g. "sleep", "notepad.exe", "Rterm.exe", etc.).

Usage

process$kill_tree(grace = 0.1, close_connections = TRUE)

Arguments

Method signal()

Send a signal to the process. On Windows only the SIGINT, SIGTERM and SIGKILL signals are interpreted, and the special 0 signal. The first three all kill the process. The 0 signal returns TRUE if the process is alive, and FALSE otherwise. On Unix all signals are supported that the OS supports, and the 0 signal as well.

Usage

process$signal(signal)

Arguments

Method interrupt()

Send an interrupt to the process. On Unix this is a SIGINT signal, and it is usually equivalent to pressing CTRL+C at the terminal prompt. On Windows, it is a CTRL+BREAK keypress. Applications may catch these events. By default they will quit.

Usage

process$interrupt()

Method get_pid()

Query the process id.

Usage

process$get_pid()

Returns

Integer scalar, the process id of the process.

Method is_alive()

Check if the process is alive.

Usage

process$is_alive()

Returns

Logical scalar.

Method wait()

Wait until the process finishes, or a timeout happens. Note that if the process never finishes, and the timeout is infinite (the default), then R will never regain control. In some rare cases, ⁠$wait()⁠ might take a bit longer than specified to time out. This happens on Unix, when another package overwrites the processx SIGCHLD signal handler, after the processx process has started. One such package is parallel, if used with fork clusters, e.g. through parallel::mcparallel().

Usage

process$wait(timeout = -1)

Arguments

Returns

It returns the process itself, invisibly.

Method get_exit_status()

⁠$get_exit_status⁠ returns the exit code of the process if it has finished and NULL otherwise. On Unix, in some rare cases, the exit status might be NA. This happens if another package (or R itself) overwrites the processx SIGCHLD handler, after the processx process has started. In these cases processx cannot determine the real exit status of the process. One such package is parallel, if used with fork clusters, e.g. through the parallel::mcparallel() function.

Usage

process$get_exit_status()

Method format()

format(p) or p$format() creates a string representation of the process, usually for printing.

Usage

process$format()

Method print()

print(p) or p$print() shows some information about the process on the screen, whether it is running and it's process id, etc.

Usage

process$print()

Method get_start_time()

⁠$get_start_time()⁠ returns the time when the process was started.

Usage

process$get_start_time()

Method is_supervised()

⁠$is_supervised()⁠ returns whether the process is being tracked by supervisor process.

Usage

process$is_supervised()

Method supervise()

⁠$supervise()⁠ if passed TRUE, tells the supervisor to start tracking the process. If FALSE, tells the supervisor to stop tracking the process. Note that even if the supervisor is disabled for a process, if it was started with cleanup = TRUE, the process will still be killed when the object is garbage collected.

Usage

process$supervise(status)

Arguments

Method read_output()

⁠$read_output()⁠ reads from the standard output connection of the process. If the standard output connection was not requested, then then it returns an error. It uses a non-blocking text connection. This will work only if stdout="|" was used. Otherwise, it will throw an error.

Usage

process$read_output(n = -1)

Arguments

Method read_error()

⁠$read_error()⁠ is similar to ⁠$read_output⁠, but it reads from the standard error stream.

Usage

process$read_error(n = -1)

Arguments

Method read_output_lines()

⁠$read_output_lines()⁠ reads lines from standard output connection of the process. If the standard output connection was not requested, then it returns an error. It uses a non-blocking text connection. This will work only if stdout="|" was used. Otherwise, it will throw an error.

Usage

process$read_output_lines(n = -1)

Arguments

Method read_error_lines()

⁠$read_error_lines()⁠ is similar to ⁠$read_output_lines⁠, but it reads from the standard error stream.

Usage

process$read_error_lines(n = -1)

Arguments

Method is_incomplete_output()

⁠$is_incomplete_output()⁠ return FALSE if the other end of the standard output connection was closed (most probably because the process exited). It return TRUE otherwise.

Usage

process$is_incomplete_output()

Method is_incomplete_error()

⁠$is_incomplete_error()⁠ return FALSE if the other end of the standard error connection was closed (most probably because the process exited). It return TRUE otherwise.

Usage

process$is_incomplete_error()

Method has_input_connection()

⁠$has_input_connection()⁠ return TRUE if there is a connection object for standard input; in other words, if stdout="|". It returns FALSE otherwise.

Usage

process$has_input_connection()

Method has_output_connection()

⁠$has_output_connection()⁠ returns TRUE if there is a connection object for standard output; in other words, if stdout="|". It returns FALSE otherwise.

Usage

process$has_output_connection()

Method has_error_connection()

⁠$has_error_connection()⁠ returns TRUE if there is a connection object for standard error; in other words, if stderr="|". It returns FALSE otherwise.

Usage

process$has_error_connection()

Method has_poll_connection()

⁠$has_poll_connection()⁠ return TRUE if there is a poll connection, FALSE otherwise.

Usage

process$has_poll_connection()

Method get_input_connection()

⁠$get_input_connection()⁠ returns a connection object, to the standard input stream of the process.

Usage

process$get_input_connection()

Method get_output_connection()

⁠$get_output_connection()⁠ returns a connection object, to the standard output stream of the process.

Usage

process$get_output_connection()

Method get_error_connection()

⁠$get_error_conneciton()⁠ returns a connection object, to the standard error stream of the process.

Usage

process$get_error_connection()

Method read_all_output()

⁠$read_all_output()⁠ waits for all standard output from the process. It does not return until the process has finished. Note that this process involves waiting for the process to finish, polling for I/O and potentially several readLines() calls. It returns a character scalar. This will return content only if stdout="|" was used. Otherwise, it will throw an error.

Usage

process$read_all_output()

Method read_all_error()

⁠$read_all_error()⁠ waits for all standard error from the process. It does not return until the process has finished. Note that this process involves waiting for the process to finish, polling for I/O and potentially several readLines() calls. It returns a character scalar. This will return content only if stderr="|" was used. Otherwise, it will throw an error.

Usage

process$read_all_error()

Method read_all_output_lines()

⁠$read_all_output_lines()⁠ waits for all standard output lines from a process. It does not return until the process has finished. Note that this process involves waiting for the process to finish, polling for I/O and potentially several readLines() calls. It returns a character vector. This will return content only if stdout="|" was used. Otherwise, it will throw an error.

Usage

process$read_all_output_lines()

Method read_all_error_lines()

⁠$read_all_error_lines()⁠ waits for all standard error lines from a process. It does not return until the process has finished. Note that this process involves waiting for the process to finish, polling for I/O and potentially several readLines() calls. It returns a character vector. This will return content only if stderr="|" was used. Otherwise, it will throw an error.

Usage

process$read_all_error_lines()

Method write_input()

⁠$write_input()⁠ writes the character vector (separated by sep) to the standard input of the process. It will be converted to the specified encoding. This operation is non-blocking, and it will return, even if the write fails (because the write buffer is full), or if it suceeds partially (i.e. not the full string is written). It returns with a raw vector, that contains the bytes that were not written. You can supply this raw vector to ⁠$write_input()⁠ again, until it is fully written, and then the return value will be raw(0) (invisibly).

Usage

process$write_input(str, sep = "\n")

Arguments

Returns

Leftover text (as a raw vector), that was not written.

Method get_input_file()

⁠$get_input_file()⁠ if the stdin argument was a filename, this returns the absolute path to the file. If stdin was "|" or NULL, this simply returns that value.

Usage

process$get_input_file()

Method get_output_file()

⁠$get_output_file()⁠ if the stdout argument was a filename, this returns the absolute path to the file. If stdout was "|" or NULL, this simply returns that value.

Usage

process$get_output_file()

Method get_error_file()

⁠$get_error_file()⁠ if the stderr argument was a filename, this returns the absolute path to the file. If stderr was "|" or NULL, this simply returns that value.

Usage

process$get_error_file()

Method poll_io()

⁠$poll_io()⁠ polls the process's connections for I/O. See more in the Polling section, and see also the poll() function to poll on multiple processes.

Usage

process$poll_io(timeout)

Arguments

Method get_poll_connection()

⁠$get_poll_connetion()⁠ returns the poll connection, if the process has one.

Usage

process$get_poll_connection()

Method get_result()

⁠$get_result()⁠ returns the result of the post processesing function. It can only be called once the process has finished. If the process has no post-processing function, then NULL is returned.

Usage

process$get_result()

Method as_ps_handle()

⁠$as_ps_handle()⁠ returns a ps::ps_handle object, corresponding to the process.

Usage

process$as_ps_handle()

Method get_name()

Calls ps::ps_name() to get the process name.

Usage

process$get_name()

Method get_exe()

Calls ps::ps_exe() to get the path of the executable.

Usage

process$get_exe()

Method get_cmdline()

Calls ps::ps_cmdline() to get the command line.

Usage

process$get_cmdline()

Method get_status()

Calls ps::ps_status() to get the process status.

Usage

process$get_status()

Method get_username()

calls ps::ps_username() to get the username.

Usage

process$get_username()

Method get_wd()

Calls ps::ps_cwd() to get the current working directory.

Usage

process$get_wd()

Method get_cpu_times()

Calls ps::ps_cpu_times() to get CPU usage data.

Usage

process$get_cpu_times()

Method get_memory_info()

Calls ps::ps_memory_info() to get memory data.

Usage

process$get_memory_info()

Method suspend()

Calls ps::ps_suspend() to suspend the process.

Usage

process$suspend()

Method resume()

Calls ps::ps_resume() to resume a suspended process.

Usage

process$resume()

Examples

p <- process$new("sleep", "2")
p$is_alive()
p
p$kill()
p$is_alive()

p <- process$new("sleep", "1")
p$is_alive()
Sys.sleep(2)
p$is_alive()

Description

run provides an interface similar to base::system() and base::system2(), but based on the process class. This allows some extra features, see below.

Usage

run(
  command = NULL,
  args = character(),
  error_on_status = TRUE,
  wd = NULL,
  echo_cmd = FALSE,
  echo = FALSE,
  spinner = FALSE,
  timeout = Inf,
  stdout = "|",
  stderr = "|",
  stdout_line_callback = NULL,
  stdout_callback = NULL,
  stderr_line_callback = NULL,
  stderr_callback = NULL,
  stderr_to_stdout = FALSE,
  env = NULL,
  windows_verbatim_args = FALSE,
  windows_hide_window = FALSE,
  encoding = "",
  cleanup_tree = FALSE,
  ...
)

Arguments

Details

run supports

• Specifying a timeout for the command. If the specified time has passed, and the process is still running, it will be killed (with all its child processes).

• Calling a callback function for each line or each chunk of the standard output and/or error. A chunk may contain multiple lines, and can be as short as a single character.

• Cleaning up the subprocess, or the whole process tree, before exiting.

Value

A list with components:

• status The exit status of the process. If this is NA, then the process was killed and had no exit status.

• stdout The standard output of the command, in a character scalar.

• stderr The standard error of the command, in a character scalar.

• timeout Whether the process was killed because of a timeout.

Callbacks

Some notes about the callback functions. The first argument of a callback function is a character scalar (length 1 character), a single output or error line. The second argument is always the process object. You can manipulate this object, for example you can call ⁠$kill()⁠ on it to terminate it, as a response to a message on the standard output or error.

Error conditions

run() throws error condition objects if the process is interrupted, timeouts or fails (if error_on_status is TRUE):

• On interrupt, a condition with classes system_command_interrupt, interrupt, condition is signalled. This can be caught with tryCatch(..., interrupt = ...).

• On timeout, a condition with classes system_command_timeout_error, system_command_error, error, condition is thrown.

• On error (if error_on_status is TRUE), an error with classes system_command_status_error, system_command_error, error, condition is thrown.

All of these conditions have the fields:

• message: the error message,

• stderr: the standard error of the process, or the standard output of the process if stderr_to_stdout was TRUE.

• call: the captured call to run().

• echo: the value of the echo argument.

• stderr_to_stdout: the value of the stderr_to_stdout argument.

• status: the exit status for system_command_status_error errors.

Examples

# This works on Unix systems
run("ls")
system.time(run("sleep", "10", timeout = 1, error_on_status = FALSE))
system.time(
  run(
    "sh", c("-c", "for i in 1 2 3 4 5; do echo $i; sleep 1; done"),
    timeout = 2, error_on_status = FALSE
  )
)


# This works on Windows systems, if the ping command is available
run("ping", c("-n", "1", "127.0.0.1"))
run("ping", c("-n", "6", "127.0.0.1"), timeout = 1,
    error_on_status = FALSE)