Next: , Previous: Synchronous Processes, Up: Processes

37.4 Creating an Asynchronous Process

In this section, we describe how to create an asynchronous process. After an asynchronous process is created, it runs in parallel with Emacs, and Emacs can communicate with it using the functions described in the following sections (see Input to Processes, and see Output from Processes). Note that process communication is only partially asynchronous: Emacs sends data to the process only when certain functions are called, and Emacs accepts data from the process only while waiting for input or for a time delay.

An asynchronous process is controlled either via a pty (pseudo-terminal) or a pipe. The choice of pty or pipe is made when creating the process, based on the value of the variable process-connection-type (see below). Ptys are usually preferable for processes visible to the user, as in Shell mode, because they allow for job control (C-c, C-z, etc.) between the process and its children, whereas pipes do not. For subprocesses used for internal purposes by programs, it is often better to use a pipe, because they are more efficient, and because they are immune to stray character injections that ptys introduce for large (around 500 byte) messages. Also, the total number of ptys is limited on many systems and it is good not to waste them.

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

This function creates a new asynchronous subprocess and starts the program 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; if a process with this name already exists, then name is modified (by appending ‘<1>’, etc.) to be 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 remaining arguments, 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 invoked 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 program-args.

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 name. The variable shell-file-name specifies which shell to use.

The point of running a program through the shell, rather than directly with 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 start-process is called. So you can specify how to communicate with one subprocess by binding the variable around the call to start-process.

          (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).