Functions for starting and interacting with other processes, and for working with the current process' execution environment.
spawnProcess spawns a new process, optionally assigning it an arbitrary set of standard input, output, and error streams. The function returns immediately, leaving the child process to execute in parallel with its parent. All other functions in this module that spawn processes are built around spawnProcess.wait makes the parent process wait for a child process to terminate. In general one should always do this, to avoid child processes becoming "zombies" when the parent process exits. Scope guards are perfect for this – see the spawnProcess documentation for examples. tryWait is similar to wait, but does not block if the process has not yet terminated.pipeProcess also spawns a child process which runs in parallel with its parent. However, instead of taking arbitrary streams, it automatically creates a set of pipes that allow the parent to communicate with the child through the child's standard input, output, and/or error streams. This function corresponds roughly to C's popen function.execute starts a new process and waits for it to complete before returning. Additionally, it captures the process' standard output and error streams and returns the output of these as a string.spawnShell, pipeShell and executeShell work like spawnProcess, pipeProcess and execute, respectively, except that they take a single command string and run it through the current user's default command interpreter. executeShell corresponds roughly to C's system function.kill attempts to terminate a running process.| Runs program directly | Runs shell command | |
|---|---|---|
| Low-level process creation | spawnProcess | spawnShell |
| Automatic input/output redirection using pipes | pipeProcess | pipeShell |
| Execute and wait for completion, collect output | execute | executeShell |
pipe is used to create unidirectional pipes.environment is an interface through which the current process' environment variables can be read and manipulated.escapeShellCommand and escapeShellFileName are useful for constructing shell command lines in a portable way.Spawns a new process, optionally assigning it an arbitrary set of standard input, output, and error streams.
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.
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. 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: // 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!");
env parameter. If the same variable exists in both the parent's environment and in env, the latter takes precedence. 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));
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. char[][] args
| An array which contains the program name as the zeroth element and any command-line arguments in the following elements. |
File stdin
| The standard input stream of the child process. This can be any std.stdio.File that is opened for reading. By default the child process inherits the parent's input stream. |
File stdout
| The standard output stream of the child process. This can be any std.stdio.File that is opened for writing. By default the child process inherits the parent's output stream. |
File stderr
| The standard error stream of the child process. This can be any std.stdio.File that is opened for writing. By default the child process inherits the parent's error stream. |
string[string] env
| Additional environment variables for the child process. |
Config config
| Flags that control process creation. See Config for an overview of available flags. |
char[] workDir
| The working directory for the new process. By default the child process inherits the parent's working directory. |
Pid object that corresponds to the spawned process. 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.A variation on spawnProcess that runs the given command through the current user's preferred command interpreter (aka. shell).
The string command is passed verbatim to the shell, and is therefore subject to its rules about command structure, argument/filename quoting and escaping of special characters. The path to the shell executable defaults to nativeShell.
In all other respects this function works just like spawnProcess. Please refer to the spawnProcess documentation for descriptions of the other function parameters, the return value and any exceptions that may be thrown.
// Run the command/program "foo" on the file named "my file.txt", and // redirect its output into foo.log. auto pid = spawnShell(`foo "my file.txt" > foo.log`); wait(pid);
escapeShellCommand, which may be helpful in constructing a properly quoted and escaped shell command line for the current platform.Flags that control the behaviour of spawnProcess and spawnShell.
Use bitwise OR to combine flags.
auto logFile = File("myapp_error.log", "w");
// Start program, suppressing the console window (Windows only),
// redirect its error stream to logFile, and leave logFile open
// in the parent process as well.
auto pid = spawnProcess("myapp", stdin, stdout, logFile,
Config.retainStderr | Config.suppressConsole);
scope(exit)
{
auto exitCode = wait(pid);
logFile.writeln("myapp exited with code ", exitCode);
logFile.close();
}
By default, the child process inherits the parent's environment, and any environment variables passed to spawnProcess will be added to it. If this flag is set, the only variables in the child process' environment will be those given to spawnProcess.
Unless the child process inherits the standard input/output/error streams of its parent, one almost always wants the streams closed in the parent when spawnProcess returns. Therefore, by default, this is done. If this is not desirable, pass any of these options to spawnProcess.
On Windows, if the child process is a console application, this flag will prevent the creation of a console window. Otherwise, it will be ignored. On POSIX, suppressConsole has no effect.
On POSIX, open file descriptors are by default inherited by the child process. As this may lead to subtle bugs when pipes or multiple threads are involved, spawnProcess ensures that all file descriptors except the ones that correspond to standard input/output/error are closed in the child process when it starts. Use inheritFDs to prevent this.
On Windows, this option has no effect, and any handles which have been explicitly marked as inheritable will always be inherited by the child process.
Spawn process in detached state. This removes the need in calling wait to clean up the process resources.
A handle that corresponds to a spawned process.
The process ID number.
This is a number that uniquely identifies the process on the operating system, for at least as long as the process is running. Once wait has been called on the Pid, this method will return an invalid (negative) process ID.
An operating system handle to the process.
This handle is used to specify the process in OS-specific APIs. On POSIX, this function returns a core.sys.posix.sys.types.pid_t with the same value as Pid.processID, while on Windows it returns a core.sys.windows.windows.HANDLE.
Once wait has been called on the Pid, this method will return an invalid handle.
Waits for the process associated with pid to terminate, and returns its exit status.
In general one should always wait for child processes to terminate before exiting the parent process unless the process was spawned as detached (that was spawned with Config.detached flag). Otherwise, they may become "zombies" – processes that are defunct, yet still occupy a slot in the OS process table. You should not and must not wait for detached processes, since you don't own them.
If the process has already terminated, this function returns directly. The exit code is cached, so that if wait() is called multiple times on the same Pid it will always return the same value.
core.sys.posix.signal module (which corresponds to the signal.h POSIX header). ProcessException on failure or on attempt to wait for detached process. spawnProcess documentation. tryWait, for a non-blocking function.A non-blocking version of wait.
If the process associated with pid has already terminated, tryWait has the exact same effect as wait. In this case, it returns a tuple where the terminated field is set to true and the status field has the same interpretation as the return value of wait.
If the process has not yet terminated, this function differs from wait in that does not wait for this to happen, but instead returns immediately. The terminated field of the returned tuple will then be set to false, while the status field will always be 0 (zero). wait or tryWait should then be called again on the same Pid at some later time; not only to get the exit code, but also to avoid the process becoming a "zombie" when it finally terminates. (See wait for details).
std.typecons.Tuple!(bool, "terminated", int, "status"). ProcessException on failure or on attempt to wait for detached process. auto pid = spawnProcess("dmd myapp.d");
scope(exit) wait(pid);
...
auto dmd = tryWait(pid);
if (dmd.terminated)
{
if (dmd.status == 0) writeln("Compilation succeeded!");
else writeln("Compilation failed");
}
else writeln("Still compiling...");
...
Note that in this example, the first wait call will have no effect if the process has already terminated by the time tryWait is called. In the opposite case, however, the scope statement ensures that we always wait for the process if it hasn't terminated by the time we reach the end of the scope. Attempts to terminate the process associated with pid.
The effect of this function, as well as the meaning of codeOrSignal, is highly platform dependent. Details are given below. Common to all platforms is that this function only initiates termination of the process, and returns immediately. It does not wait for the process to end, nor does it guarantee that the process does in fact get terminated.
Always call wait to wait for a process to complete, even if kill has been called on it.
codeOrSignal is specified, it must be a nonnegative number which will be used as the exit code of the process. If not, the process wil exit with code 1. Do not use codeOrSignal = 259, as this is a special value (aka. STILL_ACTIVE) used by Windows to signal that a process has in fact not terminated yet. auto pid = spawnProcess("some_app");
kill(pid, 10);
assert(wait(pid) == 10);
codeOrSignal. Depending on the signal sent, this may or may not terminate the process. Symbolic constants for various POSIX signals are defined in core.sys.posix.signal, which corresponds to the signal.h POSIX header. If codeOrSignal is omitted, the SIGTERM signal will be sent. (This matches the behaviour of the kill shell command.) import core.sys.posix.signal : SIGKILL;
auto pid = spawnProcess("some_app");
kill(pid, SIGKILL);
assert(wait(pid) == -SIGKILL); // Negative return value on POSIX!
ProcessException on error (e.g. if codeOrSignal is invalid). or on attempt to kill detached process. Note that failure to terminate the process is considered a "normal" outcome, not an error.Creates a unidirectional pipe.
Data is written to one end of the pipe and read from the other.
auto p = pipe();
p.writeEnd.writeln("Hello World");
p.writeEnd.flush();
assert(p.readEnd.readln().chomp() == "Hello World");
Pipes can, for example, be used for interprocess communication by spawning a new process and passing one end of the pipe to the child, while the parent uses the other end. (See also pipeProcess and pipeShell for an easier way of doing this.) // Use cURL to download the dlang.org front page, pipe its
// output to grep to extract a list of links to ZIP files,
// and write the list to the file "D downloads.txt":
auto p = pipe();
auto outFile = File("D downloads.txt", "w");
auto cpid = spawnProcess(["curl", "http://dlang.org/download.html"],
std.stdio.stdin, p.writeEnd);
scope(exit) wait(cpid);
auto gpid = spawnProcess(["grep", "-o", `http://\S*\.zip`],
p.readEnd, outFile);
scope(exit) wait(gpid);
Pipe object that corresponds to the created pipe. std.stdio.StdioException on failure.An interface to a pipe created by the pipe function.
The read end of the pipe.
The write end of the pipe.
Closes both ends of the pipe.
Normally it is not necessary to do this manually, as std.stdio.File objects are automatically closed when there are no more references to them.
Note that if either end of the pipe has been passed to a child process, it will only be closed in the parent process. (What happens in the child process is platform dependent.)
std.exception.ErrnoException if an error occurs.Starts a new process, creating pipes to redirect its standard input, output and/or error streams.
pipeProcess and pipeShell are convenient wrappers around spawnProcess and spawnShell, respectively, and automate the task of redirecting one or more of the child process' standard streams through pipes. Like the functions they wrap, these functions return immediately, leaving the child process to execute in parallel with the invoking process. It is recommended to always call wait on the returned ProcessPipes.pid, as detailed in the documentation for wait.
The args/program/command, env and config parameters are forwarded straight to the underlying spawn functions, and we refer to their documentation for details.
char[][] args
| An array which contains the program name as the zeroth element and any command-line arguments in the following elements. (See spawnProcess for details.) |
char[] program
| The program name, without command-line arguments. (See spawnProcess for details.) |
char[] command
| A shell command which is passed verbatim to the command interpreter. (See spawnShell for details.) |
Redirect redirect
| Flags that determine which streams are redirected, and how. See Redirect for an overview of available flags. |
string[string] env
| Additional environment variables for the child process. (See spawnProcess for details.) |
Config config
| Flags that control process creation. See Config for an overview of available flags, and note that the retainStd... flags have no effect in this function. |
char[] workDir
| The working directory for the new process. By default the child process inherits the parent's working directory. |
string shellPath
| The path to the shell to use to run the specified program. By default this is nativeShell. |
ProcessPipes object which contains std.stdio.File handles that communicate with the redirected streams of the child process, along with a Pid object that corresponds to the spawned process. ProcessException on failure to start the process.std.stdio.StdioException on failure to redirect any of the streams.// my_application writes to stdout and might write to stderr
auto pipes = pipeProcess("my_application", Redirect.stdout | Redirect.stderr);
scope(exit) wait(pipes.pid);
// Store lines of output.
string[] output;
foreach (line; pipes.stdout.byLine) output ~= line.idup;
// Store lines of errors.
string[] errors;
foreach (line; pipes.stderr.byLine) errors ~= line.idup;
// sendmail expects to read from stdin
pipes = pipeProcess(["/usr/bin/sendmail", "-t"], Redirect.stdin);
pipes.stdin.writeln("To: you");
pipes.stdin.writeln("From: me");
pipes.stdin.writeln("Subject: dlang");
pipes.stdin.writeln("");
pipes.stdin.writeln(message);
// a single period tells sendmail we are finished
pipes.stdin.writeln(".");
// but at this point sendmail might not see it, we need to flush
pipes.stdin.flush();
// sendmail happens to exit on ".", but some you have to close the file:
pipes.stdin.close();
// otherwise this wait will wait forever
wait(pipes.pid);
Flags that can be passed to pipeProcess and pipeShell to specify which of the child process' standard streams are redirected. Use bitwise OR to combine flags.
Redirect the standard input, output or error streams, respectively.
Redirect all three streams. This is equivalent to Redirect.stdin | Redirect.stdout | Redirect.stderr.
Redirect the standard error stream into the standard output stream. This can not be combined with Redirect.stderr.
Redirect the standard output stream into the standard error stream. This can not be combined with Redirect.stdout.
Object which contains std.stdio.File handles that allow communication with a child process through its standard streams.
The Pid of the child process.
An std.stdio.File that allows writing to the child process' standard input stream.
Error if the child process' standard input stream hasn't been redirected.An std.stdio.File that allows reading from the child process' standard output stream.
Error if the child process' standard output stream hasn't been redirected.An std.stdio.File that allows reading from the child process' standard error stream.
Error if the child process' standard error stream hasn't been redirected.Executes the given program or shell command and returns its exit code and output.
execute and executeShell start a new process using spawnProcess and spawnShell, respectively, and wait for the process to complete before returning. The functions capture what the child process prints to both its standard output and standard error streams, and return this together with its exit code.
auto dmd = execute(["dmd", "myapp.d"]);
if (dmd.status != 0) writeln("Compilation failed:\n", dmd.output);
auto ls = executeShell("ls -l");
if (ls.status != 0) writeln("Failed to retrieve file listing");
else writeln(ls.output);
args/program/command, env and config parameters are forwarded straight to the underlying spawn functions, and we refer to their documentation for details. char[][] args
| An array which contains the program name as the zeroth element and any command-line arguments in the following elements. (See spawnProcess for details.) |
char[] program
| The program name, without command-line arguments. (See spawnProcess for details.) |
char[] command
| A shell command which is passed verbatim to the command interpreter. (See spawnShell for details.) |
string[string] env
| Additional environment variables for the child process. (See spawnProcess for details.) |
Config config
| Flags that control process creation. See Config for an overview of available flags, and note that the retainStd... flags have no effect in this function. |
size_t maxOutput
| The maximum number of bytes of output that should be captured. |
char[] workDir
| The working directory for the new process. By default the child process inherits the parent's working directory. |
string shellPath
| The path to the shell to use to run the specified program. By default this is nativeShell. |
std.typecons.Tuple!(int, "status", string, "output"). status field of the return value will contain a negative number whose absolute value is the signal number. (See wait for details.) ProcessException on failure to start the process.std.stdio.StdioException on failure to capture output.An exception that signals a problem with starting or waiting for a process.
Determines the path to the current user's preferred command interpreter.
On Windows, this function returns the contents of the COMSPEC environment variable, if it exists. Otherwise, it returns the result of nativeShell.
On POSIX, userShell returns the contents of the SHELL environment variable, if it exists and is non-empty. Otherwise, it returns the result of nativeShell.
The platform-specific native shell path.
This function returns "cmd.exe" on Windows, "/bin/sh" on POSIX, and "/system/bin/sh" on Android.
Returns the process ID of the current process, which is guaranteed to be unique on the system.
writefln("Current process ID: %d", thisProcessID);
Returns the process ID of the current thread, which is guaranteed to be unique within the current process.
core.thread.ThreadID value for the calling thread. writefln("Current thread ID: %s", thisThreadID);
Escapes an argv-style argument array to be used with spawnShell, pipeShell or executeShell.
string url = "http://dlang.org/";
executeShell(escapeShellCommand("wget", url, "-O", "dlang-index.html"));
Concatenate multiple escapeShellCommand and escapeShellFileName results to use shell redirection or piping operators.
executeShell(
escapeShellCommand("curl", "http://dlang.org/download.html") ~
"|" ~
escapeShellCommand("grep", "-o", `http://\S*\.zip`) ~
">" ~
escapeShellFileName("D download links.txt"));
Exception if any part of the command line contains unescapable characters (NUL on all platforms, as well as CR and LF on Windows).Quotes a command-line argument in a manner conforming to the behavior of CommandLineToArgvW.
Escapes a filename to be used for shell redirection with spawnShell, pipeShell or executeShell.
Manipulates environment variables using an associative-array-like interface.
This class contains only static methods, and cannot be instantiated. See below for examples of use.
Retrieves the value of the environment variable with the given name.
auto path = environment["PATH"];
Exception if the environment variable does not exist, or std.utf.UTFException if the variable contains invalid UTF-16 characters (Windows only). environment.get, which doesn't throw on failure.Retrieves the value of the environment variable with the given name, or a default value if the variable doesn't exist.
Unlike environment.opIndex, this function never throws.
auto sh = environment.get("SHELL", "/bin/sh");
This function is also useful in checking for the existence of an environment variable. auto myVar = environment.get("MYVAR");
if (myVar is null)
{
// Environment variable doesn't exist.
// Note that we have to use 'is' for the comparison, since
// myVar == null is also true if the variable exists but is
// empty.
}
std.utf.UTFException if the variable contains invalid UTF-16 characters (Windows only).Assigns the given value to the environment variable with the given name. If value is null the variable is removed from environment.
If the variable does not exist, it will be created. If it already exists, it will be overwritten.
environment["foo"] = "bar";
Exception if the environment variable could not be added (e.g. if the name is invalid). Removes the environment variable with the given name.
If the variable isn't in the environment, this function returns successfully without doing anything.
Identify whether a variable is defined in the environment.
Because it doesn't return the value, this function is cheaper than get. However, if you do need the value as well, you should just check the return of get for null instead of using this function first.
// good usage
if ("MY_ENV_FLAG" in environment)
doSomething();
// bad usage
if ("MY_ENV_VAR" in environment)
doSomething(environment["MY_ENV_VAR"]);
// do this instead
if (auto var = environment.get("MY_ENV_VAR"))
doSomething(var);
Copies all environment variables into an associative array.
PATH). Exception if the environment variables could not be retrieved (Windows only).Replaces the current process by executing a command, pathname, with the arguments in argv.
This functions is Posix-Only.
Typically, the first element of argv is the command being executed, i.e. argv[0] == pathname. The 'p' versions of exec search the PATH environment variable for pathname. The 'e' versions additionally take the new process' environment variables as an array of strings of the form key=value.
Does not return on success (the current process will have been replaced). Returns -1 on failure with no indication of the underlying error.
execv* by using spawnProcess and terminating the current process once the child process has returned. For example: auto commandLine = [ "program", "arg1", "arg2" ];
version (Posix)
{
execv(commandLine[0], commandLine);
throw new Exception("Failed to execute program");
}
else version (Windows)
{
import core.stdc.stdlib : _exit;
_exit(wait(spawnProcess(commandLine)));
}
This is, however, NOT equivalent to POSIX' execv*. For one thing, the executed program is started as a separate process, with all this entails. Secondly, in a multithreaded program, other threads will continue to do work while the current thread is waiting for the child process to complete. A better option may sometimes be to terminate the current program immediately after spawning the child process. This is the behaviour exhibited by the _exec functions in Microsoft's C runtime library, and it is how D's now-deprecated Windows execv* functions work. Example: auto commandLine = [ "program", "arg1", "arg2" ];
version (Posix)
{
execv(commandLine[0], commandLine);
throw new Exception("Failed to execute program");
}
else version (Windows)
{
spawnProcess(commandLine);
import core.stdc.stdlib : _exit;
_exit(0);
}
Start up the browser and set it to viewing the page at url.
© 1999–2017 The D Language Foundation
Licensed under the Boost License 1.0.
https://dlang.org/phobos/std_process.html