# Module osproc

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

# Imports

strutils, os, strtabs, streams, posix

# Types

    PProcess = ref TProcess

  represents an operating system process

    TProcessOption = enum
      poEchoCmd,                  ## echo the command before execution
      poUseShell, ## use the shell to execute the command; NOTE: This
                  ## often creates a security hole!
      poStdErrToStdOut,           ## merge stdout and stderr to the stdout stream
      poParentStreams             ## use the parent's streams

  options that can be passed startProcess

# Procs

    proc startCmd(command: string;
                  options: set[TProcessOption] = {poStdErrToStdOut, poUseShell}): PProcess {.
        tags: [FExecIO, FReadEnv], raises: [E_Base].}

  a simpler version of startProcess that parses the command line into program and arguments and then calls startProcess with the empty string for workingDir and the nil string table for env.

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

  returns p's process ID.

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

  returns the numer of the processors/cores the machine has. Returns 0 if it cannot be detected.

    proc execProcesses(cmds: openarray[string];
                       options = {poStdErrToStdOut, poParentStreams};
                       n = countProcessors()): int {.rtl, extern: "nosp$1",
        tags: [FExecIO, FTime, FReadEnv], raises: [E_Base].}

  executes the commands cmds in parallel. Creates n processes that execute in parallel. The highest return value of all processes is returned.

    proc execProcess(command: string;
                     options: set[TProcessOption] = {poStdErrToStdOut, poUseShell}): TaintedString {.
        rtl, extern: "nosp$1", tags: [FExecIO, FReadIO], raises: [E_Base].}

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

    proc startProcess(command: string; workingDir: string = "";
                      args: openarray[string] = []; env: PStringTable = nil;
                      options: set[TProcessOption] = {poStdErrToStdOut}): PProcess {.
        rtl, extern: "nosp$1", tags: [FExecIO, FReadEnv], raises: [EOS, E_Base].}

  Starts a process. Command is the executable file, workingDir is the process's working directory. If `workingDir == ""` the current directory is used. 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` the environment is inherited of the parent process. options are additional flags that may be passed to startProcess. See the documentation of `TProcessOption` for the meaning of these flags. You need to close the process when done.

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

    proc close(p: PProcess) {.rtl, extern: "nosp$1", tags: [], raises: [E_Base].}

  When the process has finished executing, cleanup related handles

    proc suspend(p: PProcess) {.rtl, extern: "nosp$1", tags: [], raises: [EOS].}

  Suspends the process p.

    proc resume(p: PProcess) {.rtl, extern: "nosp$1", tags: [], raises: [EOS].}

  Resumes the process p.

    proc running(p: PProcess): bool {.rtl, extern: "nosp$1", tags: [], raises: [].}

  Returns true iff the process p is still running. Returns immediately.

    proc terminate(p: PProcess) {.rtl, extern: "nosp$1", tags: [], raises: [EOS].}

  Terminates the process p.

    proc waitForExit(p: PProcess; timeout: int = - 1): int {.rtl, extern: "nosp$1",
        tags: [], raises: [EOS].}

  waits for the process to finish and returns p's error code.

    proc peekExitCode(p: PProcess): int {.tags: [], raises: [].}

  return -1 if the process is still running. Otherwise the process' exit code

    proc inputStream(p: PProcess): PStream {.rtl, extern: "nosp$1", tags: [],
        raises: [EOS].}

  returns `p`'s input stream for writing to

  Warning: The returned PStream should not be closed manually as it is closed when closing the PProcess `p`.

    proc outputStream(p: PProcess): PStream {.rtl, extern: "nosp$1", tags: [],
        raises: [EOS].}

  returns `p`'s output stream for reading from

  Warning: The returned PStream should not be closed manually as it is closed when closing the PProcess `p`.

    proc errorStream(p: PProcess): PStream {.rtl, extern: "nosp$1", tags: [],
        raises: [EOS].}

  returns `p`'s output stream for reading from

  Warning: The returned PStream should not be closed manually as it is closed when closing the PProcess `p`.

    proc execCmd(command: string): int {.rtl, extern: "nosp$1", tags: [FExecIO],
                                         raises: [].}

  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.

    proc select(readfds: var seq[PProcess]; timeout = 500): int {.raises: [],
        tags: [].}

  select with a sensible Nimrod interface. timeout is in miliseconds. Specify -1 for no timeout. Returns the number of processes that are ready to read from. The processes that are ready to be read from are removed from readfds.

  Warning: This function may give unexpected or completely wrong results on Windows.

    proc execCmdEx(command: string;
                   options: set[TProcessOption] = {poStdErrToStdOut, poUseShell}): tuple[
        output: TaintedString, exitCode: int] {.tags: [FExecIO, FReadIO],
        raises: [E_Base, EOS].}

  a convenience proc that runs the command, grabs all its output and exit code and returns both.

Generated: 2013-05-21 09:55:09 UTC