Types
PProcess = ref TProcess
- represents an operating system process
TProcessOption = 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 trused source. poStdErrToStdOut, ## merge stdout and stderr to the stdout stream poParentStreams ## use the parent's streams
- options that can be passed startProcess
Consts
poUseShell = poUsePath
- Deprecated alias for poUsePath.
Procs
proc quoteShellWindows(s: string): string {.noSideEffect, rtl, extern: "nosp$1", raises: [], tags: [].}
- Quote s, so it can be safely passed to Windows API. Based on Python's subprocess.list2cmdline See http://msdn.microsoft.com/en-us/library/17w5ykft.aspx
proc quoteShellPosix(s: string): string {.noSideEffect, rtl, extern: "nosp$1", raises: [], tags: [].}
- Quote s, so it can be safely passed to POSIX shell. Based on Python's pipes.quote
proc quoteShell(s: string): string {.noSideEffect, rtl, extern: "nosp$1", raises: [], tags: [].}
- Quote s, so it can be safely passed to shell.
proc startCmd(command: string; options: set[TProcessOption] = {poStdErrToStdOut, poUsePath}): PProcess {. tags: [FExecIO, FReadEnv], deprecated, raises: [E_Base].}
- Deprecated - use startProcess directly.
proc processID(p: PProcess): int {.rtl, extern: "nosp$1", raises: [], tags: [].}
- returns p's process ID.
proc inputHandle(p: PProcess): TFileHandle {.rtl, extern: "nosp$1", tags: [], raises: [].}
-
returns p's input file handle for writing to.
Warning: The returned TFileHandle should not be closed manually as it is closed when closing the PProcess p.
proc outputHandle(p: PProcess): TFileHandle {.rtl, extern: "nosp$1", tags: [], raises: [].}
-
returns p's output file handle for reading from.
Warning: The returned TFileHandle should not be closed manually as it is closed when closing the PProcess p.
proc errorHandle(p: PProcess): TFileHandle {.rtl, extern: "nosp$1", tags: [], raises: [].}
-
returns p's error file handle for reading from.
Warning: The returned TFileHandle should not be closed manually as it is closed when closing the PProcess p.
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; args: openArray[string] = []; env: PStringTable = nil; options: set[TProcessOption] = { poStdErrToStdOut, poUsePath, poEvalCommand}): 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. WARNING: this function uses poEvalCommand by default for backward compatibility. Make sure to pass options explicitly.
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, E_Base, 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.
Warning: Be careful when using waitForExit for processes created without poParentStreams because they may fill output buffers, causing deadlock.
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 error 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, poUsePath}): 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.