% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/run.R
\name{run}
\alias{run}
\title{Run external command, and wait until finishes}
\usage{
run(
  command = NULL,
  args = character(),
  error_on_status = TRUE,
  wd = NULL,
  echo_cmd = FALSE,
  echo = FALSE,
  spinner = FALSE,
  timeout = Inf,
  stdout = "|",
  stderr = "|",
  stdout_line_callback = NULL,
  stdout_callback = NULL,
  stderr_line_callback = NULL,
  stderr_callback = NULL,
  stderr_to_stdout = FALSE,
  env = NULL,
  windows_verbatim_args = FALSE,
  windows_hide_window = FALSE,
  encoding = "",
  cleanup_tree = FALSE,
  ...
)
}
\arguments{
\item{command}{Character scalar, the command to run. If you are
running \code{.bat} or \code{.cmd} files on Windows, make sure you read the
'Batch files' section in the \link{process} manual page.}

\item{args}{Character vector, arguments to the command.}

\item{error_on_status}{Whether to throw an error if the command returns
with a non-zero status, or it is interrupted. The error classes are
\code{system_command_status_error} and \code{system_command_timeout_error},
respectively, and both errors have class \code{system_command_error} as
well. See also "Error conditions" below.}

\item{wd}{Working directory of the process. If \code{NULL}, the current
working directory is used.}

\item{echo_cmd}{Whether to print the command to run to the screen.}

\item{echo}{Whether to print the standard output and error
to the screen. Note that the order of the standard output and error
lines are not necessarily correct, as standard output is typically
buffered. If the standard output and/or error is redirected to a
file or they are ignored, then they also not echoed.}

\item{spinner}{Whether to show a reassuring spinner while the process
is running.}

\item{timeout}{Timeout for the process, in seconds, or as a \code{difftime}
object. If it is not finished before this, it will be killed.}

\item{stdout}{What to do with the standard output. By default it
is collected in the result, and you can also use the
\code{stdout_line_callback} and \code{stdout_callback} arguments to pass
callbacks for output. If it is the empty string (\code{""}), then
the child process inherits the standard output stream of the
R process. (If the main R process does not have a standard output
stream, e.g. in RGui on Windows, then an error is thrown.)
If it is \code{NULL}, then standard output is discarded. If it is a string
other than \code{"|"} and \code{""}, then it is taken as a file name and the
output is redirected to this file.}

\item{stderr}{What to do with the standard error. By default it
is collected in the result, and you can also use the
\code{stderr_line_callback} and \code{stderr_callback} arguments to pass
callbacks for output. If it is the empty string (\code{""}), then
the child process inherits the standard error stream of the
R process. (If the main R process does not have a standard error
stream, e.g. in RGui on Windows, then an error is thrown.)
If it is \code{NULL}, then standard error is discarded. If it is a string
other than \code{"|"} and \code{""}, then it is taken as a file name and the
standard error is redirected to this file.}

\item{stdout_line_callback}{\code{NULL}, or a function to call for every
line of the standard output. See \code{stdout_callback} and also more
below.}

\item{stdout_callback}{\code{NULL}, or a function to call for every chunk
of the standard output. A chunk can be as small as a single character.
At most one of \code{stdout_line_callback} and \code{stdout_callback} can be
non-\code{NULL}.}

\item{stderr_line_callback}{\code{NULL}, or a function to call for every
line of the standard error. See \code{stderr_callback} and also more
below.}

\item{stderr_callback}{\code{NULL}, or a function to call for every chunk
of the standard error. A chunk can be as small as a single character.
At most one of \code{stderr_line_callback} and \code{stderr_callback} can be
non-\code{NULL}.}

\item{stderr_to_stdout}{Whether to redirect the standard error to the
standard output. Specifying \code{TRUE} here will keep both in the
standard output, correctly interleaved. However, it is not possible
to deduce where pieces of the output were coming from. If this is
\code{TRUE}, the standard error callbacks  (if any) are never called.}

\item{env}{Environment variables of the child process. If \code{NULL},
the parent's environment is inherited. On Windows, many programs
cannot function correctly if some environment variables are not
set, so we always set \code{HOMEDRIVE}, \code{HOMEPATH}, \code{LOGONSERVER},
\code{PATH}, \code{SYSTEMDRIVE}, \code{SYSTEMROOT}, \code{TEMP}, \code{USERDOMAIN},
\code{USERNAME}, \code{USERPROFILE} and \code{WINDIR}. To append new environment
variables to the ones set in the current process, specify
\code{"current"} in \code{env}, without a name, and the appended ones with
names. The appended ones can overwrite the current ones.}

\item{windows_verbatim_args}{Whether to omit the escaping of the
command and the arguments on windows. Ignored on other platforms.}

\item{windows_hide_window}{Whether to hide the window of the
application on windows. Ignored on other platforms.}

\item{encoding}{The encoding to assume for \code{stdout} and
\code{stderr}. By default the encoding of the current locale is
used. Note that \code{processx} always reencodes the output of
both streams in UTF-8 currently.}

\item{cleanup_tree}{Whether to clean up the child process tree after
the process has finished.}

\item{...}{Extra arguments are passed to \code{process$new()}, see
\link{process}. Note that you cannot pass \code{stout} or \code{stderr} here,
because they are used internally by \code{run()}. You can use the
\code{stdout_callback}, \code{stderr_callback}, etc. arguments to manage
the standard output and error, or the \link{process} class directly
if you need more flexibility.}
}
\value{
A list with components:
\itemize{
\item status The exit status of the process. If this is \code{NA}, then the
process was killed and had no exit status.
\item stdout The standard output of the command, in a character scalar.
\item stderr The standard error of the command, in a character scalar.
\item timeout Whether the process was killed because of a timeout.
}
}
\description{
\code{run} provides an interface similar to \code{\link[base:system]{base::system()}} and
\code{\link[base:system2]{base::system2()}}, but based on the \link{process} class. This allows some
extra features, see below.
}
\details{
\code{run} supports
\itemize{
\item Specifying a timeout for the command. If the specified time has
passed, and the process is still running, it will be killed
(with all its child processes).
\item Calling a callback function for each line or each chunk of the
standard output and/or error. A chunk may contain multiple lines, and
can be as short as a single character.
\item Cleaning up the subprocess, or the whole process tree, before exiting.
}
}
\section{Callbacks}{


Some notes about the callback functions. The first argument of a
callback function is a character scalar (length 1 character), a single
output or error line. The second argument is always the \link{process}
object. You can manipulate this object, for example you can call
\verb{$kill()} on it to terminate it, as a response to a message on the
standard output or error.
}

\section{Error conditions}{


\code{run()} throws error condition objects if the process is interrupted,
timeouts or fails (if \code{error_on_status} is \code{TRUE}):
\itemize{
\item On interrupt, a condition with classes \code{system_command_interrupt},
\code{interrupt}, \code{condition} is signalled. This can be caught with
\code{tryCatch(..., interrupt = ...)}.
\item On timeout, a condition with classes \code{system_command_timeout_error},
\code{system_command_error}, \code{error}, \code{condition} is thrown.
\item On error (if \code{error_on_status} is \code{TRUE}), an error with classes
\code{system_command_status_error}, \code{system_command_error}, \code{error},
\code{condition} is thrown.
}

All of these conditions have the fields:
\itemize{
\item \code{message}: the error message,
\item \code{stderr}: the standard error of the process, or the standard output
of the process if \code{stderr_to_stdout} was \code{TRUE}.
\item \code{call}: the captured call to \code{run()}.
\item \code{echo}: the value of the \code{echo} argument.
\item \code{stderr_to_stdout}: the value of the \code{stderr_to_stdout} argument.
\item \code{status}: the exit status for \code{system_command_status_error} errors.
}
}

\examples{
\dontshow{if (.Platform$OS.type == "unix") (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
# This works on Unix systems
run("ls")
system.time(run("sleep", "10", timeout = 1, error_on_status = FALSE))
system.time(
  run(
    "sh", c("-c", "for i in 1 2 3 4 5; do echo $i; sleep 1; done"),
    timeout = 2, error_on_status = FALSE
  )
)
\dontshow{\}) # examplesIf}
\dontshow{if (FALSE) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
# This works on Windows systems, if the ping command is available
run("ping", c("-n", "1", "127.0.0.1"))
run("ping", c("-n", "6", "127.0.0.1"), timeout = 1,
    error_on_status = FALSE)
\dontshow{\}) # examplesIf}
}