I.1.1 Creating Subprocesses—In General

There are three primitives that create a new subprocess in which to run a program.

call-process

creates a synchronous process

call-process-region

creates a synchronous process

make-process

creates an asynchronous process and returns a process object

The three functions are called in similar fashions; their common arguments are described here first.

The Program to Run

In all cases, the functions specify the program to be run.

exec-path

The filename may contain ‘~’, ‘.’, and ‘..’. If the file name is relative, the variable ‘exec-path’ contains a list of directories to search. Emacs initializes ‘exec-path’ when it starts up, based on the value of the environment variable ‘PATH’. nil in the list refers to default-directory. The variable exec-directory can also supply a directory to search.

Your exec-path has the contents:

Function: exec-directory ¶

The value of this variable is a string, the name of a directory that contains programs that come with GNU Emacs and are intended for Emacs to invoke. The program ‘movemail’ is an example of such a program; Rmail uses it to fetch new mail from an inbox.

Your exec-directory has the value:

/Applications/Emacs.app/Contents/MacOS/libexec/

Use the function ‘substitute-in-file-name’ to perform environment variable substitutions (‘$HOME’).

Function: substitute-in-file-name filename ¶

Substitute environment variables referred to in FILENAME. ‘$FOO’ where FOO is an environment variable name means to substitute the value of that variable.

(substitute-in-file-name "$HOME/foo") ⇒ "/xcssun/users/rms/foo"

Filename Arguments

Each of the subprocess-creating functions has a BUFFER-OR-NAME argument that specifies where the output from the program will go. It should be a buffer or a buffer name; if it is a buffer name, that will create the buffer if it does not already exist. It can also be ‘nil’, which says to discard the output, unless a custom filter function handles it.

For synchronous processes, you can send the output to a file instead of a buffer.

Standard Streams

By default, both standard output and standard error streams go to the same destination, but all the 3 primitives allow optionally to direct the standard error stream to a different destination.

Process Command-Line Arguments

All three of the subprocess-creating functions allow to specify command-line arguments for the process to run. The command-line arguments must all be strings, and they are supplied to the program as separate argument strings.

• For ‘call-process’ and ‘call-process-region’, these come in the form of a ‘&rest’ argument, ARGS.
• For ‘make-process’, both the program to run and its command-line arguments are specified as a list of strings.

Inheriting Environment

The subprocess inherits its environment from Emacs, but you can specify overrides for it with ‘process-environment’.

The subprocess gets its current directory from the value of ‘default-directory’.

• Specifying Shell Arguments