path: root/devdocs/elisp/asynchronous-processes.html

 <h3 class="section">Creating an Asynchronous Process</h3>  <p>In this section, we describe how to create an <em>asynchronous process</em>. 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 <a href="input-to-processes">Input to Processes</a>, and see <a href="output-from-processes">Output from Processes</a>). Note that process communication is only partially asynchronous: Emacs sends and receives data to and from a process only when those functions are called. </p>   <p>An asynchronous process is controlled either via a <em>pty</em> (pseudo-terminal) or a <em>pipe</em>. The choice of pty or pipe is made when creating the process, by default based on the value of the variable <code>process-connection-type</code> (see below). If available, ptys are usually preferable for processes visible to the user, as in Shell mode, because they allow for job control (<kbd>C-c</kbd>, <kbd>C-z</kbd>, etc.) between the process and its children, and because interactive programs treat ptys as terminal devices, whereas pipes don’t support these features. However, for subprocesses used by Lisp programs for internal purposes (i.e., no user interaction with the subprocess is required), where significant amounts of data need to be exchanged between the subprocess and the Lisp program, it is often better to use a pipe, because pipes are more efficient. Also, the total number of ptys is limited on many systems, and it is good not to waste them unnecessarily. </p> <dl> <dt id="make-process">Function: <strong>make-process</strong> <em>&amp;rest args</em>
</dt> <dd>
<p>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 <code>start-process</code>, described below, it takes keyword arguments, is more flexible, and allows to specify process filters and sentinels in a single call. </p> <p>The arguments <var>args</var> are a list of keyword/argument pairs. Omitting a keyword is always equivalent to specifying it with value <code>nil</code>. Here are the meaningful keywords: </p> <dl compact> <dt>:name <var>name</var>
</dt> <dd>
<p>Use the string <var>name</var> as the process name; if a process with this name already exists, then <var>name</var> is modified (by appending ‘<samp>&lt;1&gt;</samp>’, etc.) to be unique. </p> </dd> <dt>:buffer <var>buffer</var>
</dt> <dd>
<p>Use <var>buffer</var> as the process buffer. If the value is <code>nil</code>, the subprocess is not associated with any buffer. </p> </dd> <dt>:command <var>command</var>
</dt> <dd>
<p>Use <var>command</var> 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 <code>nil</code>, Emacs opens a new pseudoterminal (pty) and associates its input and output with <var>buffer</var>, without actually running any program; the rest of the list elements are ignored in that case. </p> </dd> <dt>:coding <var>coding</var>
</dt> <dd>
<p>If <var>coding</var> is a symbol, it specifies the coding system to be used for both reading and writing of data from and to the connection. If <var>coding</var> is a cons cell <code>(<var>decoding</var> . <var>encoding</var>)</code>, then <var>decoding</var> will be used for reading and <var>encoding</var> 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 <a href="encoding-and-i_002fo">file-name-coding-system</a>). </p> <p>If <var>coding</var> is <code>nil</code>, the default rules for finding the coding system will apply. See <a href="default-coding-systems">Default Coding Systems</a>. </p> </dd> <dt>:connection-type <var>type</var>
</dt> <dd>
<p>Initialize the type of device used to communicate with the subprocess. Possible values are <code>pty</code> to use a pty, <code>pipe</code> to use a pipe, or <code>nil</code> to use the default derived from the value of the <code>process-connection-type</code> variable. This parameter and the value of <code>process-connection-type</code> are ignored if a non-<code>nil</code> value is specified for the <code>:stderr</code> parameter; in that case, the type will always be <code>pipe</code>. On systems where ptys are not available (MS-Windows), this parameter is likewise ignored, and pipes are used unconditionally. </p> </dd> <dt>:noquery <var>query-flag</var>
</dt> <dd>
<p>Initialize the process query flag to <var>query-flag</var>. See <a href="query-before-exit">Query Before Exit</a>. </p> </dd> <dt>:stop <var>stopped</var>
</dt> <dd>
<p>If provided, <var>stopped</var> must be <code>nil</code>; it is an error to use any non-<code>nil</code> value. The <code>:stop</code> key is ignored otherwise and is retained for compatibility with other process types such as pipe processes. Asynchronous subprocesses never start in the stopped state. </p> </dd> <dt>:filter <var>filter</var>
</dt> <dd>
<p>Initialize the process filter to <var>filter</var>. If not specified, a default filter will be provided, which can be overridden later. See <a href="filter-functions">Filter Functions</a>. </p> </dd> <dt>:sentinel <var>sentinel</var>
</dt> <dd>
<p>Initialize the process sentinel to <var>sentinel</var>. If not specified, a default sentinel will be used, which can be overridden later. See <a href="sentinels">Sentinels</a>. </p> </dd> <dt>:stderr <var>stderr</var>
</dt> <dd>
<p>Associate <var>stderr</var> with the standard error of the process. A non-<code>nil</code> value should be either a buffer or a pipe process created with <code>make-pipe-process</code>, described below. If <var>stderr</var> is <code>nil</code>, standard error is mixed with standard output, and both are sent to <var>buffer</var> or <var>filter</var>. </p>  <p>If <var>stderr</var> is a buffer, Emacs will create a pipe process, the <em>standard error process</em>. This process will have the default filter (see <a href="filter-functions">Filter Functions</a>), sentinel (see <a href="sentinels">Sentinels</a>), and coding systems (see <a href="default-coding-systems">Default Coding Systems</a>). On the other hand, it will use <var>query-flag</var> as its query-on-exit flag (see <a href="query-before-exit">Query Before Exit</a>). It will be associated with the <var>stderr</var> buffer (see <a href="process-buffers">Process Buffers</a>) and send its output (which is the standard error of the main process) there. To get the process object for the standard error process, pass the <var>stderr</var> buffer to <code>get-buffer-process</code>. </p> <p>If <var>stderr</var> is a pipe process, Emacs will use it as standard error process for the new process. </p> </dd> <dt>:file-handler <var>file-handler</var>
</dt> <dd><p>If <var>file-handler</var> is non-<code>nil</code>, then look for a file name handler for the current buffer’s <code>default-directory</code>, and invoke that file name handler to make the process. If there is no such handler, proceed as if <var>file-handler</var> were <code>nil</code>. </p></dd> </dl> <p>The original argument list, modified with the actual connection information, is available via the <code>process-contact</code> function. </p> <p>The current working directory of the subprocess is set to the current buffer’s value of <code>default-directory</code> if that is local (as determined by <code>unhandled-file-name-directory</code>), or <samp>~</samp> otherwise. If you want to run a process in a remote directory, pass <code>:file-handler t</code> to <code>make-process</code>. In that case, the current working directory is the local name component of <code>default-directory</code> (as determined by <code>file-local-name</code>). </p> <p>Depending on the implementation of the file name handler, it might not be possible to apply <var>filter</var> or <var>sentinel</var> to the resulting process object. The <code>:stderr</code> argument cannot be a pipe process, file name handlers do not support pipe processes for this. A buffer as <code>:stderr</code> argument is accepted, its contents is shown without the use of pipe processes. See <a href="filter-functions">Filter Functions</a>, <a href="sentinels">Sentinels</a>, and <a href="accepting-output">Accepting Output</a>. </p> <p>Some file name handlers may not support <code>make-process</code>. In such cases, this function does nothing and returns <code>nil</code>. </p>
</dd>
</dl> <dl> <dt id="make-pipe-process">Function: <strong>make-pipe-process</strong> <em>&amp;rest args</em>
</dt> <dd>
<p>This function creates a bidirectional pipe which can be attached to a child process. This is useful with the <code>:stderr</code> keyword of <code>make-process</code>. The function returns a process object. </p> <p>The arguments <var>args</var> are a list of keyword/argument pairs. Omitting a keyword is always equivalent to specifying it with value <code>nil</code>. </p> <p>Here are the meaningful keywords: </p> <dl compact> <dt>:name <var>name</var>
</dt> <dd>
<p>Use the string <var>name</var> as the process name. As with <code>make-process</code>, it is modified if necessary to make it unique. </p> </dd> <dt>:buffer <var>buffer</var>
</dt> <dd>
<p>Use <var>buffer</var> as the process buffer. </p> </dd> <dt>:coding <var>coding</var>
</dt> <dd>
<p>If <var>coding</var> is a symbol, it specifies the coding system to be used for both reading and writing of data from and to the connection. If <var>coding</var> is a cons cell <code>(<var>decoding</var> . <var>encoding</var>)</code>, then <var>decoding</var> will be used for reading and <var>encoding</var> for writing. </p> <p>If <var>coding</var> is <code>nil</code>, the default rules for finding the coding system will apply. See <a href="default-coding-systems">Default Coding Systems</a>. </p> </dd> <dt>:noquery <var>query-flag</var>
</dt> <dd>
<p>Initialize the process query flag to <var>query-flag</var>. See <a href="query-before-exit">Query Before Exit</a>. </p> </dd> <dt>:stop <var>stopped</var>
</dt> <dd>
<p>If <var>stopped</var> is non-<code>nil</code>, 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 <code>stop-process</code> and cleared by <code>continue-process</code> (see <a href="signals-to-processes">Signals to Processes</a>). </p> </dd> <dt>:filter <var>filter</var>
</dt> <dd>
<p>Initialize the process filter to <var>filter</var>. If not specified, a default filter will be provided, which can be changed later. See <a href="filter-functions">Filter Functions</a>. </p> </dd> <dt>:sentinel <var>sentinel</var>
</dt> <dd><p>Initialize the process sentinel to <var>sentinel</var>. If not specified, a default sentinel will be used, which can be changed later. See <a href="sentinels">Sentinels</a>. </p></dd> </dl> <p>The original argument list, modified with the actual connection information, is available via the <code>process-contact</code> function. </p>
</dd>
</dl> <dl> <dt id="start-process">Function: <strong>start-process</strong> <em>name buffer-or-name program &amp;rest args</em>
</dt> <dd>
<p>This function is a higher-level wrapper around <code>make-process</code>, exposing an interface that is similar to <code>call-process</code>. It creates a new asynchronous subprocess and starts the specified <var>program</var> running in it. It returns a process object that stands for the new subprocess in Lisp. The argument <var>name</var> specifies the name for the process object; as with <code>make-process</code>, it is modified if necessary to make it unique. The buffer <var>buffer-or-name</var> is the buffer to associate with the process. </p> <p>If <var>program</var> is <code>nil</code>, Emacs opens a new pseudoterminal (pty) and associates its input and output with <var>buffer-or-name</var>, without creating a subprocess. In that case, the remaining arguments <var>args</var> are ignored. </p> <p>The rest of <var>args</var> are strings that specify command line arguments for the subprocess. </p> <p>In the example below, the first process is started and runs (rather, sleeps) for 100 seconds (the output buffer ‘<samp>foo</samp>’ is created immediately). Meanwhile, the second process is started, and given the name ‘<samp>my-process&lt;1&gt;</samp>’ for the sake of uniqueness. It inserts the directory listing at the end of the buffer ‘<samp>foo</samp>’, 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. </p> <div class="example"> <pre class="example">(start-process "my-process" "foo" "sleep" "100")
     ⇒ #&lt;process my-process&gt;
</pre>

<pre class="example">(start-process "my-process" "foo" "ls" "-l" "/bin")
     ⇒ #&lt;process my-process&lt;1&gt;&gt;

---------- 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&lt;1&gt; finished

Process my-process finished
---------- Buffer: foo ----------
</pre>
</div> </dd>
</dl> <dl> <dt id="start-file-process">Function: <strong>start-file-process</strong> <em>name buffer-or-name program &amp;rest args</em>
</dt> <dd>
<p>Like <code>start-process</code>, this function starts a new asynchronous subprocess running <var>program</var> in it, and returns its process object. </p> <p>The difference from <code>start-process</code> is that this function may invoke a file name handler based on the value of <code>default-directory</code>. This handler ought to run <var>program</var>, perhaps on the local host, perhaps on a remote host that corresponds to <code>default-directory</code>. In the latter case, the local part of <code>default-directory</code> becomes the working directory of the process. </p> <p>This function does not try to invoke file name handlers for <var>program</var> or for the rest of <var>args</var>. For that reason, if <var>program</var> or any of <var>args</var> use the remote-file syntax (see <a href="magic-file-names">Magic File Names</a>), they must be converted either to file names relative to <code>default-directory</code>, or to names that identify the files locally on the remote host, by running them through <code>file-local-name</code>. </p> <p>Depending on the implementation of the file name handler, it might not be possible to apply <code>process-filter</code> or <code>process-sentinel</code> to the resulting process object. See <a href="filter-functions">Filter Functions</a>, and <a href="sentinels">Sentinels</a>. </p> <p>Some file name handlers may not support <code>start-file-process</code> (for example the function <code>ange-ftp-hook-function</code>). In such cases, this function does nothing and returns <code>nil</code>. </p>
</dd>
</dl> <dl> <dt id="start-process-shell-command">Function: <strong>start-process-shell-command</strong> <em>name buffer-or-name command</em>
</dt> <dd>
<p>This function is like <code>start-process</code>, except that it uses a shell to execute the specified <var>command</var>. The argument <var>command</var> is a shell command string. The variable <code>shell-file-name</code> specifies which shell to use. </p> <p>The point of running a program through the shell, rather than directly with <code>make-process</code> or <code>start-process</code>, 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 <code>shell-quote-argument</code> first, so that any special shell characters do <em>not</em> have their special shell meanings. See <a href="shell-arguments">Shell Arguments</a>. Of course, when executing commands based on user input you should also consider the security implications. </p>
</dd>
</dl> <dl> <dt id="start-file-process-shell-command">Function: <strong>start-file-process-shell-command</strong> <em>name buffer-or-name command</em>
</dt> <dd><p>This function is like <code>start-process-shell-command</code>, but uses <code>start-file-process</code> internally. Because of this, <var>command</var> can also be executed on remote hosts, depending on <code>default-directory</code>. </p></dd>
</dl> <dl> <dt id="process-connection-type">Variable: <strong>process-connection-type</strong>
</dt> <dd>
<p>This variable controls the type of device used to communicate with asynchronous subprocesses. If it is non-<code>nil</code>, then ptys are used, when available. Otherwise, pipes are used. </p> <p>The value of <code>process-connection-type</code> takes effect when <code>make-process</code> or <code>start-process</code> is called. So you can specify how to communicate with one subprocess by binding the variable around the call to these functions. </p> <p>Note that the value of this variable is ignored when <code>make-process</code> is called with a non-<code>nil</code> value of the <code>:stderr</code> parameter; in that case, Emacs will communicate with the process using pipes. It is also ignored if ptys are unavailable (MS-Windows). </p> <div class="example"> <pre class="example">(let ((process-connection-type nil))  ; <span class="roman">use a pipe</span>
  (start-process …))
</pre>
</div> <p>To determine whether a given subprocess actually got a pipe or a pty, use the function <code>process-tty-name</code> (see <a href="process-information">Process Information</a>). </p>
</dd>
</dl><div class="_attribution">
  <p class="_attribution-p">
    Copyright &copy; 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br>
    <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Asynchronous-Processes.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Asynchronous-Processes.html</a>
  </p>
</div>