Menu

- Learn
- Documentation
  - Language Reference
  - Library Reference
  - Command-line Reference
  - Feature Overview
  - Articles
- Downloads
- Packages
- Community
  - Blog
  - Orgs using D
  - Twitter
  - Calendar
  - Forums
  - IRC
  - Community Discord
  - Wiki
  - GitHub
  - Issues
  - Get involved
  - Contributors
  - Foundation
  - Security Team
  - Donate
  - Sponsors
- Resources
  - Tour
  - Books
  - Tutorials
  - Tools
  - Editors
  - IDEs
  - run.dlang.io
  - Visual D
  - Acknowledgments
  - D Style
  - Glossary
  - Sitemap

Search
Report a bug
If you spot a problem with this page, click here to create a Bugzilla issue.
Improve this page
Quickly fork, edit online, and submit a pull request for this page. Requires a signed-in GitHub account. This works well for small changes. If you'd like to make larger changes you may want to consider using a local clone.

# std.process

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

Process handling

- spawnProcess spawns a new process, optionally assigning it an arbitrary set of standard input, output, and error streams. The function returns immediately, leaving the child process to execute in parallel with its parent. All other functions in this module that spawn processes are built around spawnProcess.
- wait makes the parent process wait for a child process to terminate. In general one should always do this, to avoid child processes becoming "zombies" when the parent process exits. Scope guards are perfect for this – see the spawnProcess documentation for examples. tryWait is similar to wait, but does not block if the process has not yet terminated.
- pipeProcess also spawns a child process which runs in parallel with its parent. However, instead of taking arbitrary streams, it automatically creates a set of pipes that allow the parent to communicate with the child through the child's standard input, output, and/or error streams. This function corresponds roughly to C's popen function.
- execute starts a new process and waits for it to complete before returning. Additionally, it captures the process' standard output and error streams and returns the output of these as a string.
- spawnShell, pipeShell and executeShell work like spawnProcess, pipeProcess and execute, respectively, except that they take a single command string and run it through the current user's default command interpreter. executeShell corresponds roughly to C's system function.
- kill attempts to terminate a running process.

The following table compactly summarises the different process creation functions and how they relate to each other:

| Runs program 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.

Authors:
Lars Tandle Kyllingstad, Steven Schveighoffer, Vladimir Panteleev
License:
Boost License 1.0.

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`, 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.

Copyright © 1999-2022 by the D Language Foundation | Page generated by Ddoc on Thu Dec 15 17:30:51 2022