system {base}R Documentation

Invoke a System Command

Description

system invokes the OS command specified by command.

Usage

system(command, intern = 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 string.
intern a logical (not NA) which indicates whether to make the output of the command an R object.
ignore.stderr a logical indicating whether error messages written to ‘stderr’ should be ignored.
wait a logical 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.
show.output.on.console a logical, indicates whether to capture the output of the command and show it on the R console (not used by Rterm, which captures the output unless wait is false).
minimized a logical, indicates whether the command window should be initially displayed as a minimized window.
invisible a logical, indicates whether the command window should be visible on the screen.

Details

command is parsed as a command plus arguments separated by spaces. So if the path to the command (or a filepath argument) 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.)

How the command is run differs by platform: Unix-alikes use a shell (‘/bin/sh’ by default), and Windows executes the command directly (extensions ‘.exe’, ‘.com’) or as a batch file (extensions ‘.cmd’ and ‘.bat’). (These extensions are tried in turn if none is supplied.) This means that redirection, pipes, ... cannot be used: see shell. (To use DOS internal commands use paste(Sys.getenv("COMSPEC"),"/c", cmd).)

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.

The ordering of arguments after the first two has changed from time to time: it is recommended to name all arguments after the first.

Value

If intern = TRUE, a character vector giving the output of the command, one line per character string. (Output lines of more than 8095 characters will be split.) If the command could not be run or gives an error an R error is generated. This also captures stderr on the RGui console unless ignore.stderr = TRUE.
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 -1. (An R warning is also generated.) Otherwise if wait = TRUE the value is the error code returned by the command, and if wait = FALSE it is 0 (the conventional success value). Some Windows commands return out-of-range error values (e.g. -1) and so only the bottom 16 bits of the value are used.
If intern = FALSE and show.output.on.console = TRUE the ‘stdout’ and ‘stderr’ (unless 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: known examples include ‘fc.exe’.

Interaction with the command

Precisely what is seen by the user depends on whether Rgui or Rterm is being used. For Rgui a new ‘console’ will always be used, so a commands window will appear for the duration of console applications unless invisible is true (which it is by default). For Rterm a separate commands window will appear for console applications only if wait = FALSE and invisible = FALSE.

If the R process is waiting for output from the command it is possible to interrupt the running command from the keyboard or Rgui menu: this should at least return control to the R console. Otherwise it it not possible to interrupt the running command.

Do not try to run console applications that require user input from Rgui setting intern = TRUE and/or show.output.on.console = TRUE. They will not work, may hang and then will probably hang Rgui too.

See Also

shell or shell.exec for a less raw interface.

.Platform for platform-specific variables.

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 2.9.1 Index]