This module implements an advanced facility for executing OS processes and process communication.

See also:

Imports

strutils, os, strtabs, streams, cpuinfo, streamwrapper, since, winlean

Types

Process = ref ProcessObj

Represents an operating system process. Source Edit

ProcessOption = enum
  poEchoCmd,                ## Echo the command before execution.
  poUsePath, ## Asks system to search for executable using PATH environment
              ## variable.
              ## On Windows, this is the default.
  poEvalCommand, ## Pass `command` directly to the shell, without quoting.
                  ## Use it only if `command` comes from trusted source.
  poStdErrToStdOut,         ## Merge stdout and stderr to the stdout stream.
  poParentStreams,          ## Use the parent's streams.
  poInteractive, ## Optimize the buffer handling for responsiveness for
                  ## UI applications. Currently this only affects
                  ## Windows: Named pipes are used so that you can peek
                  ## at the process' output streams.
  poDaemon                   ## Windows: The program creates no Window.
                             ## Unix: Start the program as a daemon. This is still
                             ## work in progress!

Options that can be passed to startProcess proc. Source Edit

Procs

proc close(p: Process) {....gcsafe, extern: "nosp$1", raises: [IOError, OSError],
                         tags: [WriteIOEffect], forbids: [].}

When the process has finished executing, cleanup related handles.

Warning: If the process has not finished executing, this will forcibly terminate the process. Doing so may result in zombie processes and pty leaks.

Source Edit

proc countProcessors(): int {....gcsafe, extern: "nosp$1", raises: [], tags: [],
                              forbids: [].}

Returns the number of the processors/cores the machine has. Returns 0 if it cannot be detected. It is implemented just calling cpuinfo.countProcessors. Source Edit

proc errorHandle(p: Process): FileHandle {....gcsafe, extern: "nosp$1", raises: [],
    tags: [], forbids: [].}

Returns p’s error file handle for reading from.

Warning: The returned FileHandle should not be closed manually as it is closed when closing the Process p.

See also:

inputHandle proc
outputHandle proc

Source Edit

proc errorStream(p: Process): Stream {....gcsafe, extern: "nosp$1", tags: [],
                                       raises: [], forbids: [].}

Returns p’s error stream for reading from.

You cannot perform peek/write/setOption operations to this stream. Use peekableErrorStream proc if you need to peek stream.

Warning: The returned Stream should not be closed manually as it is closed when closing the Process p.

See also:

inputStream proc
outputStream proc

Source Edit

proc execCmd(command: string): int {....gcsafe, extern: "nosp$1", tags: [
    ExecIOEffect, ReadIOEffect, RootEffect], raises: [OSError], forbids: [].}

Executes command and returns its error code.

Standard input, output, error streams are inherited from the calling process. This operation is also often called system.

See also:

execCmdEx proc
startProcess proc
execProcess proc

Example:

let errC = execCmd("nim c -r mytestfile.nim")

Source Edit

proc execCmdEx(command: string;
               options: set[ProcessOption] = {poStdErrToStdOut, poUsePath};
               env: StringTableRef = nil; workingDir = ""; input = ""): tuple[
    output: string, exitCode: int] {....raises: [OSError, IOError], tags: [
    ExecIOEffect, ReadIOEffect, RootEffect], gcsafe, forbids: [].}

A convenience proc that runs the command, and returns its output and exitCode. env and workingDir params behave as for startProcess. If input.len > 0, it is passed as stdin.

Note: this could block if input.len is greater than your OS’s maximum pipe buffer size.

See also:

execCmd proc
startProcess proc
execProcess proc

Example:

var result = execCmdEx("nim r --hints:off -", options = {}, input = "echo 3*4")
import std/[strutils, strtabs]
stripLineEnd(result[0]) ## portable way to remove trailing newline, if any
doAssert result == ("12", 0)
doAssert execCmdEx("ls --nonexistent").exitCode != 0
when defined(posix):
  assert execCmdEx("echo $FO", env = newStringTable({"FO": "B"})) == ("B\n", 0)
  assert execCmdEx("echo $PWD", workingDir = "/") == ("/\n", 0)

Source Edit

proc execProcess(command: string; workingDir: string = "";
                 args: openArray[string] = []; env: StringTableRef = nil;
    options: set[ProcessOption] = {poStdErrToStdOut, poUsePath, poEvalCommand}): string {.
    ...gcsafe, extern: "nosp$1", raises: [OSError, IOError],
    tags: [ExecIOEffect, ReadIOEffect, RootEffect], forbids: [].}

A convenience procedure that executes command with startProcess and returns its output as a string.

Warning: This function uses poEvalCommand by default for backwards compatibility. Make sure to pass options explicitly.

See also:

startProcess proc
execProcesses proc,proc(int,Process))
execCmd proc

Example:

let outp = execProcess("nim", args=["c", "-r", "mytestfile.nim"], options={poUsePath})
let outp_shell = execProcess("nim c -r mytestfile.nim")
# Note: outp may have an interleave of text from the nim compile
# and any output from mytestfile when it runs

Source Edit

proc execProcesses(cmds: openArray[string];
                   options = {poStdErrToStdOut, poParentStreams};
                   n = countProcessors(); beforeRunEvent: proc (idx: int) = nil;
                   afterRunEvent: proc (idx: int; p: Process) = nil): int {.
    ...gcsafe, extern: "nosp$1", raises: [ValueError, OSError, IOError],
    tags: [ExecIOEffect, TimeEffect, ReadEnvEffect, RootEffect],
    effectsOf: [beforeRunEvent, afterRunEvent], ...forbids: [].}

Executes the commands cmds in parallel. Creates n processes that execute in parallel.

The highest (absolute) return value of all processes is returned. Runs beforeRunEvent before running each command.

Source Edit

proc hasData(p: Process): bool {....raises: [], tags: [], forbids: [].}

Source Edit

proc inputHandle(p: Process): FileHandle {....gcsafe, raises: [], extern: "nosp$1",
    tags: [], forbids: [].}

Returns p’s input file handle for writing to.

Warning: The returned FileHandle should not be closed manually as it is closed when closing the Process p.

See also:

outputHandle proc
errorHandle proc

Source Edit

proc inputStream(p: Process): Stream {....gcsafe, extern: "nosp$1", tags: [],
                                       raises: [], forbids: [].}

Returns p’s input stream for writing to.

Warning: The returned Stream should not be closed manually as it is closed when closing the Process p.

See also:

outputStream proc
errorStream proc

Source Edit

proc kill(p: Process) {....gcsafe, extern: "nosp$1", tags: [], raises: [OSError],
                        forbids: [].}

Kill the process p.

On Posix OSes the procedure sends SIGKILL to the process. On Windows kill is simply an alias for terminate().

See also:

Source Edit

proc outputHandle(p: Process): FileHandle {....gcsafe, extern: "nosp$1",
    raises: [], tags: [], forbids: [].}

Returns p’s output file handle for reading from.

Warning: The returned FileHandle should not be closed manually as it is closed when closing the Process p.

See also:

inputHandle proc
errorHandle proc

Source Edit

proc outputStream(p: Process): Stream {....gcsafe, extern: "nosp$1",
                                        raises: [IOError, OSError], tags: [],
                                        forbids: [].}

Returns p’s output stream for reading from.

You cannot perform peek/write/setOption operations to this stream. Use peekableOutputStream proc if you need to peek stream.

Warning: The returned Stream should not be closed manually as it is closed when closing the Process p.

See also:

inputStream proc
errorStream proc

Source Edit

proc peekableErrorStream(p: Process): Stream {....gcsafe, extern: "nosp$1",
    tags: [], raises: [], forbids: [].}

Returns p’s error stream for reading from.

You can run peek operation to returned stream.

Warning: The returned Stream should not be closed manually as it is closed when closing the Process p.

See also:

errorStream proc
peekableOutputStream proc

Source Edit

proc peekableOutputStream(p: Process): Stream {....gcsafe, extern: "nosp$1",
    tags: [], raises: [], forbids: [].}

Returns p’s output stream for reading from.

You can peek returned stream.

Warning: The returned Stream should not be closed manually as it is closed when closing the Process p.

See also:

outputStream proc
peekableErrorStream proc

Source Edit

proc peekExitCode(p: Process): int {....gcsafe, extern: "nosp$1",
                                     raises: [OSError], tags: [], forbids: [].}

Return -1 if the process is still running. Otherwise the process’ exit code.

On posix, if the process has exited because of a signal, 128 + signal number will be returned.

Source Edit

proc processID(p: Process): int {....gcsafe, extern: "nosp$1", raises: [],
                                  tags: [], forbids: [].}

Returns p’s process ID.

See also:

os.getCurrentProcessId proc

Source Edit

proc readLines(p: Process): (seq[string], int) {.
    ...raises: [OSError, IOError, ValueError], tags: [ReadIOEffect], forbids: [].}

Convenience function for working with startProcess to read data from a background process.

See also:

lines iterator

Example:

const opts = {poUsePath, poDaemon, poStdErrToStdOut}
var ps: seq[Process]
for prog in ["a", "b"]: # run 2 progs in parallel
  ps.add startProcess("nim", "", ["r", prog], nil, opts)
for p in ps:
  let (lines, exCode) = p.readLines
  if exCode != 0:
    for line in lines: echo line
  p.close

Source Edit

proc resume(p: Process) {....gcsafe, extern: "nosp$1", tags: [], raises: [],
                          forbids: [].}

Resumes the process p.

See also:

suspend proc
terminate proc
kill proc

Source Edit

proc running(p: Process): bool {....gcsafe, extern: "nosp$1", raises: [OSError],
                                 tags: [], forbids: [].}

Returns true if the process p is still running. Returns immediately. Source Edit

proc startProcess(command: string; workingDir: string = "";
                  args: openArray[string] = []; env: StringTableRef = nil;
                  options: set[ProcessOption] = {poStdErrToStdOut}): owned(
    Process) {....gcsafe, extern: "nosp$1", raises: [OSError, IOError],
               tags: [ExecIOEffect, ReadEnvEffect, RootEffect], forbids: [].}

Starts a process. Command is the executable file, workingDir is the process’s working directory. If workingDir == “” the current directory is used (default). args are the command line arguments that are passed to the process. On many operating systems, the first command line argument is the name of the executable. args should not contain this argument! env is the environment that will be passed to the process. If env == nil (default) the environment is inherited of the parent process. options are additional flags that may be passed to startProcess. See the documentation of ProcessOption for the meaning of these flags.

You need to close the process when done.

Note that you can’t pass any args if you use the option poEvalCommand, which invokes the system shell to run the specified command. In this situation you have to concatenate manually the contents of args to command carefully escaping/quoting any special characters, since it will be passed as is to the system shell. Each system/shell may feature different escaping rules, so try to avoid this kind of shell invocation if possible as it leads to non portable software.

Return value: The newly created process object. Nil is never returned, but OSError is raised in case of an error.

See also:

execProcesses proc,proc(int,Process))
execProcess proc
execCmd proc

Source Edit

proc suspend(p: Process) {....gcsafe, extern: "nosp$1", tags: [], raises: [],
                           forbids: [].}

Suspends the process p.

See also:

resume proc
terminate proc
kill proc

Source Edit

proc terminate(p: Process) {....gcsafe, extern: "nosp$1", tags: [],
                             raises: [OSError], forbids: [].}

Stop the process p.

On Posix OSes the procedure sends SIGTERM to the process. On Windows the Win32 API function TerminateProcess() is called to stop the process.

See also:

Source Edit

proc waitForExit(p: Process; timeout: int = -1): int {....gcsafe, extern: "nosp$1",
    raises: [OSError, ValueError], tags: [], forbids: [].}

Waits for the process to finish and returns p’s error code.

Warning: Be careful when using waitForExit for processes created without poParentStreams because they may fill output buffers, causing deadlock.

On posix, if the process has exited because of a signal, 128 + signal number will be returned.

Warning: When working with timeout parameters, remember that the value is typically expressed in milliseconds, and ensure that the correct unit of time is used to avoid unexpected behavior.

Source Edit

Iterators

iterator lines(p: Process; keepNewLines = false): string {.
    ...raises: [OSError, IOError, ValueError], tags: [ReadIOEffect], forbids: [].}

Convenience iterator for working with startProcess to read data from a background process.

See also:

readLines proc

Example:

const opts = {poUsePath, poDaemon, poStdErrToStdOut}
var ps: seq[Process]
for prog in ["a", "b"]: # run 2 progs in parallel
  ps.add startProcess("nim", "", ["r", prog], nil, opts)
for p in ps:
  var i = 0
  for line in p.lines:
    echo line
    i.inc
    if i > 100: break
  p.close

Source Edit

Exports

quoteShell, quoteShellWindows, quoteShellPosix

osproc

Imports

Types

Procs

Iterators

Exports