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)

### 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 R character 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 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`.
`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.
`timeout` | 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.

`show.output.on.console` | 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).
`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.

### 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`. 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.

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`.

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.

### 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 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.

### 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 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.

### 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 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).

### See Also

`shell` or `shell.exec` for a less raw interface.

`.Platform` for platform-specific variables.

`pipe` to set up a pipe connection.

### Examples

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

[Package base version 3.5.1 Index]