Process

The Process class is used to start external programs and communicate with them via their standard input, output and error streams.

You can pass either the command line or an array of arguments to execute, either in the constructor or to the args property. The environment variables can be set in a similar way using the env property and you can set the program's working directory via the workDir property.

To actually start a process you need to use the execute() method. Once the program is running you will be able to write to its standard input via the stdin OutputStream and you will be able to read from its standard output and error through the stdout and stderr InputStream respectively.

You can check whether the process is running or not with the isRunning() method and you can get its process ID via the pid property.

After you are done with the process, or if you just want to wait for it to end, you need to call the wait() method which will return once the process is no longer running.

To stop a running process you must use kill() method. If you do this you cannot call the wait() method. Once the kill() method returns the process will be already dead.

After calling either wait() or kill(), and no more data is expected on the pipes, you should call close() as this will clean the pipes. Not doing this may lead to a depletion of the available file descriptors for the main process if many processes are created.

class Process {}

Constructors

this
this(const(char[])[] args)

Constructor (variadic version). Note that by default, the environment will not be copied.

this
this(bool copyEnv, const(char[])[] args)

Constructor (variadic version, with environment copy).

this
this(const(char)[] command, const(char[])[char[]] env)

Constructor.

this
this(const(char[])[] args, const(char[])[char[]] env)

Constructor.

Members

Functions

args
const(char[])[] args()

Return an array with the process' arguments. This does not include the actual program name.

args
const(char[])[] args(const(char)[] progname, const(char[])[] args)

Set the process' arguments from the arguments received by the method.

cleanPipes
void cleanPipes()

Close and delete any pipe that may have been left open in a previous execution of a child process.

close
void close()

Explicitly close any resources held by this process object. It is recommended to always call this when you are done with the process.

execute
deprecated void execute(const(char)[] arg1, const(char[])[] args)

Execute a process using the arguments as parameters to this method.

execute
deprecated void execute(const(char)[] command, const(char[])[const(char)[]] env)

Execute a process using the command line arguments as parameters to this method.

execute
deprecated void execute(const(char[])[] args, const(char[])[char[]] env)

Execute a process using the command line arguments as parameters to this method.

execute
Process execute()

Execute a process using the arguments that were supplied to the constructor or to the args property.

isRunning
bool isRunning()

Indicate whether the process is running or not.

kill
void kill()

Kill a running process. This method will not return until the process has been killed.

setArgs
Process setArgs(const(char)[] progname, const(char[])[] args)

Set the process' arguments from the arguments received by the method.

setCopyEnv
Process setCopyEnv(bool b)

Set the copyEnv flag. If set to true, then the environment will be copied from the current process. If set to false, then the environment is set from the env field.

setEnv
Process setEnv(const(char[])[char[]] env)

Set the process' environment variables from the associative array received by the method. Returns a 'this' reference for chaining.

setGui
Process setGui(bool value)

Set the GUI flag. Returns a reference to this process for chaining.

setProgramName
Process setProgramName(const(char)[] name)

Set the process' executable filename, return 'this' for chaining

setRedirect
Process setRedirect(Redirect flags)

Set the redirect flags for the process. Return a reference to this process for chaining.

setWorkDir
Process setWorkDir(const(char)[] dir)

Set the working directory for the process. Returns a 'this' reference for chaining

toString
string toString()

Return an UTF-8 string with the process' command line.

wait
Result wait()

Unconditionally wait for a process to end and return the reason and status code why the process ended.

Properties

copyEnv
bool copyEnv [@property getter]

If true, the environment from the current process will be copied to the child process.

copyEnv
bool copyEnv [@property setter]

Set the copyEnv flag. If set to true, then the environment will be copied from the current process. If set to false, then the environment is set from the env field.

env
const(const(char[])[char[]]) env [@property getter]

Return an associative array with the process' environment variables.

env
const(char[])[char[]] env [@property setter]

Set the process' environment variables from the associative array received by the method.

gui
bool gui [@property getter]

Get the GUI flag.

gui
bool gui [@property setter]

Set the GUI flag.

pid
int pid [@property getter]

Return the running process' ID.

programName
const(char)[] programName [@property getter]

Return the process' executable filename.

programName
const(char)[] programName [@property setter]

Set the process' executable filename.

redirect
Redirect redirect [@property getter]

Get the redirect flags for the process.

redirect
Redirect redirect [@property setter]

Set the redirect flags for the process.

stderr
PipeConduit stderr [@property getter]

Return the running process' standard error pipe.

stdin
PipeConduit stdin [@property getter]

Return the running process' standard input pipe.

stdout
PipeConduit stdout [@property getter]

Return the running process' standard output pipe.

workDir
const(char)[] workDir [@property getter]

Return the working directory for the process.

workDir
const(char)[] workDir [@property setter]

Set the working directory for the process.

Static functions

execvpe
int execvpe(const(char)[] filename, const(char)*[] argv, const(char)*[] envp)

Execute a process by looking up a file in the system path, passing the array of arguments and the the environment variables. This method is a combination of the execve() and execvp() POSIX system calls.

splitArgs
const(char)[][] splitArgs(const(char)[] command, const(char)[] delims)

Split a string containing the command line used to invoke a program and return and array with the parsed arguments. The double-quotes (") character can be used to specify arguments with embedded spaces. e.g. first "second param" third

toNullEndedArray
const(char)*[] toNullEndedArray(const(char)[] elem0, const(char[])[] src)

Convert an array of strings to an array of pointers to char with a terminating null character (C strings). The resulting array has a null pointer at the end. This is the format expected by the execv*() family of POSIX functions.

toNullEndedArray
const(char)*[] toNullEndedArray(const(char[])[char[]] src)

Convert an associative array of strings to an array of pointers to char with a terminating null character (C strings). The resulting array has a null pointer at the end. This is the format expected by the execv*() family of POSIX functions for environment variables.

toNullEndedBuffer
char[] toNullEndedBuffer(const(char[])[char[]] src)

Convert an associative array of strings to a buffer containing a concatenation of "<name>=<value>" strings separated by a null character and with an additional null character at the end of it. This is the format expected by the CreateProcess() Windows API for the environment variables.

Structs

Result
struct Result

Result returned by wait().

Variables

DefaultRedirectFlags
enum Redirect DefaultRedirectFlags;
Undocumented in source.
DefaultStderrBufferSize
enum uint DefaultStderrBufferSize;
Undocumented in source.
DefaultStdinBufferSize
enum uint DefaultStdinBufferSize;
Undocumented in source.
DefaultStdoutBufferSize
enum uint DefaultStdoutBufferSize;
Undocumented in source.

Examples

try
{
    auto p = new Process ("ls -al", null);
    p.execute;

    Stdout.formatln ("Output from {}:", p.programName);
    Stdout.copy (p.stdout).flush;
    auto result = p.wait;

    Stdout.formatln ("Process '{}' ({}) exited with reason {}, status {}",
                     p.programName, p.pid, cast(int) result.reason, result.status);
}
catch (ProcessException e)
       Stdout.formatln ("Process execution failed: {}", e);

Meta