std.process
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.
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 and escapeShellFileName are useful for constructing shell command lines in a portable way.
Source std/process.d
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.
- 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
, stringdefaultValue
= 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
(inout char[]value
, scope const(char)[]name
); - Assigns the given
value
to the environment variable with the givenname
. Ifvalue
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 @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 @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
, Filestdin
= std.stdio.stdin
, Filestdout
= std.stdio.stdout
, Filestderr
= std.stdio.stderr
, const string[string]env
= null, Configconfig
= Config.none, scope const char[]workDir
= null);
@trusted PidspawnProcess
(scope const(char[])[]args
, const string[string]env
, Configconfig
= Config.none, scope const(char)[]workDir
= null);
@trusted PidspawnProcess
(scope const(char)[]program
, Filestdin
= std.stdio.stdin
, Filestdout
= std.stdio.stdout
, Filestderr
= std.stdio.stderr
, const string[string]env
= null, Configconfig
= Config.none, scope const(char)[]workDir
= null);
@trusted PidspawnProcess
(scope const(char)[]program
, const string[string]env
, Configconfig
= 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,
Unless a directory is specified inargs
, 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.args
[0] orprogram
,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:- The directory from which the application loaded.
- The current directory for the parent process.
- The 32-bit Windows system directory.
- The 16-bit Windows system directory.
- The Windows directory.
- 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
If the Config.newEnv flag is set inenv
parameter. If the same variable exists in both the parent's environment and inenv
, the latter takes precedence.config
, the child process will not inherit the parent's environment. Its entire environment will then be determined byenv
.wait(spawnProcess("myapp", ["foo" : "bar"], Config.newEnv));
Standard streams The optional arguments
stdin
,stdout
andstderr
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 tospawnProcess
. 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 ifargs
is empty. - @safe Pid
spawnShell
(scope const(char)[]command
, Filestdin
= std.stdio.stdin
, Filestdout
= std.stdio.stdout
, Filestderr
= std.stdio.stderr
, scope const string[string]env
= null, Configconfig
= Config.none, scope const(char)[]workDir
= null, scope stringshellPath
= nativeShell);
@trusted PidspawnShell
(scope const(char)[]command
, scope const string[string]env
, Configconfig
= Config.none, scope const(char)[]workDir
= null, scope stringshellPath
= 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;
Flagsflags
; - 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.
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 ConfignewEnv
;
enum ConfigretainStdin
;
enum ConfigretainStdout
;
enum ConfigretainStderr
;
enum ConfigsuppressConsole
;
enum ConfiginheritFDs
;
enum Configdetached
;
enum ConfigstderrPassThrough
;
ConfigopBinary
(string op : "|")(Configother
); - 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. 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.
- 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
(Pidpid
); - 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
(Pidpid
, Durationtimeout
); - 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.
- @safe auto
tryWait
(Pidpid
); - 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 ortryWait
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 timetryWait
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
(Pidpid
);
voidkill
(Pidpid
, intcodeOrSignal
); - Attempts to terminate the process associated with
pid
.The effect of this function, as well as the meaning ofcodeOrSignal
, 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 ifkill
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. IfcodeOrSignal
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
, Redirectredirect
= Redirect.all, const string[string]env
= null, Configconfig
= Config.none, scope const(char)[]workDir
= null);
@safe ProcessPipespipeProcess
(scope const(char)[]program
, Redirectredirect
= Redirect.all, const string[string]env
= null, Configconfig
= Config.none, scope const(char)[]workDir
= null);
@safe ProcessPipespipeShell
(scope const(char)[]command
, Redirectredirect
= Redirect.all, const string[string]env
= null, Configconfig
= Config.none, scope const(char)[]workDir
= null, stringshellPath
= nativeShell); - Starts a new process, creating pipes to redirect its standard input, output and/or error streams.
pipeProcess
andpipeShell
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. Theargs
/program
/command
,env
andconfig
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, Configconfig
= Config.none, size_tmaxOutput
= size_t.max, scope const(char)[]workDir
= null);
@safe autoexecute
(scope const(char)[]program
, const string[string]env
= null, Configconfig
= Config.none, size_tmaxOutput
= size_t.max, scope const(char)[]workDir
= null);
@safe autoexecuteShell
(scope const(char)[]command
, const string[string]env
= null, Configconfig
= Config.none, size_tmaxOutput
= size_t.max, scope const(char)[]workDir
= null, stringshellPath
= nativeShell); - Executes the given program or shell command and returns its exit code and output.
execute
andexecuteShell
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);
Theargs
/program
/command
,env
andconfig
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 multipleescapeShellCommand
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
); - int
execv
(in stringpathname
, in string[]argv
);
intexecve
(in stringpathname
, in string[]argv
, in string[]envp
);
intexecvp
(in stringpathname
, in string[]argv
);
intexecvpe
(in stringpathname
, in string[]argv
, in string[]envp
); - Replaces the current process by executing a command,
pathname
, with the arguments inargv
.This function is Posix-Only. Typically, the first element ofargv
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 Windowsexecv
* 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.