std.process

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

More...

Members

Classes

Pid
class Pid

A handle that corresponds to a spawned process.

ProcessException
class ProcessException

An exception that signals a problem with starting or waiting for a process.

environment
class environment

Manipulates environment variables using an associative-array-like interface.

Enums

Redirect
enum 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.

Functions

browse
void browse(const(char)[] url)

Start up the browser and set it to viewing the page at url.

escapeShellCommand
string escapeShellCommand(const(char[])[] args)

Escapes an argv-style argument array to be used with spawnShell, pipeShell or executeShell.

escapeShellFileName
string escapeShellFileName(const(char)[] fileName)

Escapes a filename to be used for shell redirection with spawnShell, pipeShell or executeShell.

escapeWindowsArgument
string escapeWindowsArgument(const(char)[] arg)

Quotes a command-line argument in a manner conforming to the behavior of CommandLineToArgvW.

execute
auto execute(const(char[])[] args, string[string] env, Config config, size_t maxOutput, const(char)[] workDir)
auto execute(const(char)[] program, string[string] env, Config config, size_t maxOutput, const(char)[] workDir)
executeShell
auto executeShell(const(char)[] command, string[string] env, Config config, size_t maxOutput, const(char)[] workDir, string shellPath)

Executes the given program or shell command and returns its exit code and output.

execv
int execv(string pathname, string[] argv)
execve
int execve(string pathname, string[] argv, string[] envp)
execvp
int execvp(string pathname, string[] argv)
execvpe
int execvpe(string pathname, string[] argv, string[] envp)

Replaces the current process by executing a command, pathname, with the arguments in argv.

kill
void kill(Pid pid)
void kill(Pid pid, int codeOrSignal)

Attempts to terminate the process associated with pid.

pipe
Pipe pipe()

Creates a unidirectional pipe.

pipeProcess
ProcessPipes pipeProcess(const(char[])[] args, Redirect redirect, string[string] env, Config config, const(char)[] workDir)
ProcessPipes pipeProcess(const(char)[] program, Redirect redirect, string[string] env, Config config, const(char)[] workDir)
pipeShell
ProcessPipes pipeShell(const(char)[] command, Redirect redirect, string[string] env, Config config, const(char)[] workDir, string shellPath)

Starts a new process, creating pipes to redirect its standard input, output and/or error streams.

spawnProcess
Pid spawnProcess(const(char[])[] args, string[string] env, Config config, const(char)[] workDir)
Pid spawnProcess(const(char)[] program, File stdin, File stdout, File stderr, string[string] env, Config config, const(char)[] workDir)
Pid spawnProcess(const(char)[] program, string[string] env, Config config, const(char)[] workDir)

Returns the process ID of the current thread, which is guaranteed to be unique within the current process.

spawnShell
Pid spawnShell(const(char)[] command, File stdin, File stdout, File stderr, string[string] env, Config config, const(char)[] workDir, string shellPath)
Pid spawnShell(const(char)[] command, string[string] env, Config config, const(char)[] workDir, string shellPath)

A variation on spawnProcess that runs the given command through the current user's preferred command interpreter (aka. shell).

tryWait
auto tryWait(Pid pid)

A non-blocking version of wait.

wait
int wait(Pid pid)

Waits for the process associated with pid to terminate, and returns its exit status.

waitTimeout
Tuple!(bool, "terminated", int, "status") waitTimeout(Pid pid, Duration timeout)

Waits until either the process associated with pid terminates or the elapsed time exceeds the given timeout.

Properties

nativeShell
string nativeShell [@property getter]

The platform-specific native shell path.

thisProcessID
int thisProcessID [@property getter]

Returns the process ID of the current process, which is guaranteed to be unique on the system.

thisThreadID
ThreadID thisThreadID [@property getter]

Returns the process ID of the current thread, which is guaranteed to be unique within the current process.

userShell
string userShell [@property getter]

Determines the path to the current user's preferred command interpreter.

Structs

Config
struct Config

Options that control the behaviour of process creation functions in this module. Most options only apply to spawnProcess and spawnShell.

Pipe
struct Pipe

An interface to a pipe created by the pipe function.

ProcessPipes
struct ProcessPipes

Object which contains std.stdio.File handles that allow communication with a child process through its standard streams.

Detailed Description

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 directlyRuns shell command
Low-level process creationspawnProcessspawnShell
Automatic input/output redirection using pipespipeProcesspipeShell
Execute and wait for completion, collect outputexecuteexecuteShell

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 and escapeShellFileName are useful for constructing shell command lines in a portable way.

Meta