Skip to content

Command Specifications

make-command creates an immutable-by-interface command-spec:

(process-kit:make-command
 "/usr/bin/env" nil
 :search nil
 :environment-policy :inherit
 :environment-update (list (cons "LANG" "C")
                           (cons "DEBUG" nil))
 :directory #P"/tmp/"
 :stdin :inherit
 :stdout :capture
 :stderr :capture
 :result-type :string
 :external-format :utf-8
 :decoding-error-policy :replace)

Its positional arguments are program and a proper list of string arguments.

Environment

environment-policy is either :inherit or a complete list of "KEY=VALUE" strings; an empty list requests an empty environment. environment-update is an ordered alist: a string value sets a variable and nil deletes it. Updates are applied after the base policy.

Executable search is disabled by default. With search (or :search) true, cl-process-kit resolves the executable before launching it, using only the PATH in the effective environment:

  • :inherit therefore uses a copied parent PATH when present.
  • A replacement environment without PATH performs no search and signals process-launch-error.
  • Programs containing a slash bypass PATH lookup entirely.
  • Relative programs and PATH components (including empty components) are resolved against the effective working directory.

Search failure modes

A candidate that is missing, is a directory, or is not executable signals process-launch-error.

Stdio policies

The stdin, stdout, and stderr policies accept :inherit, :null, :pipe, :capture, a stream, or a pathname; stderr additionally accepts :stdout.

result-type is :string or :octets.

Text encoding

external-format is :default (UTF-8) or any encoding designator cl-codec-kit registers -- :utf-8, :utf-16be/:utf-16le, :utf-32be/:utf-32le, :ucs-2be/:ucs-2le, :ascii, :iso-8859-1, and their aliases. make-command rejects any other designator immediately, including the generic, byte-order-sensing :utf-16/ :utf-32/:ucs-2 (each senses its byte-order mark once per decode call, which is unsafe across the repeated, streaming decode calls captured output goes through) and any SBCL external-format cl-codec-kit does not yet implement.

Decoding errors

decoding-error-policy controls what happens when captured output isn't valid text under external-format, and applies only when result-type is :string. It is :replace by default: malformed byte sequences are substituted with the Unicode replacement character, and the decoder holds back an incomplete multi-byte character at a read-buffer boundary until the rest arrives rather than misreading it as invalid -- for every supported external-format, not just UTF-8. :error instead signals process-io-error the first time a malformed sequence is encountered. This option is shared by run/communicate — make-command's decoding-error-policy is the command-spec-driven way to set the same behavior for run-command.

Accessors

Accessors are named command-program, command-arguments, command-search, command-environment-policy, command-environment-update, command-directory, command-stdin, command-stdout, command-stderr, command-result-type, command-external-format, and command-decoding-error-policy. command-p tests the type.

Untrusted input

Prefer make-command plus run-command for untrusted data: arguments are passed directly without shell interpolation. run-shell invokes /bin/sh -c; never concatenate untrusted input into its command string.