| % File src/library/base/man/system.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 1995-2018 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{system} |
| \alias{system} |
| #ifdef unix |
| \alias{shell} |
| #endif |
| \title{Invoke a System Command} |
| \description{ |
| \code{system} invokes the OS command specified by \code{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) |
| } |
| \arguments{ |
| \item{command}{the system command to be invoked, as a character string.} |
| \item{intern}{a logical (not \code{NA}) which indicates whether to |
| capture the output of the command as an \R character vector.} |
| \item{ignore.stdout, ignore.stderr}{a logical (not \code{NA}) |
| indicating whether messages written to \file{stdout} or |
| \file{stderr} should be ignored.} |
| \item{wait}{a logical (not \code{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 \code{intern = TRUE}. When running the command |
| asynchronously, no output will be displayed on the \code{Rgui} |
| console in Windows (it will be dropped, instead).} |
| \item{input}{if a character vector is supplied, this is copied one |
| string per line to a temporary file, and the standard input of |
| \code{command} is redirected to the file.} |
| \item{timeout}{timeout in seconds, ignored if 0. This is a limit for the |
| elapsed time running \code{command} in a separate process. Fractions |
| of seconds are ignored.} |
| #ifdef unix |
| \item{show.output.on.console, minimized, invisible}{arguments |
| that are accepted on Windows but ignored on this platform, with a |
| warning.} |
| #endif |
| #ifdef windows |
| \item{show.output.on.console}{logical (not \code{NA}), indicates |
| whether to capture the output of the command and show it on the \R |
| console (not used by \code{Rterm}, which shows the output in the |
| terminal unless \code{wait} is false, and on some systems even when |
| \code{wait} is false).} |
| \item{minimized}{logical (not \code{NA}), indicates whether a |
| command window should be displayed initially as a minimized window.} |
| \item{invisible}{logical (not \code{NA}), indicates whether a |
| command window should be visible on the screen.} |
| #endif |
| } |
| \details{ |
| This interface has become rather complicated over the years: see |
| \code{\link{system2}} for a more portable and flexible interface |
| which is recommended for new code. |
| |
| \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.\sspace{}by |
| \code{\link{shQuote}}. |
| #ifdef windows |
| 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.) |
| |
| \code{command} must be an executable (extensions \file{.exe}, |
| \file{.com}) or a batch file (extensions \file{.cmd} and \file{.bat}): |
| these extensions are tried in turn if none is supplied. This means |
| that redirection, pipes, DOS internal commands, \dots cannot be used: |
| see \code{\link{shell}} if you want to pass a shell command-line. |
| |
| The search path for \code{command} may be system-dependent: it will |
| include the \R \file{bin} directory, the working directory and the |
| Windows system directories before \env{PATH}. |
| #endif |
| #ifdef unix |
| Unix-alikes pass the command line to a shell (normally \file{/bin/sh}, |
| and POSIX requires that shell), so \code{command} can be anything the |
| shell regards as executable, including shell scripts, and it can |
| contain multiple commands separated by \code{;}. |
| |
| On Windows, \code{system} does not use a shell and there is a separate |
| function \code{shell} which passes command lines to a shell. |
| |
| If \code{intern} is \code{TRUE} then \code{popen} is used to invoke the |
| command and the output collected, line by line, into an \R |
| \code{\link{character}} vector. If \code{intern} is \code{FALSE} then |
| the C function \code{system} is used to invoke the command. |
| |
| \code{wait} is implemented by appending \code{&} to the command: this |
| is in principle shell-dependent, but required by POSIX and so widely |
| supported. |
| #endif |
| |
| When \code{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 \code{wait = TRUE}. |
| |
| #ifdef unix |
| Timeouts cannot be used with interactive commands: the command is run with |
| standard input redirected from \code{/dev/null} and it must not modify |
| terminal settings. As long as tty \code{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 \code{user.child} and |
| \code{sys.child} element of \code{proc_time} returned by \code{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. |
| #endif |
| |
| 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 \code{system} to ascertain if a |
| command can be run --- \code{\link{Sys.which}} is more suitable. |
| } |
| |
| \value{ |
| If \code{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. |
| #ifdef windows |
| Under the \code{Rgui} console \code{intern = TRUE} also captures |
| \code{stderr} unless \code{ignore.stderr = TRUE}. |
| #endif |
| If \code{command} runs but gives a non-zero exit status this will be |
| reported with a warning and in the attribute \code{"status"} of the |
| result: an attribute \code{"errmsg"} may also be available. |
| |
| If \code{intern = FALSE}, the return value is an error code (\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 \code{127} and a warning is issued (as from \R 3.5.0). |
| Otherwise if \code{wait = TRUE} the value is the exit status returned |
| by the command, and if \code{wait = FALSE} it is \code{0} (the |
| conventional success value). |
| |
| If the command times out, a warning is reported and the exit status is |
| \code{124}. |
| #ifdef windows |
| Some Windows commands return out-of-range status values |
| (e.g., \code{-1}) and so only the bottom 16 bits of the value are used. |
| |
| If \code{intern = FALSE, wait = TRUE, show.output.on.console = TRUE} the |
| \file{stdout} and \file{stderr} (unless \code{ignore.stdout = TRUE} or |
| \code{ignore.stderr = TRUE}) output from a command that is a |
| \sQuote{console application} should appear in the \R console |
| (\code{Rgui}) or the window running \R (\code{Rterm}). |
| |
| Not all Windows executables properly respect redirection of output, or |
| may only do so from a console application such as \code{Rterm} and not |
| from \code{Rgui}: for example, \file{fc.exe} was among these in the past, |
| but we have had more success recently. |
| #endif |
| } |
| |
| #ifdef unix |
| \section{Stdout and stderr}{ |
| For command-line \R, error messages written to \file{stderr} will be |
| sent to the terminal unless \code{ignore.stderr = TRUE}. They can be |
| captured (in the most likely shells) by |
| \preformatted{ system("some command 2>&1", intern = TRUE) |
| } |
| |
| For GUIs, what happens to output sent to \file{stdout} or |
| \file{stderr} if \code{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). |
| } |
| #endif |
| |
| #ifdef windows |
| \section{Interaction with the command}{ |
| Precisely what is seen by the user depends on the optional parameters, |
| whether \code{Rgui} or \code{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 \code{Rgui} will open a new \sQuote{console}, so |
| if \code{invisible = FALSE}, a commands window will appear for the |
| duration of the command. For \code{Rterm} a separate commands window |
| will appear for console applications only if \code{wait = FALSE} and |
| \code{invisible = FALSE}. |
| |
| GUI applications will not display in either front-end unless |
| \code{invisible} is false. |
| |
| It is possible to interrupt a running command being waited for from |
| the keyboard (using the \samp{Esc} key in \code{Rgui} or \samp{Ctrl-C} |
| in \code{Rterm}) or from the \code{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 \code{Rgui} setting \code{intern = TRUE} or |
| \code{show.output.on.console = TRUE}. They will not work. |
| } |
| #endif |
| |
| \section{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 \code{system} behaves. |
| For the benefit of programmers, the more important ones are summarized |
| in this section. |
| |
| \itemize{ |
| \item The most important difference is that on a Unix-alike |
| \code{system} launches a shell which then runs \code{command}. On |
| Windows the command is run directly -- use \code{shell} for an |
| interface which runs \code{command} \emph{via} a shell (by default |
| the Windows shell \command{cmd.exe}, which has many differences from |
| a POSIX shell). |
| |
| This means that it cannot be assumed that redirection or piping will |
| work in \code{system} (redirection sometimes does, but we have seen |
| cases where it stopped working after a Windows security patch), and |
| \code{\link{system2}} (or \code{shell}) must be used on Windows. |
| |
| \item What happens to \code{stdout} and \code{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. \code{system(intern = TRUE)} captures \file{stderr} |
| when run from the Windows GUI console unless \code{ignore.stderr = |
| TRUE}. |
| |
| \item The behaviour on error is different in subtle ways (and has |
| differed between \R versions). |
| |
| \item The quoting conventions for \code{command} differ, but |
| \code{\link{shQuote}} is a portable interface. |
| |
| \item Arguments \code{show.output.on.console}, \code{minimized}, |
| \code{invisible} only do something on Windows (and are most relevant |
| to \command{Rgui} there). |
| } |
| } |
| \seealso{ |
| #ifdef windows |
| \code{\link{shell}} or \code{\link{shell.exec}} for a less raw |
| interface. |
| #endif |
| #ifdef unix |
| \command{man system} and \command{man sh} for how this is implemented |
| on the OS in use. |
| #endif |
| |
| \code{\link{.Platform}} for platform-specific variables. |
| |
| \code{\link{pipe}} to set up a pipe connection. |
| } |
| #ifdef unix |
| \examples{ |
| # list all files in the current directory using the -F flag |
| \dontrun{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. |
| } |
| #endif |
| #ifdef windows |
| \examples{ |
| # launch an editor, wait for it to quit |
| \dontrun{system("notepad myfile.txt")} |
| # launch your favourite shell: |
| \dontrun{system(Sys.getenv("COMSPEC"))} |
| \dontrun{ |
| ## note the two sets of quotes here: |
| system(paste('"c:/Program Files/Mozilla Firefox/firefox.exe"', |
| '-url cran.r-project.org'), wait = FALSE)} |
| } |
| #endif |
| \keyword{interface} |
| \keyword{file} |
| \keyword{utilities} |