Function std.process.spawnProcess

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, as detailed in the documentation for wait.

Prototypes

Pid spawnProcess(
  const(char[][]) args,
  File stdin = stdin,
  File stdout = stdout,
  File stderr = stderr,
  const(string[string]) env = cast(const(string[string]))null,
  Config config = cast(Config)0,
  const(char[]) workDir = null
) @trusted;

Pid spawnProcess(
  const(char[][]) args,
  const(string[string]) env,
  Config config = cast(Config)0,
  const(char[]) workDir = null
) @trusted;

Pid spawnProcess(
  const(char[]) program,
  File stdin = stdin,
  File stdout = stdout,
  File stderr = stderr,
  const(string[string]) env = cast(const(string[string]))null,
  Config config = cast(Config)0,
  const(char[]) workDir = null
) @trusted;

Pid spawnProcess(
  const(char[]) program,
  const(string[string]) env,
  Config config = cast(Config)0,
  const(char[]) workDir = null
) @trusted;

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 std.stdio.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"],
                        std.stdio.stdin,
                        std.stdio.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

Returns

A Pid object that corresponds to the spawned process.

Throws

ProcessException on failure to start the process.
std.stdio.StdioException on failure to pass one of the streams to the child process (Windows only).
core.exception.RangeError if args is empty.