The R Project SVN R

\name{system}
\alias{system}
\alias{unix}
\title{Invoke a System Command}
\usage{
system(command, intern = FALSE, wait = TRUE, input = NULL,
       show.output.on.console = FALSE,
       minimized = FALSE, invisible = FALSE)
}
\arguments{
    \item{command}{the system command to be invoked, as a string.}
    \item{intern}{a logical, indicates whether to make the output of the
    command an \R object.}
    \item{wait}{should the \R interpreter wait for the command to finish?
    The default is to wait, and the interpreter will always wait if
    \code{intern = TRUE}.}
    \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{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 \code{Rterm}, which captures the output unless \code{wait}
      is false).}
    \item{minimized}{a logical, indicates whether the command window
      should be initially displayed as a minimized window.}
    \item{invisible}{a logical, indicates whether the command window
      should be visible on the screen.}
}
\description{
    \code{system} invokes the system command specified by \code{command}.
}
\value{
  If \code{intern = TRUE}, a character vector giving the output of the
  command, one line per character string. If the command could not be
  run or gives an error a \R error is generated.
  (Output ines of more that 8096 characters will be split.)

  If \code{intern = FALSE}, the return value is a error code, given the
  invisible attribute (so needs to be printed explicitly). If the
  command could not be run for any reason, the value is \code{-1} and
  an \R warning is generated. Otherwise if \code{wait = FALSE} the value
  is the error code returned by the command, and if \code{wait = TRUE}
  it is the zero (the conventional success value),

  If \code{intern = FALSE} and \code{show.output.on.console = TRUE}
  the text output from a command that is a console application will
  appear in the \R console (\code{Rgui}) or the window running \R
  (\code{Rterm}).
}
\details{
  \code{cmd} is parsed as a command plus arguments separated by spaces.
  So if the path to the command contains spaces, it must be quoted.
  See the examples.

  The command is run directly as a Windows command by the Windows API
  call \code{CreateProcess}: extensions of \code{.exe}, \code{.com},
  \code{.cmd} and \code{.bat} are tried in turn if none
  is supplied. (To use DOS internal commands use
  \code{paste(Sys.getenv("COMSPEC"),"/c",cmd)}.)
  The search path for \code{command}
  may be system-dependent: it will include the \R \code{bin}
  directory, the working directory and the Windows system directories
  before \code{PATH}.

  Precisely what is seen by the user depends on whether \code{Rgui} or
  \code{Rterm} is being used.  For \code{Rgui} a new console will
  always be used, so a commands window will appear for the duration of
  console applications unless \code{invisible} is true. For
  \code{Rterm} a separate commands window
  will appear for console applications only if \code{wait = FALSE}.

  \code{unix} is a \emph{deprecated} alternative, available for
  backwards compatibility.
}
\section{Warning}{
    The command cannot be interrupted by the \R process.

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

\seealso{\code{\link{shell}} or \code{\link{shell.exec}} for a less raw
interface.}

\examples{
# launch an editor, wait for it to quit
\dontrun{system("notepad myfile.txt")}
# launch a Windows 9x process monitor (from Win9x KernelToys)
\dontrun{system("wintop", wait = FALSE)}
# launch your favourite shell:
\dontrun{system(Sys.getenv("COMSPEC"))}
\dontrun{
system(paste('"c:/Program Files/Netscape/Netscape 6/netscp6.exe"',
             '-url cran.r-project.org'), wait = FALSE)}
}
\keyword{interface}
\keyword{file}
\keyword{utilities}