system invokes the OS command specified by command.
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)the system command to be invoked, as a character string.
a logical (not NA) which indicates whether to
capture the output of the command as an R character vector.
a logical (not NA)
indicating whether messages written to stdout or
stderr should be ignored.
a logical (not NA) indicating whether the R
interpreter should wait for the command to finish, or run it
asynchronously. This will be ignored (and the interpreter will
always wait) if intern = TRUE. When running the command
asynchronously, no output will be displayed on the Rgui
console in Windows (it will be dropped, instead).
if a character vector is supplied, this is copied one
string per line to a temporary file, and the standard input of
command is redirected to the file.
timeout in seconds, ignored if 0. This is a limit for the
elapsed time running command in a separate process. Fractions
of seconds are ignored.
arguments that are accepted on Windows but ignored on this platform, with a warning.
logical (not NA), indicates
whether to capture the output of the command and show it on the R
console (not used by Rterm, which shows the output in the
terminal unless wait is false, and on some systems even when
wait is false).
logical (not NA), indicates whether a
command window should be displayed initially as a minimized window.
logical (not NA), indicates whether a
command window should be visible on the screen.
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.) If the command could not be run an R
error is generated.
Under the Rgui console intern = TRUE also captures
stderr unless ignore.stderr = TRUE.
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.
Some Windows commands return out-of-range status values
(e.g., -1) and so only the bottom 16 bits of the value are used.
If intern = FALSE, wait = TRUE, show.output.on.console = TRUE the
stdout and stderr (unless ignore.stdout = TRUE or
ignore.stderr = TRUE) output from a command that is a
‘console application’ should appear in the R console
(Rgui) or the window running R (Rterm).
Not all Windows executables properly respect redirection of output, or
may only do so from a console application such as Rterm and not
from Rgui: for example, fc.exe was among these in the past,
but we have had more success recently.
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).
Precisely what is seen by the user depends on the optional parameters,
whether Rgui or Rterm is being used, and whether a
console command or GUI application is run by the command.
By default nothing will be seen in either front-end until the command finishes and the output is displayed.
For console commands Rgui will open a new ‘console’, so
if invisible = FALSE, a commands window will appear for the
duration of the command. For Rterm a separate commands window
will appear for console applications only if wait = FALSE and
invisible = FALSE.
GUI applications will not display in either front-end unless
invisible is false.
It is possible to interrupt a running command being waited for from
the keyboard (using the Esc key in Rgui or Ctrl-C
in Rterm) or from the Rgui menu: this should at least
return control to the R console. R will attempt to shut down the
process cleanly, but may need to force it to terminate, with the
possibility of losing unsaved work, etc.
Do not try to run console applications that require user
input from Rgui setting intern = TRUE or
show.output.on.console = TRUE. They will not work.
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 runs command. On
Windows the command is run directly -- use shell for an
interface which runs command via a shell (by default
the Windows shell cmd.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), and
system2 (or shell) must be used on Windows.
What happens to stdout and stderr 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 unless ignore.stderr =
TRUE.
The behaviour on error is different in subtle ways (and has differed between R versions).
The quoting conventions for command differ, but
shQuote is a portable interface.
Arguments show.output.on.console, minimized,
invisible only do something on Windows (and are most relevant
to Rgui there).
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.
Only double quotes are allowed on Windows: see the examples. (Note: a
Windows path name cannot contain a double quote, so we do not need to
worry about escaping embedded quotes.)
command must be an executable (extensions .exe,
.com) or a batch file (extensions .cmd and .bat):
these extensions are tried in turn if none is supplied. This means
that redirection, pipes, DOS internal commands, … cannot be used:
see shell if you want to pass a shell command-line.
The search path for command may be system-dependent: it will
include the R bin directory, the working directory and the
Windows system directories before PATH.
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.
shell or shell.exec for a less raw
interface.
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.
# NOT RUN {
# list all files in the current directory using the -F flag
# }
# NOT RUN {
system("ls -F")
# }
# NOT RUN {
# 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.
# }
Run the code above in your browser using DataLab