Learn R Programming

base (version 3.3)

system: 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)

Arguments

command
the system command to be invoked, as a character string.
intern
a logical (not NA) which indicates whether to capture the output of the command as an Rcharacter vector.
ignore.stdout, ignore.stderr
a logical (not NA) indicating whether messages written to stdout or stderr should be ignored.
wait
a logical (not NA) indicating whether the Rinterpreter should wait for the command to finish, or run it asynchronously. This will be ignored (and the interpreter will always wait) if intern = TRUE.
input
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.
show.output.on.console, minimized, invisible
arguments that are accepted on Windows but ignored on this platform, with a warning.
show.output.on.console
logical (not NA), indicates whether to capture the output of the command and show it on the Rconsole (not used by Rterm, which shows the output in the terminal unless wait is false).
minimized
logical (not NA), indicates whether a command window should be displayed initially as a minimized window.
invisible
logical (not NA), indicates whether a command window should be visible on the screen.

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.) If the command could not be run an Rerror is generated. #ifdef windows Under the Rgui console intern = TRUE also captures stderr unless ignore.stderr = TRUE. #endif 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. 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). #ifdef windows 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 Rconsole (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. #endif

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 OS X GUI's console, but not on some others).

Interaction with the command

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 Rconsole. Rwill 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.

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 Rfunction 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-alikesystemlaunches a shell which then runscommand. On Windows the command is run directly -- useshellfor an interface which runscommandviaa 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 insystem(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 tostdoutandstderrwhen not captured depends on howRis running: Windows batch commands behave like a Unix-alike, but from the Windows GUI they are generally lost.system(intern = TRUE)capturesstderrwhen run from the Windows GUI console unlessignore.stderr = TRUE.
  • The behaviour on error is different in subtle ways (and has differed betweenRversions).
  • The quoting conventions forcommanddiffer, butshQuoteis a portable interface.
  • Argumentsshow.output.on.console,minimized,invisibleonly do something on Windows (and are most relevant toRguithere).
  • 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. #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.)

    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 Rbin directory, the working directory and the Windows system directories before PATH. #endif #ifdef unix 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 Rcharacter 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. #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 system to ascertain if a command can be run --- Sys.which is more suitable.

    See Also

    #ifdef windows shell or shell.exec for a less raw interface. #endif #ifdef unix man system and man sh for how this is implemented on the OS in use. #endif

    .Platform for platform-specific variables.

    pipe to set up a pipe connection.

    Examples

    Run this code
    # launch an editor, wait for it to quit
    system("notepad myfile.txt")
    # launch your favourite shell:
    system(Sys.getenv("COMSPEC"))
    ## note the two sets of quotes here:
    system(paste('"c:/Program Files/Mozilla Firefox/firefox.exe"',
                 '-url cran.r-project.org'), wait = FALSE)

    Run the code above in your browser using DataLab