— Function: make-process &rest args

This function is the basic low-level primitive for starting asynchronous subprocesses. It returns a process object representing the subprocess. Compared to the more high-level start-process, described below, it takes keyword arguments, is more flexible, and allows to specify process filters and sentinels in a single call.

The arguments args are a list of keyword/argument pairs. Omitting a keyword is always equivalent to specifying it with value nil. Here are the meaningful keywords:

:name name

Use the string name as the process name; if a process with this name already exists, then name is modified (by appending ‘<1>’, etc.) to be unique.

:buffer buffer

Use buffer as the process buffer. If the value is nil, the subprocess is not associated with any buffer.

:command command

Use command as the command line of the process. The value should be a list starting with the program's executable file name, followed by strings to give to the program as its arguments. If the first element of the list is nil, Emacs opens a new pseudoterminal (pty) and associates its input and output with buffer, without actually running any program; the rest of the list elements are ignored in that case.

:coding coding

If coding is a symbol, it specifies the coding system to be used for both reading and writing of data from and to the connection. If coding is a cons cell (decoding . encoding), then decoding will be used for reading and encoding for writing. The coding system used for encoding the data written to the program is also used for encoding the command-line arguments (but not the program itself, whose file name is encoded as any other file name; see file-name-coding-system).

If coding is nil, the default rules for finding the coding system will apply. See Default Coding Systems.

:connection-type type

Initialize the type of device used to communicate with the subprocess. Possible values are pty to use a pty, pipe to use a pipe, or nil to use the default derived from the value of the process-connection-type variable. This parameter and the value of process-connection-type are ignored if a non-nil value is specified for the :stderr parameter; in that case, the type will always be pipe. On systems where ptys are not available (MS-Windows), this parameter is likewise ignored, and pipes are used unconditionally.

:noquery query-flag

Initialize the process query flag to query-flag. See Query Before Exit.

:stop stopped

If stopped is non-nil, start the process in the stopped state.

:filter filter

Initialize the process filter to filter. If not specified, a default filter will be provided, which can be overridden later. See Filter Functions.

:sentinel sentinel

Initialize the process sentinel to sentinel. If not specified, a default sentinel will be used, which can be overridden later. See Sentinels.

:stderr stderr

Associate stderr with the standard error of the process. A non-nil value should be either a buffer or a pipe process created with make-pipe-process, described below.

The original argument list, modified with the actual connection information, is available via the process-contact function.

The current working directory of the subprocess is set to the current buffer's value of default-directory if that is local (as determined by `unhandled-file-name-directory'), or "~" otherwise. If you want to run a process in a remote directory use start-file-process.

— Function: make-pipe-process &rest args

This function creates a bidirectional pipe which can be attached to a child process. This is useful with the :stderr keyword of make-process. The function returns a process object.

The arguments args are a list of keyword/argument pairs. Omitting a keyword is always equivalent to specifying it with value nil.

Here are the meaningful keywords:

:name name

Use the string name as the process name. As with make-process, it is modified if necessary to make it unique.

:buffer buffer

Use buffer as the process buffer.

:coding coding

If coding is a symbol, it specifies the coding system to be used for both reading and writing of data from and to the connection. If coding is a cons cell (decoding . encoding), then decoding will be used for reading and encoding for writing.

If coding is nil, the default rules for finding the coding system will apply. See Default Coding Systems.

:noquery query-flag

Initialize the process query flag to query-flag. See Query Before Exit.

:stop stopped

If stopped is non-nil, start the process in the stopped state. In the stopped state, a pipe process does not accept incoming data, but you can send outgoing data. The stopped state is set by stop-process and cleared by continue-process (see Signals to Processes).

:filter filter

Initialize the process filter to filter. If not specified, a default filter will be provided, which can be changed later. See Filter Functions.

:sentinel sentinel

Initialize the process sentinel to sentinel. If not specified, a default sentinel will be used, which can be changed later. See Sentinels.

The original argument list, modified with the actual connection information, is available via the process-contact function.

— Function: start-process name buffer-or-name program &rest args

This function is a higher-level wrapper around make-process, exposing an interface that is similar to call-process. It creates a new asynchronous subprocess and starts the specified program running in it. It returns a process object that stands for the new subprocess in Lisp. The argument name specifies the name for the process object; as with make-process, it is modified if necessary to make it unique. The buffer buffer-or-name is the buffer to associate with the process.

If program is nil, Emacs opens a new pseudoterminal (pty) and associates its input and output with buffer-or-name, without creating a subprocess. In that case, the remaining arguments args are ignored.

The rest of args are strings that specify command line arguments for the subprocess.

In the example below, the first process is started and runs (rather, sleeps) for 100 seconds (the output buffer ‘foo’ is created immediately). Meanwhile, the second process is started, and given the name ‘my-process<1>’ for the sake of uniqueness. It inserts the directory listing at the end of the buffer ‘foo’, before the first process finishes. Then it finishes, and a message to that effect is inserted in the buffer. Much later, the first process finishes, and another message is inserted in the buffer for it.

          (start-process "my-process" "foo" "sleep" "100")
               ⇒ #<process my-process>
          
          (start-process "my-process" "foo" "ls" "-l" "/bin")
               ⇒ #<process my-process<1>>
          
          ---------- Buffer: foo ----------
          total 8336
          -rwxr-xr-x 1 root root 971384 Mar 30 10:14 bash
          -rwxr-xr-x 1 root root 146920 Jul  5  2011 bsd-csh
          ...
          -rwxr-xr-x 1 root root 696880 Feb 28 15:55 zsh4
          
          Process my-process<1> finished
          
          Process my-process finished
          ---------- Buffer: foo ----------

— Function: start-file-process name buffer-or-name program &rest args

Like start-process, this function starts a new asynchronous subprocess running program in it, and returns its process object.

The difference from start-process is that this function may invoke a file handler based on the value of default-directory. This handler ought to run program, perhaps on the local host, perhaps on a remote host that corresponds to default-directory. In the latter case, the local part of default-directory becomes the working directory of the process.

This function does not try to invoke file name handlers for program or for the rest of args. For that reason, if program or any of args use the remote-file syntax (see Magic File Names), they must be converted either to file names relative to default-directory, or to names that identify the files locally on the remote host, by running them through file-local-name.

Depending on the implementation of the file handler, it might not be possible to apply process-filter or process-sentinel to the resulting process object. See Filter Functions, and Sentinels.

Some file handlers may not support start-file-process (for example the function ange-ftp-hook-function). In such cases, this function does nothing and returns nil.

— Function: start-process-shell-command name buffer-or-name command

This function is like start-process, except that it uses a shell to execute the specified command. The argument command is a shell command string. The variable shell-file-name specifies which shell to use.

The point of running a program through the shell, rather than directly with make-process or start-process, is so that you can employ shell features such as wildcards in the arguments. It follows that if you include any arbitrary user-specified arguments in the command, you should quote them with shell-quote-argument first, so that any special shell characters do not have their special shell meanings. See Shell Arguments. Of course, when executing commands based on user input you should also consider the security implications.

— Function: start-file-process-shell-command name buffer-or-name command

This function is like start-process-shell-command, but uses start-file-process internally. Because of this, command can also be executed on remote hosts, depending on default-directory.

— Variable: process-connection-type

This variable controls the type of device used to communicate with asynchronous subprocesses. If it is non-nil, then ptys are used, when available. Otherwise, pipes are used.

The value of process-connection-type takes effect when make-process or start-process is called. So you can specify how to communicate with one subprocess by binding the variable around the call to these functions.

Note that the value of this variable is ignored when make-process is called with a non-nil value of the :stderr parameter; in that case, Emacs will communicate with the process using pipes. It is also ignored if ptys are unavailable (MS-Windows).

          (let ((process-connection-type nil))  ; use a pipe
            (start-process ...))

To determine whether a given subprocess actually got a pipe or a pty, use the function process-tty-name (see Process Information).