run provides an interface similar to base::system() and
base::system2(), but based on the process class. This allows some
extra features, see below.
run(
command = NULL,
args = character(),
error_on_status = TRUE,
wd = NULL,
echo_cmd = FALSE,
echo = FALSE,
spinner = FALSE,
timeout = Inf,
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,
...
)Character scalar, the command to run.
Character vector, arguments to the command.
Whether to throw an error if the command returns
with a non-zero status, or it is interrupted. The error classes are
system_command_status_error and system_command_timeout_error,
respectively, and both errors have class system_command_error as
well. See also "Error conditions" below.
Working directory of the process. If NULL, the current
working directory is used.
Whether to print the command to run to the screen.
Whether to print the standard output and error to the screen. Note that the order of the standard output and error lines are not necessarily correct, as standard output is typically buffered.
Whether to show a reassuring spinner while the process is running.
Timeout for the process, in seconds, or as a difftime
object. If it is not finished before this, it will be killed.
NULL, or a function to call for every
line of the standard output. See stdout_callback and also more
below.
NULL, or a function to call for every chunk
of the standard output. A chunk can be as small as a single character.
At most one of stdout_line_callback and stdout_callback can be
non-NULL.
NULL, or a function to call for every
line of the standard error. See stderr_callback and also more
below.
NULL, or a function to call for every chunk
of the standard error. A chunk can be as small as a single character.
At most one of stderr_line_callback and stderr_callback can be
non-NULL.
Whether to redirect the standard error to the
standard output. Specifying TRUE here will keep both in the
standard output, correctly interleaved. However, it is not possible
to deduce where pieces of the output were coming from. If this is
TRUE, the standard error callbacks (if any) are never called.
Environment of the child process, a named character vector.
IF NULL, the environment of the parent is inherited.
Whether to omit the escaping of the command and the arguments on windows. Ignored on other platforms.
Whether to hide the window of the application on windows. Ignored on other platforms.
The encoding to assume for stdout and
stderr. By default the encoding of the current locale is
used. Note that processx always reencodes the output of
both streams in UTF-8 currently.
Whether to clean up the child process tree after the process has finished.
Extra arguments are passed to process$new(), see
process.
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.
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.
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.
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.
# NOT RUN {
# 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
)
)
# }
# NOT RUN {
# 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)
# }
Run the code above in your browser using DataCamp Workspace