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.
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 aroundspawnProcess
. -
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 thespawnProcess
documentation for examples.tryWait
is similar towait
, 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'spopen
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
andexecuteShell
work likespawnProcess
,pipeProcess
andexecute
, 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'ssystem
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
-
pipe
is used to create unidirectional pipes. -
environment
is an interface through which the current process' environment variables can be read and manipulated. -
escapeShellCommand
andescapeShellFileName
are useful for constructing shell command lines in a portable way.
Note
Most of the functionality in this module is not available on iOS, tvOS
and watchOS. The only functions available on those platforms are:
environment
, thisProcessID
and thisThreadID
.
Functions
Name | Description |
---|---|
browse(url)
|
Start up the browser and set it to viewing the page at url. |
escapeShellCommand(args)
|
Escapes an argv-style argument array to be used with spawnShell ,
pipeShell or executeShell .
|
escapeShellFileName(fileName)
|
Escapes a filename to be used for shell redirection with spawnShell ,
pipeShell or executeShell .
|
escapeWindowsArgument(arg)
|
Quotes a command-line argument in a manner conforming to the behavior of CommandLineToArgvW. |
execute(args, env, config, maxOutput, workDir)
|
Executes the given program or shell command and returns its exit code and output. |
executeShell(command, env, config, maxOutput, workDir, shellPath)
|
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 .
|
kill(pid)
|
Attempts to terminate the process associated with pid .
|
nativeShell()
|
The platform-specific native shell path. |
pipe()
|
Creates a unidirectional pipe. |
pipeProcess(args, redirect, env, config, workDir)
|
Starts a new process, creating pipes to redirect its standard input, output and/or error streams. |
pipeShell(command, redirect, env, config, workDir, shellPath)
|
Starts a new process, creating pipes to redirect its standard input, output and/or error streams. |
spawnProcess(args, stdin, stdout, stderr, env, config, workDir)
|
Spawns a new process, optionally assigning it an arbitrary set of standard input, output, and error streams. |
spawnShell(command, stdin, stdout, stderr, env, config, workDir, shellPath)
|
A variation on spawnProcess that runs the given command through
the current user's preferred command interpreter (aka. shell).
|
thisProcessID()
|
Returns the process ID of the current process, which is guaranteed to be unique on the system. |
thisThreadID()
|
Returns the process ID of the current thread, which is guaranteed to be unique within the current process. |
tryWait(pid)
|
A non-blocking version of wait .
|
userShell()
|
Determines the path to the current user's preferred command interpreter. |
wait(pid)
|
Waits for the process associated with pid to terminate, and returns
its exit status.
|
waitTimeout(pid, timeout)
|
Waits until either the process associated with pid terminates or the
elapsed time exceeds the given timeout.
|
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 |
---|---|
Config
|
Options that control the behaviour of process creation functions in this
module. Most options only apply to spawnProcess and
spawnShell .
|
Pipe
|
An interface to a pipe created by the pipe function.
|
ProcessPipes
|
Object which contains File handles that allow communication
with a child process through its standard streams.
|
Enums
Name | Description |
---|---|
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.
|
Authors
Lars Tandle Kyllingstad, Steven Schveighoffer, Vladimir Panteleev
License
Copyright © 1999-2022 by the D Language Foundation | Page generated by ddox.