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.