run
From processx v1.0.0.9000
by Gábor Csárdi
Run external command, and wait until finishes
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(), commandline = NULL,
error_on_status = TRUE, echo = FALSE, spinner = FALSE, timeout = Inf,
stdout_callback = NULL, stderr_callback = NULL, check_interval = 0.01)
Arguments
- command
- Character scalar, the command to run. It will be escaped via base::shQuote.
- args
- Character vector, arguments to the command. They will be escaped via base::shQuote.
- commandline
- A character scalar, a full command line. No escaping will be performed on it.
- error_on_status
- Whether to throw an error if the command returns
with a non-zero status, or it is interrupted. The error clases are
system_command_status_error
andsystem_command_timeout_error
, respectively, and both errors have classsystem_command_error
as well. - echo
- Whether to print the command, 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.
- spinner
- Whether to a reassusing spinner while the process is running.
- timeout
- Timeout for the process, in seconds, or as a
difftime
object. If it is not finished before this, it will be killed. - stdout_callback
NULL
, or a function to call for every line of the standard output. See more below.- stderr_callback
NULL
, or a function to call for every line of the standard error. See more below.- check_interval
- How often to check on the process for output.
This is only used if the process had no output at the last check.
If a process continuously produces output, then
run
does not wait at all.
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 of the standard output and/or error.
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 vector.
- stderr The standard error of the command, in a character vector.
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.
Examples
## Different examples for Unix and Windows
if (.Platform$OS.type == "unix") {
run("ls")
system.time(run(commandline = "sleep 10", timeout = 1,
error_on_status = FALSE))
system.time(
run(
commandline = "for i in 1 2 3 4 5; do echo $i; sleep 1; done",
timeout=2, error_on_status = FALSE
)
)
} else {
run(commandline = "ping -n 1 127.0.0.1")
run(commandline = "ping -n 6 127.0.0.1", timeout = 1,
error_on_status = FALSE)
}
Community examples
Looks like there are no examples yet.