View source code Display the source code in std/process.d from which this page was generated on github. 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. Page wiki View or edit the community-maintained wiki page associated with this page.

Module std.process

Functions for starting and interacting with other processes, and for working with the current process' execution environment.

Process handling

  • 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.

The following table compactly summarises the different process creation functions and how they relate to each other: 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

Other functionality

Functions

Name Description
browse Start up the browser and set it to viewing the page at url.
escapeShellCommand Escapes an argv-style argument array to be used with spawnShell, pipeShell or executeShell.
escapeShellFileName Escapes a filename to be used for shell redirection with spawnShell, pipeShell or executeShell.
escapeWindowsArgument Quotes a command-line argument in a manner conforming to the behavior of CommandLineToArgvW.
execute Executes the given program or shell command and returns its exit code and output.
executeShell Executes the given program or shell command and returns its exit code and output.
execv Replaces the current process by executing a command, pathname, with the arguments in argv.
execve Replaces the current process by executing a command, pathname, with the arguments in argv.
execvp Replaces the current process by executing a command, pathname, with the arguments in argv.
execvpe Replaces the current process by executing a command, pathname, with the arguments in argv.
getenv Gets the value of environment variable name as a string. Calls core.stdc.stdlib.getenv internally.
kill Attempts to terminate the process associated with pid.
pipe Creates a unidirectional pipe.
pipeProcess Starts a new process, creating pipes to redirect its standard input, output and/or error streams.
pipeShell Starts a new process, creating pipes to redirect its standard input, output and/or error streams.
setenv Sets the value of environment variable name to value. If the value was written, or the variable was already present and overwrite is false, returns normally. Otherwise, it throws an exception. Calls core.sys.posix.stdlib.setenv internally.
shell Runs cmd in a shell and returns its standard output. If the process could not be started or exits with an error code, throws ErrnoException.
spawnProcess Spawns a new process, optionally assigning it an arbitrary set of standard input, output, and error streams.
spawnShell A variation on spawnProcess that runs the given command through the current user's preferred command interpreter (aka. shell).
system Execute command in a command shell.
thisProcessID Returns the process ID number of the current process.
tryWait A non-blocking version of wait.
unsetenv Removes variable name from the environment. Calls core.sys.posix.stdlib.unsetenv internally.
userShell Determines the path to the current user's default command interpreter.
wait Waits for the process associated with pid to terminate, and returns its exit status.

Classes

Name Description
environment Manipulates environment variables using an associative-array-like interface.
Pid A handle that corresponds to a spawned process.
ProcessException An exception that signals a problem with starting or waiting for a process.

Structs

Name Description
Pipe An interface to a pipe created by the pipe function.
ProcessPipes Object which contains std.stdio.File handles that allow communication with a child process through its standard streams.

Enums

Name Description
Config Flags that control the behaviour of spawnProcess and spawnShell.
Redirect 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.

Aliases

Name Type Description
getpid Returns the process ID of the calling process, which is guaranteed to be unique on the system. This call is always successful.

Authors

Lars Tandle Kyllingstad, Steven Schveighoffer, Vladimir Panteleev

License

Boost License 1.0.

Comments