std.process

abstract class environment;

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

This class contains only static methods, and cannot be instantiated. See below for examples of use.

static @safe string opIndex(scope const(char)[] name);

Retrieves the value of the environment variable with the given name.

auto path = environment["PATH"];

Throws:

Exception if the environment variable does not exist, or std.utf.UTFException if the variable contains invalid UTF-16 characters (Windows only).

See Also:

environment.get, which doesn't throw on failure.

static @safe string get(scope const(char)[] name, string defaultValue = null);

Retrieves the value of the environment variable with the given name, or a default value if the variable doesn't exist.

Unlike environment.opIndex, this function never throws on Posix.

auto sh = environment.get("SHELL", "/bin/sh");

This function is also useful in checking for the existence of an environment variable.

auto myVar = environment.get("MYVAR");
if (myVar is null)
{
    // Environment variable doesn't exist.
    // Note that we have to use 'is' for the comparison, since
    // myVar == null is also true if the variable exists but is
    // empty.
}

Parameters:

const(char)[] name	name of the environment variable to retrieve
string defaultValue	default value to return if the environment variable doesn't exist.

Returns:

the value of the environment variable if found, otherwise null if the environment doesn't exist.

Throws:

std.utf.UTFException if the variable contains invalid UTF-16 characters (Windows only).

static @trusted inout(char)[] opIndexAssign(return scope inout char[] value, scope const(char)[] name);

Assigns the given value to the environment variable with the given name. If value is null the variable is removed from environment.

If the variable does not exist, it will be created. If it already exists, it will be overwritten.

environment["foo"] = "bar";

Throws:

Exception if the environment variable could not be added (e.g. if the name is invalid).

Note On some platforms, modifying environment variables may not be allowed in multi-threaded programs. See e.g. glibc.

static nothrow @nogc @trusted void remove(scope const(char)[] name);

Removes the environment variable with the given name.

If the variable isn't in the environment, this function returns successfully without doing anything.

Note On some platforms, modifying environment variables may not be allowed in multi-threaded programs. See e.g. glibc.

@trusted bool opBinaryRight(string op : "in")(scope const(char)[] name);

Identify whether a variable is defined in the environment.

Because it doesn't return the value, this function is cheaper than get. However, if you do need the value as well, you should just check the return of get for null instead of using this function first.

Example

// good usage
if ("MY_ENV_FLAG" in environment)
    doSomething();

// bad usage
if ("MY_ENV_VAR" in environment)
    doSomething(environment["MY_ENV_VAR"]);

// do this instead
if (auto var = environment.get("MY_ENV_VAR"))
    doSomething(var);

static @trusted string[string] toAA();

Copies all environment variables into an associative array.

Windows specific While Windows environment variable names are case insensitive, D's built-in associative arrays are not. This function will store all variable names in uppercase (e.g. PATH).

Throws:

Exception if the environment variables could not be retrieved (Windows only).

nothrow @nogc @property @trusted int thisProcessID();

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

Example

writefln("Current process ID: %d", thisProcessID);

nothrow @nogc @property @trusted ThreadID thisThreadID();

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

Returns:

A core.thread.ThreadID value for the calling thread.

Example

writefln("Current thread ID: %s", thisThreadID);

@safe Pid spawnProcess(scope const(char[])[] args, File stdin = std.stdio.stdin, File stdout = std.stdio.stdout, File stderr = std.stdio.stderr, const string[string] env = null, Config config = Config.none, scope const char[] workDir = null);

@trusted Pid spawnProcess(scope const(char[])[] args, const string[string] env, Config config = Config.none, scope const(char)[] workDir = null);

@trusted Pid spawnProcess(scope const(char)[] program, File stdin = std.stdio.stdin, File stdout = std.stdio.stdout, File stderr = std.stdio.stderr, const string[string] env = null, Config config = Config.none, scope const(char)[] workDir = null);

@trusted Pid spawnProcess(scope const(char)[] program, const string[string] env, Config config = Config.none, scope const(char)[] workDir = null);

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. It is recommended to always call wait on the returned Pid unless the process was spawned with Config.detached flag, as detailed in the documentation for wait.

Command line There are four overloads of this function. The first two take an array of strings, args, which should contain the program name as the zeroth element and any command-line arguments in subsequent elements. The third and fourth versions are included for convenience, and may be used when there are no command-line arguments. They take a single string, program, which specifies the program name.

Unless a directory is specified in args[0] or program, spawnProcess will search for the program in a platform-dependent manner. On POSIX systems, it will look for the executable in the directories listed in the PATH environment variable, in the order they are listed. On Windows, it will search for the executable in the following sequence:

1. The directory from which the application loaded.
2. The current directory for the parent process.
3. The 32-bit Windows system directory.
4. The 16-bit Windows system directory.
5. The Windows directory.
6. The directories listed in the PATH environment variable.

// Run an executable called "prog" located in the current working
// directory:
auto pid = spawnProcess("./prog");
scope(exit) wait(pid);
// We can do something else while the program runs.  The scope guard
// ensures that the process is waited for at the end of the scope.
...

// Run DMD on the file "myprog.d", specifying a few compiler switches:
auto dmdPid = spawnProcess(["dmd", "-O", "-release", "-inline", "myprog.d" ]);
if (wait(dmdPid) != 0)
    writeln("Compilation failed!");

Environment variables By default, the child process inherits the environment of the parent process, along with any additional variables specified in the env parameter. If the same variable exists in both the parent's environment and in env, the latter takes precedence.

If the Config.newEnv flag is set in config, the child process will not inherit the parent's environment. Its entire environment will then be determined by env.

wait(spawnProcess("myapp", ["foo" : "bar"], Config.newEnv));

Standard streams The optional arguments stdin, stdout and stderr may be used to assign arbitrary std.stdio.File objects as the standard input, output and error streams, respectively, of the child process. The former must be opened for reading, while the latter two must be opened for writing. The default is for the child process to inherit the standard streams of its parent.

// Run DMD on the file myprog.d, logging any error messages to a
// file named errors.log.
auto logFile = File("errors.log", "w");
auto pid = spawnProcess(["dmd", "myprog.d"],
                        std.stdio.stdin,
                        std.stdio.stdout,
                        logFile);
if (wait(pid) != 0)
    writeln("Compilation failed. See errors.log for details.");

Note that if you pass a File object that is not one of the standard input/output/error streams of the parent process, that stream will by default be closed in the parent process when this function returns. See the Config documentation below for information about how to disable this behaviour.

Beware of buffering issues when passing File objects to spawnProcess. The child process will inherit the low-level raw read/write offset associated with the underlying file descriptor, but it will not be aware of any buffered data. In cases where this matters (e.g. when a file should be aligned before being passed on to the child process), it may be a good idea to use unbuffered streams, or at least ensure all relevant buffers are flushed.

Parameters:

const(char[])[] args	An array which contains the program name as the zeroth element and any command-line arguments in the following elements.
File stdin	The standard input stream of the child process. This can be any std.stdio.File that is opened for reading. By default the child process inherits the parent's input stream.
File stdout	The standard output stream of the child process. This can be any std.stdio.File that is opened for writing. By default the child process inherits the parent's output stream.
File stderr	The standard error stream of the child process. This can be any std.stdio.File that is opened for writing. By default the child process inherits the parent's error stream.
string[string] env	Additional environment variables for the child process.
Config config	Flags that control process creation. See Config for an overview of available flags.
char[] workDir	The working directory for the new process. By default the child process inherits the parent's working directory.

Returns:

A Pid object that corresponds to the spawned process.

Throws:

ProcessException on failure to start the process.
std.stdio.StdioException on failure to pass one of the streams to the child process (Windows only).
core.exception.RangeError if args is empty.

@trusted Pid spawnShell(scope const(char)[] command, File stdin = std.stdio.stdin, File stdout = std.stdio.stdout, File stderr = std.stdio.stderr, scope const string[string] env = null, Config config = Config.none, scope const(char)[] workDir = null, scope string shellPath = nativeShell);

@trusted Pid spawnShell(scope const(char)[] command, scope const string[string] env, Config config = Config.none, scope const(char)[] workDir = null, scope string shellPath = nativeShell);

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

The string command is passed verbatim to the shell, and is therefore subject to its rules about command structure, argument/filename quoting and escaping of special characters. The path to the shell executable defaults to nativeShell.

In all other respects this function works just like spawnProcess. Please refer to the spawnProcess documentation for descriptions of the other function parameters, the return value and any exceptions that may be thrown.

// Run the command/program "foo" on the file named "my file.txt", and
// redirect its output into foo.log.
auto pid = spawnShell(`foo "my file.txt" > foo.log`);
wait(pid);

See Also:

escapeShellCommand, which may be helpful in constructing a properly quoted and escaped shell command line for the current platform.

struct Config;

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

Example

auto logFile = File("myapp_error.log", "w");

// Start program, suppressing the console window (Windows only),
// redirect its error stream to logFile, and leave logFile open
// in the parent process as well.
auto pid = spawnProcess("myapp", stdin, stdout, logFile,
                        Config.retainStderr | Config.suppressConsole);
scope(exit)
{
    auto exitCode = wait(pid);
    logFile.writeln("myapp exited with code ", exitCode);
    logFile.close();
}

enum Flags: int;

Flags flags;

Flag options. Use bitwise OR to combine flags.

newEnv

By default, the child process inherits the parent's environment, and any environment variables passed to spawnProcess will be added to it. If this flag is set, the only variables in the child process' environment will be those given to spawnProcess.

retainStdin

retainStdout

retainStderr

Unless the child process inherits the standard input/output/error streams of its parent, one almost always wants the streams closed in the parent when spawnProcess returns. Therefore, by default, this is done. If this is not desirable, pass any of these options to spawnProcess.

suppressConsole

On Windows, if the child process is a console application, this flag will prevent the creation of a console window. Otherwise, it will be ignored. On POSIX, suppressConsole has no effect.

inheritFDs

On POSIX, open file descriptors are by default inherited by the child process. As this may lead to subtle bugs when pipes or multiple threads are involved, spawnProcess ensures that all file descriptors except the ones that correspond to standard input/output/error are closed in the child process when it starts. Use inheritFDs to prevent this.

On Windows, this option has no effect, and any handles which have been explicitly marked as inheritable will always be inherited by the child process.

detached

Spawn process in detached state. This removes the need in calling wait to clean up the process resources.

Note Calling wait or kill with the resulting Pid is invalid.

stderrPassThrough

By default, the execute and executeShell functions will capture child processes' both stdout and stderr. This can be undesirable if the standard output is to be processed or otherwise used by the invoking program, as execute's result would then contain a mix of output and warning/error messages.

Specify this flag when calling execute or executeShell to cause invoked processes' stderr stream to be sent to std.stdio.stderr, and only capture and return standard output.

This flag has no effect on spawnProcess or spawnShell.

enum Config none;

enum Config newEnv;

enum Config retainStdin;

enum Config retainStdout;

enum Config retainStderr;

enum Config suppressConsole;

enum Config inheritFDs;

enum Config detached;

enum Config stderrPassThrough;

Config opUnary(string op)()
if (is(typeof(mixin(op ~ "flags"))));

Config opBinary(string op)(Config other)
if (is(typeof(mixin("flags" ~ op ~ "other.flags"))));

Config opOpAssign(string op)(Config other)
if (is(typeof(mixin("flags" ~ op ~ "=other.flags"))));

For backwards compatibility, and cases when only flags need to be specified in the Config, these allow building Config instances using flag names only.

bool function() nothrow @nogc @safe preExecFunction;

A function that is called before exec in spawnProcess. It returns true if succeeded and otherwise returns false.

Warning: Please note that the code in this function must only use async-signal-safe functions.

On Windows, this member is not available.

class Pid;

A handle that corresponds to a spawned process.

const pure nothrow @property @safe int processID();

The process ID number.

This is a number that uniquely identifies the process on the operating system, for at least as long as the process is running. Once wait has been called on the Pid, this method will return an invalid (negative) process ID.

pure nothrow @nogc @property @safe pid_t osHandle();

An operating system handle to the process.

This handle is used to specify the process in OS-specific APIs. On POSIX, this function returns a core.sys.posix.sys.types.pid_t with the same value as Pid.processID, while on Windows it returns a core.sys.windows.windows.HANDLE.

Once wait has been called on the Pid, this method will return an invalid handle.

@safe int wait(Pid pid);

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

In general one should always wait for child processes to terminate before exiting the parent process unless the process was spawned as detached (that was spawned with Config.detached flag). Otherwise, they may become "zombies" – processes that are defunct, yet still occupy a slot in the OS process table. You should not and must not wait for detached processes, since you don't own them.

If the process has already terminated, this function returns directly. The exit code is cached, so that if wait() is called multiple times on the same Pid it will always return the same value.

POSIX specific If the process is terminated by a signal, this function returns a negative number whose absolute value is the signal number. Since POSIX restricts normal exit codes to the range 0-255, a negative return value will always indicate termination by signal. Signal codes are defined in the core.sys.posix.signal module (which corresponds to the signal.h POSIX header).

Throws:

ProcessException on failure or on attempt to wait for detached process.

Example See the spawnProcess documentation.

See Also:

tryWait, for a non-blocking function.

@safe 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.

If the process terminates within the given duration it behaves exactly like wait, except that it returns a tuple (true, exit code).

If the process does not terminate within the given duration it will stop waiting and return (false, 0).

The timeout may not exceed (uint.max - 1).msecs (~ 7 weeks, 17 hours).

This function is Windows-Only.

Returns:

An std.typecons.Tuple!(bool, "terminated", int, "status").

Throws:

ProcessException on failure or on attempt to wait for detached process.

Example See the spawnProcess documentation.

See Also:

wait, for a blocking function without timeout. tryWait, for a non-blocking function without timeout.

@safe auto tryWait(Pid pid);

A non-blocking version of wait.

If the process associated with pid has already terminated, tryWait has the exact same effect as wait. In this case, it returns a tuple where the terminated field is set to true and the status field has the same interpretation as the return value of wait.

If the process has not yet terminated, this function differs from wait in that does not wait for this to happen, but instead returns immediately. The terminated field of the returned tuple will then be set to false, while the status field will always be 0 (zero). wait or tryWait should then be called again on the same Pid at some later time; not only to get the exit code, but also to avoid the process becoming a "zombie" when it finally terminates. (See wait for details).

Returns:

An std.typecons.Tuple!(bool, "terminated", int, "status").

Throws:

ProcessException on failure or on attempt to wait for detached process.

Example

auto pid = spawnProcess("dmd myapp.d");
scope(exit) wait(pid);
...
auto dmd = tryWait(pid);
if (dmd.terminated)
{
    if (dmd.status == 0) writeln("Compilation succeeded!");
    else writeln("Compilation failed");
}
else writeln("Still compiling...");
...

Note that in this example, the first wait call will have no effect if the process has already terminated by the time tryWait is called. In the opposite case, however, the scope statement ensures that we always wait for the process if it hasn't terminated by the time we reach the end of the scope.

void kill(Pid pid);

void kill(Pid pid, int codeOrSignal);

Attempts to terminate the process associated with pid.

The effect of this function, as well as the meaning of codeOrSignal, is highly platform dependent. Details are given below. Common to all platforms is that this function only initiates termination of the process, and returns immediately. It does not wait for the process to end, nor does it guarantee that the process does in fact get terminated.

Always call wait to wait for a process to complete, even if kill has been called on it.

Windows specific The process will be forcefully and abruptly terminated. If codeOrSignal is specified, it must be a nonnegative number which will be used as the exit code of the process. If not, the process wil exit with code 1. Do not use codeOrSignal = 259, as this is a special value (aka. STILL_ACTIVE) used by Windows to signal that a process has in fact not terminated yet.

auto pid = spawnProcess("some_app");
kill(pid, 10);
assert(wait(pid) == 10);

POSIX specific A signal will be sent to the process, whose value is given by codeOrSignal. Depending on the signal sent, this may or may not terminate the process. Symbolic constants for various POSIX signals are defined in core.sys.posix.signal, which corresponds to the signal.h POSIX header. If codeOrSignal is omitted, the SIGTERM signal will be sent. (This matches the behaviour of the _kill shell command.)

import core.sys.posix.signal : SIGKILL;
auto pid = spawnProcess("some_app");
kill(pid, SIGKILL);
assert(wait(pid) == -SIGKILL); // Negative return value on POSIX!

Throws:

ProcessException on error (e.g. if codeOrSignal is invalid). or on attempt to kill detached process. Note that failure to terminate the process is considered a "normal" outcome, not an error.

@trusted Pipe pipe();

Creates a unidirectional pipe.

Data is written to one end of the pipe and read from the other.

auto p = pipe();
p.writeEnd.writeln("Hello World");
p.writeEnd.flush();
assert(p.readEnd.readln().chomp() == "Hello World");

Pipes can, for example, be used for interprocess communication by spawning a new process and passing one end of the pipe to the child, while the parent uses the other end. (See also pipeProcess and pipeShell for an easier way of doing this.)

// Use cURL to download the dlang.org front page, pipe its
// output to grep to extract a list of links to ZIP files,
// and write the list to the file "D downloads.txt":
auto p = pipe();
auto outFile = File("D downloads.txt", "w");
auto cpid = spawnProcess(["curl", "http://dlang.org/download.html"],
                         std.stdio.stdin, p.writeEnd);
scope(exit) wait(cpid);
auto gpid = spawnProcess(["grep", "-o", `http://\S*\.zip`],
                         p.readEnd, outFile);
scope(exit) wait(gpid);

Returns:

A Pipe object that corresponds to the created pipe.

Throws:

std.stdio.StdioException on failure.

struct Pipe;

An interface to a pipe created by the pipe function.

nothrow @property @safe File readEnd();

The read end of the pipe.

nothrow @property @safe File writeEnd();

The write end of the pipe.

@safe void close();

Closes both ends of the pipe.

Normally it is not necessary to do this manually, as std.stdio.File objects are automatically closed when there are no more references to them.

Note that if either end of the pipe has been passed to a child process, it will only be closed in the parent process. (What happens in the child process is platform dependent.)

Throws:

std.exception.ErrnoException if an error occurs.

@safe ProcessPipes pipeProcess(scope const(char[])[] args, Redirect redirect = Redirect.all, const string[string] env = null, Config config = Config.none, scope const(char)[] workDir = null);

@safe ProcessPipes pipeProcess(scope const(char)[] program, Redirect redirect = Redirect.all, const string[string] env = null, Config config = Config.none, scope const(char)[] workDir = null);

@safe ProcessPipes pipeShell(scope const(char)[] command, Redirect redirect = Redirect.all, const string[string] env = null, Config config = Config.none, scope const(char)[] workDir = null, string shellPath = nativeShell);

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

pipeProcess and pipeShell are convenient wrappers around spawnProcess and spawnShell, respectively, and automate the task of redirecting one or more of the child process' standard streams through pipes. Like the functions they wrap, these functions return immediately, leaving the child process to execute in parallel with the invoking process. It is recommended to always call wait on the returned ProcessPipes.pid, as detailed in the documentation for wait.

The args/program/command, env and config parameters are forwarded straight to the underlying spawn functions, and we refer to their documentation for details.

Parameters:

const(char[])[] args	An array which contains the program name as the zeroth element and any command-line arguments in the following elements. (See spawnProcess for details.)
const(char)[] program	The program name, without command-line arguments. (See spawnProcess for details.)
const(char)[] command	A shell command which is passed verbatim to the command interpreter. (See spawnShell for details.)
Redirect redirect	Flags that determine which streams are redirected, and how. See Redirect for an overview of available flags.
string[string] env	Additional environment variables for the child process. (See spawnProcess for details.)
Config config	Flags that control process creation. See Config for an overview of available flags, and note that the retainStd... flags have no effect in this function.
const(char)[] workDir	The working directory for the new process. By default the child process inherits the parent's working directory.
string shellPath	The path to the shell to use to run the specified program. By default this is nativeShell.

Returns:

A ProcessPipes object which contains std.stdio.File handles that communicate with the redirected streams of the child process, along with a Pid object that corresponds to the spawned process.

Throws:

ProcessException on failure to start the process.
std.stdio.StdioException on failure to redirect any of the streams.

Example

// my_application writes to stdout and might write to stderr
auto pipes = pipeProcess("my_application", Redirect.stdout | Redirect.stderr);
scope(exit) wait(pipes.pid);

// Store lines of output.
string[] output;
foreach (line; pipes.stdout.byLine) output ~= line.idup;

// Store lines of errors.
string[] errors;
foreach (line; pipes.stderr.byLine) errors ~= line.idup;


// sendmail expects to read from stdin
pipes = pipeProcess(["/usr/bin/sendmail", "-t"], Redirect.stdin);
pipes.stdin.writeln("To: you");
pipes.stdin.writeln("From: me");
pipes.stdin.writeln("Subject: dlang");
pipes.stdin.writeln("");
pipes.stdin.writeln(message);

// a single period tells sendmail we are finished
pipes.stdin.writeln(".");

// but at this point sendmail might not see it, we need to flush
pipes.stdin.flush();

// sendmail happens to exit on ".", but some you have to close the file:
pipes.stdin.close();

// otherwise this wait will wait forever
wait(pipes.pid);

enum Redirect: int;

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.

stdin

stdout

stderr

Redirect the standard input, output or error streams, respectively.

all

Redirect all three streams. This is equivalent to Redirect.stdin | Redirect.stdout | Redirect.stderr.

stderrToStdout

Redirect the standard error stream into the standard output stream. This can not be combined with Redirect.stderr.

stdoutToStderr

Redirect the standard output stream into the standard error stream. This can not be combined with Redirect.stdout.

struct ProcessPipes;

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

nothrow @property @safe Pid pid();

The Pid of the child process.

nothrow @property @safe File stdin();

An std.stdio.File that allows writing to the child process' standard input stream.

Throws:

Error if the child process' standard input stream hasn't been redirected.

nothrow @property @safe File stdout();

An std.stdio.File that allows reading from the child process' standard output stream.

Throws:

Error if the child process' standard output stream hasn't been redirected.

nothrow @property @safe File stderr();

An std.stdio.File that allows reading from the child process' standard error stream.

Throws:

Error if the child process' standard error stream hasn't been redirected.

@safe auto execute(scope const(char[])[] args, const string[string] env = null, Config config = Config.none, size_t maxOutput = size_t.max, scope const(char)[] workDir = null);

@safe auto execute(scope const(char)[] program, const string[string] env = null, Config config = Config.none, size_t maxOutput = size_t.max, scope const(char)[] workDir = null);

@safe auto executeShell(scope const(char)[] command, const string[string] env = null, Config config = Config.none, size_t maxOutput = size_t.max, scope const(char)[] workDir = null, string shellPath = nativeShell);

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

execute and executeShell start a new process using spawnProcess and spawnShell, respectively, and wait for the process to complete before returning. The functions capture what the child process prints to both its standard output and standard error streams, and return this together with its exit code.

auto dmd = execute(["dmd", "myapp.d"]);
if (dmd.status != 0) writeln("Compilation failed:\n", dmd.output);

auto ls = executeShell("ls -l");
if (ls.status != 0) writeln("Failed to retrieve file listing");
else writeln(ls.output);

The args/program/command, env and config parameters are forwarded straight to the underlying spawn functions, and we refer to their documentation for details.

Parameters:

const(char[])[] args	An array which contains the program name as the zeroth element and any command-line arguments in the following elements. (See spawnProcess for details.)
const(char)[] program	The program name, without command-line arguments. (See spawnProcess for details.)
const(char)[] command	A shell command which is passed verbatim to the command interpreter. (See spawnShell for details.)
string[string] env	Additional environment variables for the child process. (See spawnProcess for details.)
Config config	Flags that control process creation. See Config for an overview of available flags, and note that the retainStd... flags have no effect in this function.
size_t maxOutput	The maximum number of bytes of output that should be captured.
const(char)[] workDir	The working directory for the new process. By default the child process inherits the parent's working directory.
string shellPath	The path to the shell to use to run the specified program. By default this is nativeShell.

Returns:

An std.typecons.Tuple!(int, "status", string, "output").

POSIX specific If the process is terminated by a signal, the status field of the return value will contain a negative number whose absolute value is the signal number. (See wait for details.)

Throws:

ProcessException on failure to start the process.
std.stdio.StdioException on failure to capture output.

class ProcessException: object.Exception;

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

@property @safe string userShell();

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

On Windows, this function returns the contents of the COMSPEC environment variable, if it exists. Otherwise, it returns the result of nativeShell.

On POSIX, userShell returns the contents of the SHELL environment variable, if it exists and is non-empty. Otherwise, it returns the result of nativeShell.

pure nothrow @nogc @property @safe string nativeShell();

The platform-specific native shell path.

This function returns "cmd.exe" on Windows, "/bin/sh" on POSIX, and "/system/bin/sh" on Android.

pure @safe string escapeShellCommand(scope const(char[])[] args...);

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

string url = "http://dlang.org/";
executeShell(escapeShellCommand("wget", url, "-O", "dlang-index.html"));

Concatenate multiple escapeShellCommand and escapeShellFileName results to use shell redirection or piping operators.

executeShell(
    escapeShellCommand("curl", "http://dlang.org/download.html") ~
    "|" ~
    escapeShellCommand("grep", "-o", `http://\S*\.zip`) ~
    ">" ~
    escapeShellFileName("D download links.txt"));

Throws:

Exception if any part of the command line contains unescapable characters (NUL on all platforms, as well as CR and LF on Windows).

pure nothrow @trusted string escapeWindowsArgument(scope const(char)[] arg);

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

pure nothrow @trusted string escapeShellFileName(scope const(char)[] fileName);

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

int execv(in string pathname, in string[] argv);

int execve(in string pathname, in string[] argv, in string[] envp);

int execvp(in string pathname, in string[] argv);

int execvpe(in string pathname, in string[] argv, in string[] envp);

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

This function is Posix-Only.

Typically, the first element of argv is the command being executed, i.e. argv[0] == pathname. The 'p' versions of exec search the PATH environment variable for pathname. The 'e' versions additionally take the new process' environment variables as an array of strings of the form key=value.

Does not return on success (the current process will have been replaced). Returns -1 on failure with no indication of the underlying error.

Windows specific These functions are only supported on POSIX platforms, as the Windows operating systems do not provide the ability to overwrite the current process image with another. In single-threaded programs it is possible to approximate the effect of execv* by using spawnProcess and terminating the current process once the child process has returned. For example:

auto commandLine = [ "program", "arg1", "arg2" ];
version (Posix)
{
    execv(commandLine[0], commandLine);
    throw new Exception("Failed to execute program");
}
else version (Windows)
{
    import core.stdc.stdlib : _Exit;
    _Exit(wait(spawnProcess(commandLine)));
}

This is, however, NOT equivalent to POSIX' execv*. For one thing, the executed program is started as a separate process, with all this entails. Secondly, in a multithreaded program, other threads will continue to do work while the current thread is waiting for the child process to complete.

A better option may sometimes be to terminate the current program immediately after spawning the child process. This is the behaviour exhibited by the __exec functions in Microsoft's C runtime library, and it is how D's now-deprecated Windows execv* functions work. Example:

auto commandLine = [ "program", "arg1", "arg2" ];
version (Posix)
{
    execv(commandLine[0], commandLine);
    throw new Exception("Failed to execute program");
}
else version (Windows)
{
    spawnProcess(commandLine);
    import core.stdc.stdlib : _exit;
    _exit(0);
}

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

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