1. Module (chicken process)
    1. Processes
      1. process-execute
      2. process-fork
      3. process-run
      4. process-signal
      5. process-spawn
      6. process-wait
      7. process-sleep
      8. process
      9. process*
    2. Shell commands
      1. qs
      2. system
      3. system*
    3. Pipes
      1. call-with-input-pipe
      2. call-with-output-pipe
      3. close-input-pipe
      4. close-output-pipe
      5. create-pipe
      6. open-input-pipe
      7. open-output-pipe
      8. pipe/buf
      9. with-input-from-pipe
      10. with-output-to-pipe
    4. Windows specific notes

Module (chicken process)

This module offers procedures for interacting with subprocesses.

Processes

process-execute

[procedure] (process-execute PATHNAME [ARGUMENT-LIST [ENVIRONMENT-ALIST]])

Replaces the running process with a new process image from the program stored at PATHNAME, using the C library function execvp(3). If the optional argument ARGUMENT-LIST is given, then it should contain a list of strings which are passed as arguments to the subprocess. If the optional argument ENVIRONMENT-ALIST is supplied, then the library function execve(2) is used, and the environment passed in ENVIRONMENT-ALIST (which should be of the form (("<NAME>" . "<VALUE>") ...)) is given to the invoked process. Note that execvp(3) respects the current setting of the PATH environment variable while execve(3) does not.

This procedure never returns; it either replaces the process with a new one or it raises an exception in case something went wrong executing the program.

On Windows, these procedures all have an additional optional parameter EXACT-FLAG, which defaults to #f. When #f is passed, any argument string with embedded whitespace will be wrapped in quotes. When #t no such wrapping occurs.

process-fork

[procedure] (process-fork [THUNK [KILLOTHERS?]])

Creates a new child process with the UNIX system call fork(). Returns either the PID of the child process or 0. If THUNK is given, then the child process calls it as a procedure with no arguments and terminates. If THUNK is given and the optional argument KILLOTHERS? is true, then kill all other existing threads in the child process, leaving only the current thread to run THUNK and terminate.

NOTE: On native Windows builds (all except cygwin), this procedure is unimplemented and will raise an error.

process-run

[procedure] (process-run COMMANDLINE)
[procedure] (process-run COMMAND ARGUMENT-LIST)

Creates a new child process. The PID of the new process is returned.

process-signal

[procedure] (process-signal PID [SIGNAL])

Sends SIGNAL to the process with the id PID using the UNIX system call kill(). SIGNAL defaults to the value of the variable signal/term.

NOTE: On native Windows builds (all except cygwin), this procedure is unimplemented and will raise an error.

process-spawn

[procedure] (process-spawn MODE COMMAND [ARGUMENT-LIST [ENVIRONMENT-LIST [EXACT-FLAG]]])

Creates and runs a new process with the given COMMAND filename and the optional ARGUMENT-LIST and ENVIRONMENT-LIST. MODE specifies how exactly the process should be executed and must be one or more of the spawn/... flags listed below.

The EXACT-FLAG, default #f, controls quote-wrapping of argument strings. When #t quote-wrapping is not performed.

Returns:

NOTE: On all Unix-like builds (all except native MingW-based Windows platforms), this procedure is unimplemented and will raise an error.

[constant] spawn/overlay
[constant] spawn/wait
[constant] spawn/nowait
[constant] spawn/nowaito
[constant] spawn/detach

These variables contains special flags that specify the exact semantics of process-spawn:

process-wait

[procedure] (process-wait [PID [NOHANG]])

Suspends the current process until the child process with the id PID has terminated using the UNIX system call waitpid(). If PID is not given, then this procedure waits for any child process. If NOHANG is given and not #f then the current process is not suspended. This procedure returns three values:

Note that suspending the current process implies that all threads are suspended as well.

On Windows, process-wait always returns #t for a terminated process and only the exit status is available. (Windows does not provide signals as an interprocess communication method.)

process-sleep

[procedure] (process-sleep SECONDS)

Puts the process to sleep for SECONDS. Returns either 0 if the time has completely elapsed, or the number of remaining seconds, if a signal occurred.

process

[procedure] (process COMMANDLINE)
[procedure] (process COMMAND ARGUMENT-LIST [ENVIRONMENT-ALIST ENCODING])

Creates a subprocess and returns three values: an input port from which data written by the sub-process can be read, an output port from which any data written to will be received as input in the sub-process and the process-id of the started sub-process. Blocking reads and writes to or from the ports returned by process only block the current thread, not other threads executing concurrently.

Standard error for the subprocess is linked up to the current process's standard error (see process* if you want to reify its standard error into a separate port).

ENCODING should be a symbol specifying the encoding to be used for I/O operations, the default is utf-8. The encodings for the returned in and output ports can be subsequently changed by using the port-encoding setter.

Not using the shell may be preferrable for security reasons.

Once both the input- and output ports are closed, an implicit waitpid(3) is done to wait for the subprocess to finish or to reap a subprocess that has terminated. If the subprocess has not finished, waiting for it will necessarily block all executing threads.

process*

[procedure] (process* COMMANDLINE)
[procedure] (process* COMMAND ARGUMENT-LIST [ENVIRONMENT-ALIST ENCODING])

Like process but returns 4 values: an input port from which data written by the sub-process can be read, an output port from which any data written to will be received as input in the sub-process, the process-id of the started sub-process, and an input port from which data written by the sub-process to stderr can be read.

Shell commands

The commands below are all string-based. This means you have to be very careful to properly quote any arguments to subprocesses, to avoid shell injection bugs which can lead to arbitrary code execution.

You can quote arguments with the qs procedure, but it is strongly recommended you use fork with process-execute or the multi-argument versions of the process, process* or process-run procedures.

qs

[procedure] (qs STRING [PLATFORM])

Escapes STRING suitably for passing to a shell command on PLATFORM. PLATFORM defaults to the value of (build-platform) and indicates in which style the argument should be quoted. On Windows systems, the string is simply enclosed in double-quote (") characters, on UNIXish systems, characters that would have a special meaning to the shell are escaped using backslash (\).

system

[procedure] (system STRING)

Execute shell command. The functionality offered by this procedure depends on the capabilities of the host shell. If the forking of a subprocess failed, an exception is raised. Otherwise the return status of the subprocess is returned unaltered.

On a UNIX system, that value is the raw return value of waitpid(2), which contains signal, core dump and exit status. It is 0 on success. To pull out the signal number or exit status portably requires POSIX calls, but in a pinch you can use something like this:

;; Returns two values: #t if the process exited normally or #f otherwise;
;; and either the exit status, or the signal number if terminated via signal.
(define (process-status rc)
  (define (wait-signaled? x) (not (= 0 (bitwise-and x 127))))
  (define (wait-signal x) (bitwise-and x 127))
  (define (wait-exit-status x) (arithmetic-shift x -8))
  (if (wait-signaled? rc)
      (values #f (wait-signal rc))
      (values #t (wait-exit-status rc))))

#;> (process-status (system "exit 42"))
#t
42

system*

[procedure] (system* STRING)

Similar to (system STRING), but signals an error should the invoked program return a nonzero exit status.

Pipes

call-with-input-pipe

call-with-output-pipe

[procedure] (call-with-input-pipe CMDLINE PROC [MODE])
[procedure] (call-with-output-pipe CMDLINE PROC [MODE])

Call PROC with a single argument: a input- or output port for a pipe connected to the subprocess named in CMDLINE. If PROC returns normally, the pipe is closed and any result values are returned.

close-input-pipe

close-output-pipe

[procedure] (close-input-pipe PORT)
[procedure] (close-output-pipe PORT)

Closes the pipe given in PORT and waits until the connected subprocess finishes. The exit-status code of the invoked process is returned.

create-pipe

[procedure] (create-pipe)

The fundamental pipe-creation operator. Calls the C function pipe() and returns 2 values: the file-descriptors of the input- and output-ends of the pipe.

On Windows, there is an optional parameter MODE, which defaults to open/binary | open/noinherit. This can be open/binary or open/text, optionally or'ed with open/noinherit.

open-input-pipe

[procedure] (open-input-pipe CMDLINE [MODE])

Spawns a subprocess with the command-line string CMDLINE and returns a port, from which the output of the process can be read. If MODE is specified, it should be the keyword #:text (the default) or #:binary.

open-output-pipe

[procedure] (open-output-pipe CMDLINE [MODE])

Spawns a subprocess with the command-line string CMDLINE and returns a port. Anything written to that port is treated as the input for the process. If MODE is specified, it should be the keyword #:text (the default) or #:binary.

pipe/buf

[constant] pipe/buf

This variable contains the maximal number of bytes that can be written atomically into a pipe or FIFO.

with-input-from-pipe

with-output-to-pipe

[procedure] (with-input-from-pipe CMDLINE THUNK [MODE])
[procedure] (with-output-to-pipe CMDLINE THUNK [MODE])

Temporarily set the value of current-input-port/current-output-port to a port for a pipe connected to the subprocess named in CMDLINE and call the procedure THUNK with no arguments. After THUNK returns normally the pipe is closed and the standard input-/output port is restored to its previous value and any result values are returned.

(with-output-to-pipe
  "gs -dNOPAUSE -sDEVICE=jpeg -dBATCH -sOutputFile=signballs.jpg -g600x600 -q -"
  (lambda ()
    (print #<<EOF
 %!IOPSC-1993 %%Creator: HAYAKAWA Takashi<xxxxxxxx@xx.xxxxxx.xx.xx>
 /C/neg/d/mul/R/rlineto/E/exp/H{{cvx def}repeat}def/T/dup/g/gt/r/roll/J/ifelse 8
 H/A/copy(z&v4QX&93r9AxYQOZomQalxS2w!!O&vMYa43d6r93rMYvx2dca!D&cjSnjSnjjS3o!v&6A
 X&55SAxM1CD7AjYxTTd62rmxCnTdSST0g&12wECST!&!J0g&D1!&xM0!J0g!l&544dC2Ac96ra!m&3A
 F&&vGoGSnCT0g&wDmlvGoS8wpn6wpS2wTCpS1Sd7ov7Uk7o4Qkdw!&Mvlx1S7oZES3w!J!J!Q&7185d
 Z&lx1CS9d9nE4!k&X&MY7!&1!J!x&jdnjdS3odS!N&mmx1C2wEc!G&150Nx4!n&2o!j&43r!U&0777d
 ]&2AY2A776ddT4oS3oSnMVC00VV0RRR45E42063rNz&v7UX&UOzF!F!J![&44ETCnVn!a&1CDN!Y&0M
 V1c&j2AYdjmMdjjd!o&1r!M){( )T 0 4 3 r put T(/)g{T(9)g{cvn}{cvi}J}{($)g[]J}J
 cvx}forall/moveto/p/floor/w/div/S/add 29 H[{[{]setgray fill}for Y}for showpage
 EOF
 ) ) )

Windows specific notes

Use of UTF8 encoded strings for pathnames is not supported. Windows uses a 16-bit UNICODE encoding with special system calls for wide-character support. Only single-byte string encoding can be used.

Previous: Module (chicken pretty-print)

Next: Module (chicken process signal)