Function std.process.spawnProcess
Spawns a new process, optionally assigning it an arbitrary set of standard input, output, and error streams.
Pid spawnProcess
(
scope const(char[])[] args,
File stdin = makeGlobal(),
File stdout = makeGlobal(),
File stderr = makeGlobal(),
const(string[string]) env = cast(const(string[string]))null,
Config config = Config(Flags
scope const(char[]) workDir = null
) @safe;
Pid spawnProcess
(
scope const(char[])[] args,
const(string[string]) env,
Config config = Config(Flags
scope const(char)[] workDir = null
) @trusted;
Pid spawnProcess
(
scope const(char)[] program,
File stdin = makeGlobal(),
File stdout = makeGlobal(),
File stderr = makeGlobal(),
const(string[string]) env = cast(const(string[string]))null,
Config config = Config(Flags
scope const(char)[] workDir = null
) @trusted;
Pid spawnProcess
(
scope const(char)[] program,
const(string[string]) env,
Config config = Config(Flags
scope const(char)[] workDir = null
) @trusted;
The function returns immediately, leaving the child process to execute
in parallel with its parent. It is recommended to always call wait
on the returned Pid unless the process was spawned with
Config flag, as detailed in the documentation for wait.
Command line
There are four overloads of this function. The first two take an array
of strings, args, which should contain the program name as the
zeroth element and any command-line arguments in subsequent elements.
The third and fourth versions are included for convenience, and may be
used when there are no command-line arguments. They take a single string,
program, which specifies the program name.
Unless a directory is specified in args[0] or program,
spawnProcess will search for the program in a platform-dependent
manner. On POSIX systems, it will look for the executable in the
directories listed in the PATH environment variable, in the order
they are listed. On Windows, it will search for the executable in
the following sequence:
- The directory from which the application loaded.
- The current directory for the parent process.
- The 32-bit Windows system directory.
- The 16-bit Windows system directory.
- The Windows directory.
- The directories listed in the PATH environment variable.
// Run an executable called "prog" located in the current working
// directory:
auto pid = spawnProcess("./prog");
scope(exit) wait(pid);
// We can do something else while the program runs. The scope guard
// ensures that the process is waited for at the end of the scope.
...
// Run DMD on the file "myprog.d", specifying a few compiler switches:
auto dmdPid = spawnProcess(["dmd", "-O", "-release", "-inline", "myprog.d" ]);
if (wait(dmdPid) != 0)
writeln("Compilation failed!");Environment variables
By default, the child process inherits the environment of the parent
process, along with any additional variables specified in the env
parameter. If the same variable exists in both the parent's environment
and in env, the latter takes precedence.
If the Config flag is set in config, the child
process will not inherit the parent's environment. Its entire
environment will then be determined by env.
wait(spawnProcess("myapp", ["foo" : "bar"], ConfigStandard streams
The optional arguments stdin, stdout and stderr may
be used to assign arbitrary File objects as the standard
input, output and error streams, respectively, of the child process. The
former must be opened for reading, while the latter two must be opened for
writing. The default is for the child process to inherit the standard
streams of its parent.
// Run DMD on the file myprog.d, logging any error messages to a
// file named errors.log.
auto logFile = File("errors.log", "w");
auto pid = spawnProcess(["dmd", "myprog.d"],
stdin,
stdout,
logFile);
if (wait(pid) != 0)
writeln("Compilation failed. See errors.log for details.");Note that if you pass a File object that is not
one of the standard input/output/error streams of the parent process,
that stream will by default be closed in the parent process when
this function returns. See the Config documentation below for
information about how to disable this behaviour.
Beware of buffering issues when passing File objects to
spawnProcess. The child process will inherit the low-level raw
read/write offset associated with the underlying file descriptor, but
it will not be aware of any buffered data. In cases where this matters
(e.g. when a file should be aligned before being passed on to the
child process), it may be a good idea to use unbuffered streams, or at
least ensure all relevant buffers are flushed.
Parameters
| Name | Description |
|---|---|
| args | An array which contains the program name as the zeroth element and any command-line arguments in the following elements. |
| stdin | The standard input stream of the child process.
This can be any File that is opened for reading.
By default the child process inherits the parent's input
stream. |
| stdout | The standard output stream of the child process.
This can be any File that is opened for writing.
By default the child process inherits the parent's output stream. |
| stderr | The standard error stream of the child process.
This can be any File that is opened for writing.
By default the child process inherits the parent's error stream. |
| env | Additional environment variables for the child process. |
| config | Flags that control process creation. See Config
for an overview of available flags. |
| workDir | The working directory for the new process. By default the child process inherits the parent's working directory. |
Returns
A Pid object that corresponds to the spawned process.
Throws
ProcessException on failure to start the process.
StdioException on failure to pass one of the streams
to the child process (Windows only).
RangeError if args is empty.
Authors
Lars Tandle Kyllingstad, Steven Schveighoffer, Vladimir Panteleev