Module

Node.ChildProcess

Package: purescript-node-child-process
Repository: purescript-node/purescript-node-child-process

This module contains various types and functions to allow you to spawn and interact with child processes.

It is intended to be imported qualified, as follows:

import Node.ChildProcess as ChildProcess
-- or...
import Node.ChildProcess as CP

The Node.js documentation forms the basis for this module and has in-depth documentation about runtime behaviour.

Meaning of `appendStdio`

By default, ChildProcess uses safeStdio for its stdio option. However, Node allows one to pass in additional values besides the typical 3 (i.e. stdin, stdout, stderr) and the IPC channel that might be used (i.e. ipc). Thus, appendStdio is an option defined in this library that doesn't exist in the Node docs. It exists to allow the end-user to append additional values to the safeStdio value used here. For example,

spawn' file args (_ { appendStdio = Just [ fileDescriptor8, pipe, pipe ]})

would end up calling spawn with the following stdio:

-- i.e. `safeStdio <> [ fileDescriptor8, pipe, pipe ]`
[pipe, pipe, pipe, ipc, fileDescriptor8, pipe, pipe]

#ChildProcess Source

newtype ChildProcess

Opaque type returned by spawn, fork and exec. Needed as input for most methods in this module.

ChildProcess extends EventEmitter

#toEventEmitter Source

toEventEmitter :: ChildProcess -> EventEmitter

#toUnsafeChildProcess Source

toUnsafeChildProcess :: ChildProcess -> UnsafeChildProcess

#closeH Source

closeH :: EventHandle ChildProcess (Exit -> Effect Unit) (EffectFn2 (Nullable Int) (Nullable String) Unit)

#disconnectH Source

disconnectH :: EventHandle0 ChildProcess

#errorH Source

errorH :: EventHandle1 ChildProcess SystemError

#exitH Source

exitH :: EventHandle ChildProcess (Exit -> Effect Unit) (EffectFn2 (Nullable Int) (Nullable String) Unit)

#messageH Source

messageH :: EventHandle ChildProcess (Foreign -> Maybe Handle -> Effect Unit) (EffectFn2 Foreign (Nullable Handle) Unit)

#spawnH Source

spawnH :: EventHandle0 ChildProcess

#stdin Source

stdin :: ChildProcess -> Writable ()

The standard input stream of a child process.

#stdout Source

stdout :: ChildProcess -> Readable ()

The standard output stream of a child process.

#stderr Source

stderr :: ChildProcess -> Readable ()

The standard error stream of a child process.

#pid Source

pid :: ChildProcess -> Effect (Maybe Pid)

The process ID of a child process. This will be Nothing until the process has spawned. Note that if the process has already exited, another process may have taken the same ID, so be careful!

#pidExists Source

pidExists :: ChildProcess -> Effect Boolean

#connected Source

connected :: ChildProcess -> Effect Boolean

Indicates whether it is still possible to send and receive messages from the child process.

#disconnect Source

disconnect :: ChildProcess -> Effect Unit

Closes the IPC channel between parent and child.

#exitCode Source

exitCode :: ChildProcess -> Effect (Maybe Int)

#kill Source

kill :: ChildProcess -> Effect Boolean

#kill' Source

kill' :: KillSignal -> ChildProcess -> Effect Boolean

#killSignal Source

killSignal :: Signal -> ChildProcess -> Effect Boolean

Send a signal to a child process. In the same way as the unix kill(2) system call, sending a signal to a child process won't necessarily kill it.

The resulting effects of this function depend on the process and the signal. They can vary from system to system. The child process might emit an "error" event if the signal could not be delivered.

#killed Source

killed :: ChildProcess -> Effect Boolean

#ref Source

ref :: ChildProcess -> Effect Unit

#unref Source

unref :: ChildProcess -> Effect Unit

#signalCode Source

signalCode :: ChildProcess -> Effect (Maybe String)

#spawnFile Source

spawnFile :: ChildProcess -> String

#spawnArgs Source

spawnArgs :: ChildProcess -> Array String

#stdio Source

stdio :: ChildProcess -> Array StdIO

#spawnSync Source

spawnSync :: String -> Array String -> Effect SpawnSyncResult

#SpawnSyncOptions Source

type SpawnSyncOptions = { appendStdio :: Maybe (Array StdIO), argv0 :: Maybe String, cwd :: Maybe String, env :: Maybe (Object String), gid :: Maybe Gid, input :: Maybe Buffer, killSignal :: Maybe KillSignal, maxBuffer :: Maybe Number, shell :: Maybe Shell, timeout :: Maybe Milliseconds, uid :: Maybe Uid, windowsHide :: Maybe Boolean, windowsVerbatimArguments :: Maybe Boolean }

cwd <string> | <URL> Current working directory of the child process.
input <string> | <Buffer> | <TypedArray> | <DataView> The value which will be passed as stdin to the spawned process. Supplying this value will override stdio[0].
argv0 <string> Explicitly set the value of argv[0] sent to the child process. This will be set to command if not specified.
env <Object> Environment key-value pairs. Default: process.env.
uid <number> Sets the user identity of the process (see setuid(2)).
gid <number> Sets the group identity of the process (see setgid(2)).
timeout <number> In milliseconds the maximum amount of time the process is allowed to run. Default: undefined.
killSignal <string> | <integer> The signal value to be used when the spawned process will be killed. Default: 'SIGTERM'.
maxBuffer <number> Largest amount of data in bytes allowed on stdout or stderr. If exceeded, the child process is terminated and any output is truncated. See caveat at maxBuffer and Unicode. Default: 1024 * 1024.
shell <boolean> | <string> If true, runs command inside of a shell. Uses '/bin/sh' on Unix, and process.env.ComSpec on Windows. A different shell can be specified as a string. See Shell requirements and Default Windows shell. Default: false (no shell).
windowsVerbatimArguments <boolean> No quoting or escaping of arguments is done on Windows. Ignored on Unix. This is set to true automatically when shell is specified and is CMD. Default: false.
windowsHide <boolean> Hide the subprocess console window that would normally be created on Windows systems. Default: false.

#spawnSync' Source

spawnSync' :: String -> Array String -> (SpawnSyncOptions -> SpawnSyncOptions) -> Effect SpawnSyncResult

#spawn Source

spawn :: String -> Array String -> Effect ChildProcess

Spawn a child process. Note that, in the event that a child process could not be spawned (for example, if the executable was not found) this will not throw an error. Instead, the ChildProcess will be created anyway, but it will immediately emit an 'error' event.

#SpawnOptions Source

type SpawnOptions = { appendStdio :: Maybe (Array StdIO), argv0 :: Maybe String, cwd :: Maybe String, detached :: Maybe Boolean, env :: Maybe (Object String), gid :: Maybe Gid, killSignal :: Maybe KillSignal, serialization :: Maybe String, shell :: Maybe Shell, timeout :: Maybe Milliseconds, uid :: Maybe Uid, windowsHide :: Maybe Boolean, windowsVerbatimArguments :: Maybe Boolean }

cwd <string> | <URL> Current working directory of the child process.
env <Object> Environment key-value pairs. Default: process.env.
argv0 <string> Explicitly set the value of argv[0] sent to the child process. This will be set to command if not specified.
detached <boolean> Prepare child to run independently of its parent process. Specific behavior depends on the platform, see options.detached).
uid <number> Sets the user identity of the process (see setuid(2)).
gid <number> Sets the group identity of the process (see setgid(2)).
serialization <string> Specify the kind of serialization used for sending messages between processes. Possible values are 'json' and 'advanced'. See Advanced serialization for more details. Default: 'json'.
shell <boolean> | <string> If true, runs command inside of a shell. Uses '/bin/sh' on Unix, and process.env.ComSpec on Windows. A different shell can be specified as a string. See Shell requirements and Default Windows shell. Default: false (no shell).
windowsVerbatimArguments <boolean> No quoting or escaping of arguments is done on Windows. Ignored on Unix. This is set to true automatically when shell is specified and is CMD. Default: false.
windowsHide <boolean> Hide the subprocess console window that would normally be created on Windows systems. Default: false.
signal <AbortSignal> allows aborting the child process using an AbortSignal.
timeout <number> In milliseconds the maximum amount of time the process is allowed to run. Default: undefined.
killSignal <string> | <integer> The signal value to be used when the spawned process will be killed by timeout or abort signal. Default: 'SIGTERM'.

#spawn' Source

spawn' :: String -> Array String -> (SpawnOptions -> SpawnOptions) -> Effect ChildProcess

#execSync Source

execSync :: String -> Effect Buffer

Generally identical to exec, with the exception that the method will not return until the child process has fully closed. Returns: The stdout from the command.

#ExecSyncOptions Source

type ExecSyncOptions = { appendStdio :: Maybe (Array StdIO), cwd :: Maybe String, env :: Maybe (Object String), gid :: Maybe Gid, input :: Maybe Buffer, killSignal :: Maybe KillSignal, maxBuffer :: Maybe Number, shell :: Maybe String, timeout :: Maybe Milliseconds, uid :: Maybe Uid, windowsHide :: Maybe Boolean }

cwd <string> | <URL> Current working directory of the child process.
input <string> | <Buffer> | <TypedArray> | <DataView> The value which will be passed as stdin to the spawned process. Supplying this value will override stdio[0].
stdio <string> | <Array> Child's stdio configuration. stderr by default will be output to the parent process' stderr unless stdio is specified. Default: 'pipe'.
env <Object> Environment key-value pairs. Default: process.env.
shell <string> Shell to execute the command with. See Shell requirements and Default Windows shell. Default: '/bin/sh' on Unix, process.env.ComSpec on Windows.
uid <number> Sets the user identity of the process. (See setuid(2)).
gid <number> Sets the group identity of the process. (See setgid(2)).
timeout <number> In milliseconds the maximum amount of time the process is allowed to run. Default: undefined.
killSignal <string> | <integer> The signal value to be used when the spawned process will be killed. Default: 'SIGTERM'.
maxBuffer <number> Largest amount of data in bytes allowed on stdout or stderr. If exceeded, the child process is terminated and any output is truncated. See caveat at maxBuffer and Unicode. Default: 1024 * 1024.
encoding <string> The encoding used for all stdio inputs and outputs. Default: 'buffer'.
windowsHide <boolean> Hide the subprocess console window that would normally be created on Windows systems. Default: false.

#execSync' Source

execSync' :: String -> (ExecSyncOptions -> ExecSyncOptions) -> Effect Buffer

#exec Source

exec :: String -> Effect ChildProcess

Similar to spawn, except that this variant will:

run the given command with the shell,
buffer output, and wait until the process has exited.

Note that the child process will be killed if the amount of output exceeds a certain threshold (the default is defined by Node.js).

#ExecResult Source

type ExecResult = { error :: Maybe SystemError, stderr :: Buffer, stdout :: Buffer }

The combined output of a process called with exec.

#ExecOptions Source

type ExecOptions = { cwd :: Maybe String, env :: Maybe (Object String), gid :: Maybe Gid, killSignal :: Maybe KillSignal, maxBuffer :: Maybe Number, shell :: Maybe Shell, timeout :: Maybe Milliseconds, uid :: Maybe Uid, windowsHide :: Maybe Boolean }

cwd <string> | <URL> Current working directory of the child process.
env <Object> Environment key-value pairs. Default: process.env.
timeout <number> Default: 0
maxBuffer <number> Largest amount of data in bytes allowed on stdout or stderr. If exceeded, the child process is terminated and any output is truncated. See caveat at maxBuffer and Unicode. Default: 1024 * 1024.
killSignal <string> | <integer> Default: 'SIGTERM'
uid <number> Sets the user identity of the process (see setuid(2)).
gid <number> Sets the group identity of the process (see setgid(2)).
windowsHide <boolean> Hide the subprocess console window that would normally be created on Windows systems. Default: false.
shell <boolean> | <string> If true, runs command inside of a shell. Uses '/bin/sh' on Unix, and process.env.ComSpec on Windows. A different shell can be specified as a string. See Shell requirements and Default Windows shell. Default: false (no shell).

#exec' Source

exec' :: String -> (ExecOptions -> ExecOptions) -> (ExecResult -> Effect Unit) -> Effect ChildProcess

Similar to spawn, except that this variant will:

run the given command with the shell,
buffer output, and wait until the process has exited before calling the callback.

Note that the child process will be killed if the amount of output exceeds a certain threshold (the default is defined by Node.js).

#execFileSync Source

execFileSync :: String -> Array String -> Effect Buffer

Generally identical to execFile, with the exception that the method will not return until the child process has fully closed. Returns: The stdout from the command.

#ExecFileSyncOptions Source

type ExecFileSyncOptions = { appendStdio :: Maybe (Array StdIO), cwd :: Maybe String, env :: Maybe (Object String), gid :: Maybe Gid, input :: Maybe Buffer, killSignal :: Maybe KillSignal, maxBuffer :: Maybe Number, shell :: Maybe Shell, timeout :: Maybe Milliseconds, uid :: Maybe Uid, windowsHide :: Maybe Boolean }

cwd <string> | <URL> Current working directory of the child process.
input <string> | <Buffer> | <TypedArray> | <DataView> The value which will be passed as stdin to the spawned process. Supplying this value will override stdio[0].
env <Object> Environment key-value pairs. Default: process.env.
uid <number> Sets the user identity of the process (see setuid(2)).
gid <number> Sets the group identity of the process (see setgid(2)).
timeout <number> In milliseconds the maximum amount of time the process is allowed to run. Default: undefined.
killSignal <string> | <integer> The signal value to be used when the spawned process will be killed. Default: 'SIGTERM'.
maxBuffer <number> Largest amount of data in bytes allowed on stdout or stderr. If exceeded, the child process is terminated. See caveat at maxBuffer and Unicode. Default: 1024 * 1024.
windowsHide <boolean> Hide the subprocess console window that would normally be created on Windows systems. Default: false.
shell <boolean> | <string> If true, runs command inside of a shell. Uses '/bin/sh' on Unix, and process.env.ComSpec on Windows. A different shell can be specified as a string. See Shell requirements and Default Windows shell. Default: false (no shell).

#execFileSync' Source

execFileSync' :: String -> Array String -> (ExecFileSyncOptions -> ExecFileSyncOptions) -> Effect Buffer

#execFile Source

execFile :: String -> Array String -> Effect ChildProcess

Like exec, except instead of using a shell, it passes the arguments directly to the specified command.

#ExecFileOptions Source

type ExecFileOptions = { cwd :: Maybe String, env :: Maybe (Object String), gid :: Maybe Gid, killSignal :: Maybe KillSignal, maxBuffer :: Maybe Number, shell :: Maybe Shell, timeout :: Maybe Milliseconds, uid :: Maybe Uid, windowsHide :: Maybe Boolean, windowsVerbatimArguments :: Maybe Boolean }

cwd <string> | <URL> Current working directory of the child process.
env <Object> Environment key-value pairs. Default: process.env.
timeout <number> Default: 0
maxBuffer <number> Largest amount of data in bytes allowed on stdout or stderr. If exceeded, the child process is terminated and any output is truncated. See caveat at maxBuffer and Unicode. Default: 1024 * 1024.
killSignal <string> | <integer> Default: 'SIGTERM'
uid <number> Sets the user identity of the process (see setuid(2)).
gid <number> Sets the group identity of the process (see setgid(2)).
windowsHide <boolean> Hide the subprocess console window that would normally be created on Windows systems. Default: false.
windowsVerbatimArguments <boolean> No quoting or escaping of arguments is done on Windows. Ignored on Unix. Default: false.
shell <boolean> | <string> If true, runs command inside of a shell. Uses '/bin/sh' on Unix, and process.env.ComSpec on Windows. A different shell can be specified as a string. See Shell requirements and Default Windows shell. Default: false (no shell).

#execFile' Source

execFile' :: String -> Array String -> (ExecFileOptions -> ExecFileOptions) -> (ExecResult -> Effect Unit) -> Effect ChildProcess

#fork Source

fork :: String -> Array String -> Effect ChildProcess

A special case of spawn for creating Node.js child processes. The first argument is the module to be run, and the second is the argv (command line arguments).

#fork' Source

fork' :: String -> Array String -> (ForkOptions -> ForkOptions) -> Effect ChildProcess

#send Source

send :: forall props. Record props -> Maybe Handle -> ChildProcess -> Effect Boolean

Send messages to the (nodejs) child process.

See the node documentation for in-depth documentation.

#send' Source

send' :: forall props. Record props -> Maybe Handle -> (SendOptions -> SendOptions) -> (Maybe Error -> Effect Unit) -> ChildProcess -> Effect Boolean

Modules: Node.ChildProcess; Node.ChildProcess.Aff; Node.ChildProcess.Types; Node.UnsafeChildProcess.Safe; Node.UnsafeChildProcess.Unsafe

Node.ChildProcess

Meaning of appendStdio

#ChildProcess Source

#toEventEmitter Source

#toUnsafeChildProcess Source

#closeH Source

#disconnectH Source

#errorH Source

#exitH Source

#messageH Source

#spawnH Source

#stdin Source

#stdout Source

#stderr Source

#pid Source

#pidExists Source

#connected Source

#disconnect Source

#exitCode Source

#kill Source

#kill' Source

#killSignal Source

#killed Source

#ref Source

#unref Source

#signalCode Source

#spawnFile Source

#spawnArgs Source

#stdio Source

#spawnSync Source

#SpawnSyncOptions Source

#spawnSync' Source

#spawn Source

#SpawnOptions Source

#spawn' Source

#execSync Source

#ExecSyncOptions Source

#execSync' Source

#exec Source

#ExecResult Source

#ExecOptions Source

#exec' Source

#execFileSync Source

#ExecFileSyncOptions Source

#execFileSync' Source

#execFile Source

#ExecFileOptions Source

#execFile' Source

#fork Source

#fork' Source

#send Source

#send' Source

Meaning of `appendStdio`