View source code
Display the source code in std/process.d from which this page was generated on github.
Report a bug
If you spot a problem with this page, click here to create a Bugzilla issue.
Improve this page
Quickly fork, edit online, and submit a pull request for this page. Requires a signed-in GitHub account. This works well for small changes. If you'd like to make larger changes you may want to consider using local clone.

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.none, null),
  scope const(char[]) workDir = null
) @safe;

Pid spawnProcess (
  scope const(char[])[] args,
  const(string[string]) env,
  Config config = Config(Flags.none, null),
  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.none, null),
  scope const(char)[] workDir = null
) @trusted;

Pid spawnProcess (
  scope const(char)[] program,
  const(string[string]) env,
  Config config = Config(Flags.none, null),
  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.detached 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:

  1. The directory from which the application loaded.
  2. The current directory for the parent process.
  3. The 32-bit Windows system directory.
  4. The 16-bit Windows system directory.
  5. The Windows directory.
  6. 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.newEnv 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"], Config.newEnv));

Standard 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

NameDescription
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

License

Boost License 1.0.