tango.sys.Process

License:

BSD style: see license.txt

Author:

Juan Jose Comellas
enum Redirect
Redirect flags for processes. Defined outside process class to cut down on verbosity.
None
Redirect none of the standard handles
Output
Redirect the stdout handle to a pipe.
Error
Redirect the stderr handle to a pipe.
Input
Redirect the stdin handle to a pipe.
All
Redirect all three handles to pipes (default).
ErrorToOutput
Send stderr to stdout's handle. Note that the stderr PipeConduit will be null.
OutputToError
Send stdout to stderr's handle. Note that the stdout PipeConduit will be null.
class 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.

Examples:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

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);
struct Result [public]
Result returned by wait().
enum [public]
Reasons returned by wait() indicating why the process is no longer running.
immutable(char)[] toString() [public]
Returns a string with a description of the process execution result.
this(const(char[])[] args...) [public]
Constructor (variadic version). Note that by default, the environment will not be copied.

Parameters:

argsarray of strings with the process' arguments. If there is exactly one argument, it is considered to contain the entire command line including parameters. If you pass only one argument, spaces that are not intended to separate parameters should be embedded in quotes. The arguments can also be empty.

Note:

The class will use only slices, .dup when necessary.

Examples:

1
2

auto p = new Process("myprogram", "first argument", "second", "third");
auto p = new Process("myprogram \"first argument\" second third");
this(bool copyEnv, const(char[])[] args...) [public]
Constructor (variadic version, with environment copy).

Parameters:

copyEnvif true, the environment is copied from the current process.
argsarray of strings with the process' arguments. If there is exactly one argument, it is considered to contain the entire command line including parameters. If you pass only one argument, spaces that are not intended to separate parameters should be embedded in quotes. The arguments can also be empty.

Note:

The class will use only slices, .dup when necessary.

Examples:

1
2

auto p = new Process(true, "myprogram", "first argument", "second", "third");
auto p = new Process(true, "myprogram \"first argument\" second third");
this(const(char)[] command, const(char[])[char[]] env) [public]
Constructor.

Parameters:

commandstring with the process' command line; arguments that have embedded whitespace must be enclosed in inside double-quotes (").

Note:

The class will use only slices, .dup when necessary. env = associative array of strings with the process' environment variables; the variable name must be the key of each entry.

Examples:

1
2
3
4
5
6
7
8

char[] command = "myprogram \"first argument\" second third";
char[][char[]] env;

// Environment variables
env["MYVAR1"] = "first";
env["MYVAR2"] = "second";

auto p = new Process(command, env)
this(const(char[])[] args, const(char[])[char[]] env) [public]
Constructor.

Parameters:

argsarray of strings with the process' arguments; the first argument must be the process' name; the arguments can be empty.

Note:

The class will use only slices, .dup when necessary. env = associative array of strings with the process' environment variables; the variable name must be the key of each entry.

Examples:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

char[][] args;
char[][char[]] env;

// Process name
args ~= "myprogram";
// Process arguments
args ~= "first argument";
args ~= "second";
args ~= "third";

// Environment variables
env["MYVAR1"] = "first";
env["MYVAR2"] = "second";

auto p = new Process(args, env)
bool isRunning() [public, const]
Indicate whether the process is running or not.
int pid() [public, @property, const]
Return the running process' ID.

Returns:

an int with the process ID if the process is running; -1 if not.
const(char)[] programName() [public, @property, const]
Return the process' executable filename.
const(char)[] programName(const(char)[] name) [public, @property]
Set the process' executable filename.
Process setProgramName(const(char)[] name) [public]
Set the process' executable filename, return 'this' for chaining
const(char[])[] args() [public, const]
Return an array with the process' arguments. This does not include the actual program name.
const(char[])[] args(const(char)[] progname, const(char[])[] args...) [public]
Set the process' arguments from the arguments received by the method.

Remarks:

The first element of the array must be the name of the process' executable.

Returns:

the arguments that were set. This doesn't include the progname.

Examples:

1

p.args("myprogram", "first", "second argument", "third");
Process setArgs(const(char)[] progname, const(char[])[] args...) [public]
Set the process' arguments from the arguments received by the method.

Remarks:

The first element of the array must be the name of the process' executable.

Returns:

a reference to this for chaining

Examples:

1

p.setArgs("myprogram", "first", "second argument", "third").execute();
bool copyEnv() [public, @property, const]
If true, the environment from the current process will be copied to the child process.
bool copyEnv(bool b) [public, @property]
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.
Process setCopyEnv(bool b) [public]
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.

Returns:

A reference to this for chaining
const(const(char[])[char[]]) env() [public, @property, const]
Return an associative array with the process' environment variables.
Note that if copyEnv is set to true, this value is ignored.
const(char[])[char[]] env(const(char[])[char[]] env) [public, @property]
Set the process' environment variables from the associative array received by the method.
This also clears the copyEnv flag.

Parameters:

envassociative array of strings containing the environment variables for the process. The variable name should be the key used for each entry.

Returns:

the env set.

Examples:

1
2
3
4
5
6

char[][char[]] env;

env["MYVAR1"] = "first";
env["MYVAR2"] = "second";

p.env = env;
Process setEnv(const(char[])[char[]] env) [public]
Set the process' environment variables from the associative array received by the method. Returns a 'this' reference for chaining.
This also clears the copyEnv flag.

Parameters:

envassociative array of strings containing the environment variables for the process. The variable name should be the key used for each entry.

Returns:

A reference to this process object

Examples:

1
2
3
4
5
6

char[][char[]] env;

env["MYVAR1"] = "first";
env["MYVAR2"] = "second";

p.setEnv(env).execute();
string toString() [public, override]
Return an UTF-8 string with the process' command line.
const(char)[] workDir() [public, @property, const]
Return the working directory for the process.

Returns:

a string with the working directory; null if the working directory is the current directory.
const(char)[] workDir(const(char)[] dir) [public, @property]
Set the working directory for the process.

Parameters:

dira string with the working directory; null if the working directory is the current directory.

Returns:

the directory set.
Process setWorkDir(const(char)[] dir) [public]
Set the working directory for the process. Returns a 'this' reference for chaining

Parameters:

dira string with the working directory; null if the working directory is the current directory.

Returns:

a reference to this process.
Redirect redirect() [public, @property, const]
Get the redirect flags for the process.
The redirect flags are used to determine whether stdout, stderr, or stdin are redirected. The flags are an or'd combination of which standard handles to redirect. A redirected handle creates a pipe, whereas a non-redirected handle simply points to the same handle this process is pointing to.

You can also redirect stdout or stderr to each other. The flags to redirect a handle to a pipe and to redirect it to another handle are mutually exclusive. In the case both are specified, the redirect to the other handle takes precedent. It is illegal to specify both redirection from stdout to stderr and from stderr to stdout. If both of these are specified, an exception is thrown.

If redirected to a pipe, once the process is executed successfully, its input and output can be manipulated through the stdin, stdout and stderr member PipeConduit's. Note that if you redirect for example stderr to stdout, and you redirect stdout to a pipe, only stdout will be non-null.
Redirect redirect(Redirect flags) [public, @property]
Set the redirect flags for the process.
Process setRedirect(Redirect flags) [public]
Set the redirect flags for the process. Return a reference to this process for chaining.
bool gui() [public, @property, const]
Get the GUI flag.
This flag indicates on Windows systems that the CREATE_NO_WINDOW flag should be set on CreateProcess. Although this is a specific windows flag, it is present on posix systems as a noop for compatibility.

Without this flag, a console window will be allocated if it doesn't already exist.
bool gui(bool value) [public, @property]
Set the GUI flag.
This flag indicates on Windows systems that the CREATE_NO_WINDOW flag should be set on CreateProcess. Although this is a specific windows flag, it is present on posix systems as a noop for compatibility.

Without this flag, a console window will be allocated if it doesn't already exist.
Process setGui(bool value) [public]
Set the GUI flag. Returns a reference to this process for chaining.
This flag indicates on Windows systems that the CREATE_NO_WINDOW flag should be set on CreateProcess. Although this is a specific windows flag, it is present on posix systems as a noop for compatibility.

Without this flag, a console window will be allocated if it doesn't already exist.
PipeConduit stdin() [public, @property]
Return the running process' standard input pipe.

Returns:

a write-only PipeConduit connected to the child process' stdin.

Remarks:

The stream will be null if no child process has been executed, or the standard input stream was not redirected.
PipeConduit stdout() [public, @property]
Return the running process' standard output pipe.

Returns:

a read-only PipeConduit connected to the child process' stdout.

Remarks:

The stream will be null if no child process has been executed, or the standard output stream was not redirected.
PipeConduit stderr() [public, @property]
Return the running process' standard error pipe.

Returns:

a read-only PipeConduit connected to the child process' stderr.

Remarks:

The stream will be null if no child process has been executed, or the standard error stream was not redirected.
void execute(const(char)[] arg1, const(char[])[] args...) [public, deprecated]
Execute a process using the arguments as parameters to this method.
Once the process is executed successfully, its input and output can be manipulated through the stdin, stdout and stderr member PipeConduit's.

Throws:

ProcessCreateException if the process could not be created successfully; ProcessForkException if the call to the fork() system call failed (on POSIX-compatible platforms).

Remarks:

The process must not be running and the provided list of arguments must not be empty. If there was any argument already present in the args member, they will be replaced by the arguments supplied to the method.

Deprecated:

)
Use constructor or properties to set up process for execution.
void execute(const(char)[] command, const(char[])[const(char)[]] env) [public, deprecated]
Execute a process using the command line arguments as parameters to this method.
Once the process is executed successfully, its input and output can be manipulated through the stdin, stdout and stderr member PipeConduit's.

This also clears the copyEnv flag

Parameters:

commandstring with the process' command line; arguments that have embedded whitespace must be enclosed in inside double-quotes (").
envassociative array of strings with the process' environment variables; the variable name must be the key of each entry.

Throws:

ProcessCreateException if the process could not be created successfully; ProcessForkException if the call to the fork() system call failed (on POSIX-compatible platforms).

Remarks:

The process must not be running and the provided list of arguments must not be empty. If there was any argument already present in the args member, they will be replaced by the arguments supplied to the method.

Deprecated:

)
use properties or the constructor to set these parameters instead.
void execute(const(char[])[] args, const(char[])[char[]] env) [public, deprecated]
Execute a process using the command line arguments as parameters to this method.
Once the process is executed successfully, its input and output can be manipulated through the stdin, stdout and stderr member PipeConduit's.

This also clears the copyEnv flag

Parameters:

argsarray of strings with the process' arguments; the first argument must be the process' name; the arguments can be empty.
envassociative array of strings with the process' environment variables; the variable name must be the key of each entry.

Throws:

ProcessCreateException if the process could not be created successfully; ProcessForkException if the call to the fork() system call failed (on POSIX-compatible platforms).

Remarks:

The process must not be running and the provided list of arguments must not be empty. If there was any argument already present in the args member, they will be replaced by the arguments supplied to the method.

Deprecated:

)
Use properties or the constructor to set these parameters instead.

Examples:

1
2
3
4
5
6
7

auto p = new Process();
char[][] args;

args ~= "ls";
args ~= "-l";

p.execute(args, null);
Process execute() [public]
Execute a process using the arguments that were supplied to the constructor or to the args property.
Once the process is executed successfully, its input and output can be manipulated through the stdin, stdout and stderr member PipeConduit's.

Returns:

A reference to this process object for chaining.

Throws:

ProcessCreateException if the process could not be created successfully; ProcessForkException if the call to the fork() system call failed (on POSIX-compatible platforms).

Remarks:

The process must not be running and the list of arguments must not be empty before calling this method.
Result wait() [public]
Unconditionally wait for a process to end and return the reason and status code why the process ended.

Returns:

The return value is a Result struct, which has two members: reason and status. The reason can take the following values:

Process.Result.Exit: the child process exited normally; status has the process' return code.

Process.Result.Signal: the child process was killed by a signal; status has the signal number that killed the process.

Process.Result.Stop: the process was stopped; status has the signal number that was used to stop the process.

Process.Result.Continue: the process had been previously stopped and has now been restarted; status has the signal number that was used to continue the process.

Process.Result.Error: We could not properly wait on the child process; status has the errno value if the process was running and -1 if not.

Remarks:

You can only call wait() on a running process once. The Signal, Stop and Continue reasons will only be returned on POSIX-compatible platforms. Calling wait() will not clean the pipes as the parent process may still want the remaining output. It is however recommended to call close() when no more content is expected, as this will close the pipes.
void kill() [public]
Kill a running process. This method will not return until the process has been killed.

Throws:

ProcessKillException if the process could not be killed; ProcessWaitException if we could not wait on the process after killing it.

Remarks:

After calling this method you will not be able to call wait() on the process. Killing the process does not clean the attached pipes as the parent process may still want/need the remaining content. However, it is recommended to call close() on the process when it is no longer needed as this will clean the pipes.
const(char)[][] splitArgs(const(char)[] command, const(char)[] delims = " \t\r\n") [protected, static]
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
void cleanPipes() [protected]
Close and delete any pipe that may have been left open in a previous execution of a child process.
void close() [public]
Explicitly close any resources held by this process object. It is recommended to always call this when you are done with the process.
const(char)*[] toNullEndedArray(const(char)[] elem0, const(char[])[] src) [protected, static]
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.
const(char)*[] toNullEndedArray(const(char[])[char[]] src) [protected, static]
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.
int execvpe(const(char)[] filename, const(char)*[] argv, const(char)*[] envp) [protected, static]
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.
class ProcessCreateException : ProcessException
Exception thrown when the process cannot be created.
class ProcessForkException : ProcessException
Exception thrown when the parent process cannot be forked.
This exception will only be thrown on POSIX-compatible platforms.
class ProcessKillException : ProcessException
Exception thrown when the process cannot be killed.
class ProcessWaitException : ProcessException
Exception thrown when the parent process tries to wait on the child process and fails.