system {base} | R Documentation |
Invoke a System Command
Description
system
invokes the OS command specified by command
.
Usage
system(command, intern = FALSE,
ignore.stdout = FALSE, ignore.stderr = FALSE,
wait = TRUE, input = NULL, show.output.on.console = TRUE,
minimized = FALSE, invisible = TRUE, timeout = 0,
receive.console.signals = wait)
Arguments
command |
the system command to be invoked, as a character string. |
intern |
a logical (not |
ignore.stdout , ignore.stderr |
a logical (not |
wait |
a logical (not |
input |
if a character vector is supplied, this is copied one
string per line to a temporary file, and the standard input of
|
timeout |
timeout in seconds, ignored if 0. This is a limit for the
elapsed time running |
receive.console.signals |
a logical (not |
show.output.on.console , minimized , invisible |
arguments that are accepted on Windows but ignored on this platform, with a warning. |
Details
This interface has become rather complicated over the years: see
system2
for a more portable and flexible interface
which is recommended for new code.
command
is parsed as a command plus arguments separated by
spaces. So if the path to the command (or a single argument such as a
file path) contains spaces, it must be quoted e.g. by
shQuote
.
Unix-alikes pass the command line to a shell (normally ‘/bin/sh’,
and POSIX requires that shell), so command
can be anything the
shell regards as executable, including shell scripts, and it can
contain multiple commands separated by ;
.
On Windows, system
does not use a shell and there is a separate
function shell
which passes command lines to a shell.
If intern
is TRUE
then popen
is used to invoke the
command and the output collected, line by line, into an R
character
vector. If intern
is FALSE
then
the C function system
is used to invoke the command.
wait
is implemented by appending &
to the command: this
is in principle shell-dependent, but required by POSIX and so widely
supported.
When timeout
is non-zero, the command is terminated after the given
number of seconds. The termination works for typical commands, but is not
guaranteed: it is possible to write a program that would keep running
after the time is out. Timeouts can only be set with wait = TRUE
.
Timeouts cannot be used with interactive commands: the command is run with
standard input redirected from ‘/dev/null’ and it must not modify
terminal settings. As long as tty tostop
option is disabled, which
it usually is by default, the executed command may write to standard
output and standard error. One cannot rely on that the execution time of
the child processes will be included into user.child
and
sys.child
element of proc_time
returned by proc.time
.
For the time to be included, all child processes have to be waited for by
their parents, which has to be implemented in the parent applications.
The ordering of arguments after the first two has changed from time to time: it is recommended to name all arguments after the first.
There are many pitfalls in using system
to ascertain if a
command can be run — Sys.which
is more suitable.
receive.console.signals = TRUE
is useful when running asynchronous
processes (using wait = FALSE
) to implement a synchronous operation.
In all other cases it is recommended to use the default.
Value
If intern = TRUE
, a character vector giving the output of the
command, one line per character string. (Output lines of more than
8095 bytes will be split on some systems.)
If the command could not be run an R error is generated.
If command
runs but gives a non-zero exit status this will be
reported with a warning and in the attribute "status"
of the
result: an attribute "errmsg"
may also be available.
If intern = FALSE
, the return value is an error code (0
for success), given the invisible attribute (so needs to be printed
explicitly). If the command could not be run for any reason, the
value is 127
and a warning is issued (as from R 3.5.0).
Otherwise if wait = TRUE
the value is the exit status returned
by the command, and if wait = FALSE
it is 0
(the
conventional success value).
If the command times out, a warning is reported and the exit status is
124
.
Stdout and stderr
For command-line R, error messages written to ‘stderr’ will be
sent to the terminal unless ignore.stderr = TRUE
. They can be
captured (in the most likely shells) by
system("some command 2>&1", intern = TRUE)
For GUIs, what happens to output sent to ‘stdout’ or
‘stderr’ if intern = FALSE
is interface-specific, and it
is unsafe to assume that such messages will appear on a GUI console
(they do on the macOS GUI's console, but not on some others).
Differences between Unix and Windows
How processes are launched differs fundamentally between Windows and
Unix-alike operating systems, as do the higher-level OS functions on
which this R function is built. So it should not be surprising that
there are many differences between OSes in how system
behaves.
For the benefit of programmers, the more important ones are summarized
in this section.
The most important difference is that on a Unix-alike
system
launches a shell which then runscommand
. On Windows the command is run directly – useshell
for an interface which runscommand
via a shell (by default the Windows shellcmd.exe
, which has many differences from a POSIX shell).This means that it cannot be assumed that redirection or piping will work in
system
(redirection sometimes does, but we have seen cases where it stopped working after a Windows security patch), andsystem2
(orshell
) must be used on Windows.What happens to
stdout
andstderr
when not captured depends on how R is running: Windows batch commands behave like a Unix-alike, but from the Windows GUI they are generally lost.system(intern = TRUE)
captures ‘stderr’ when run from the Windows GUI console unlessignore.stderr = TRUE
.The behaviour on error is different in subtle ways (and has differed between R versions).
The quoting conventions for
command
differ, butshQuote
is a portable interface.Arguments
show.output.on.console
,minimized
,invisible
only do something on Windows (and are most relevant toRgui
there).
See Also
man system
and man sh
for how this is implemented
on the OS in use.
.Platform
for platform-specific variables.
pipe
to set up a pipe connection.
Examples
# list all files in the current directory using the -F flag
## Not run: system("ls -F")
# t1 is a character vector, each element giving a line of output from who
# (if the platform has who)
t1 <- try(system("who", intern = TRUE))
try(system("ls fizzlipuzzli", intern = TRUE, ignore.stderr = TRUE))
# zero-length result since file does not exist, and will give warning.