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

 <h3 class="section">Creating a Synchronous Process</h3>  <p>After a <em>synchronous process</em> is created, Emacs waits for the process to terminate before continuing. Starting Dired on GNU or Unix<a id="DOCF24" href="#FOOT24"><sup>24</sup></a> is an example of this: it runs <code>ls</code> in a synchronous process, then modifies the output slightly. Because the process is synchronous, the entire directory listing arrives in the buffer before Emacs tries to do anything with it. </p> <p>While Emacs waits for the synchronous subprocess to terminate, the user can quit by typing <kbd>C-g</kbd>. The first <kbd>C-g</kbd> tries to kill the subprocess with a <code>SIGINT</code> signal; but it waits until the subprocess actually terminates before quitting. If during that time the user types another <kbd>C-g</kbd>, that kills the subprocess instantly with <code>SIGKILL</code> and quits immediately (except on MS-DOS, where killing other processes doesn’t work). See <a href="quitting">Quitting</a>. </p> <p>The synchronous subprocess functions return an indication of how the process terminated. </p> <p>The output from a synchronous subprocess is generally decoded using a coding system, much like text read from a file. The input sent to a subprocess by <code>call-process-region</code> is encoded using a coding system, much like text written into a file. See <a href="coding-systems">Coding Systems</a>. </p> <dl> <dt id="call-process">Function: <strong>call-process</strong> <em>program &amp;optional infile destination display &amp;rest args</em>
</dt> <dd>
<p>This function calls <var>program</var> and waits for it to finish. </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 "~" otherwise. If you want to run a process in a remote directory use <code>process-file</code>. </p> <p>The standard input for the new process comes from file <var>infile</var> if <var>infile</var> is not <code>nil</code>, and from the null device otherwise. The argument <var>destination</var> says where to put the process output. Here are the possibilities: </p> <dl compact> <dt>a buffer</dt> <dd>
<p>Insert the output in that buffer, before point. This includes both the standard output stream and the standard error stream of the process. </p> </dd> <dt>a buffer name (a string)</dt> <dd>
<p>Insert the output in a buffer with that name, before point. </p> </dd> <dt><code>t</code></dt> <dd>
<p>Insert the output in the current buffer, before point. </p> </dd> <dt><code>nil</code></dt> <dd>
<p>Discard the output. </p> </dd> <dt>0</dt> <dd>
<p>Discard the output, and return <code>nil</code> immediately without waiting for the subprocess to finish. </p> <p>In this case, the process is not truly synchronous, since it can run in parallel with Emacs; but you can think of it as synchronous in that Emacs is essentially finished with the subprocess as soon as this function returns. </p> <p>MS-DOS doesn’t support asynchronous subprocesses, so this option doesn’t work there. </p> </dd> <dt><code>(:file <var>file-name</var>)</code></dt> <dd>
<p>Send the output to the file name specified, overwriting it if it already exists. </p> </dd> <dt><code>(<var>real-destination</var> <var>error-destination</var>)</code></dt> <dd>
<p>Keep the standard output stream separate from the standard error stream; deal with the ordinary output as specified by <var>real-destination</var>, and dispose of the error output according to <var>error-destination</var>. If <var>error-destination</var> is <code>nil</code>, that means to discard the error output, <code>t</code> means mix it with the ordinary output, and a string specifies a file name to redirect error output into. </p> <p>You can’t directly specify a buffer to put the error output in; that is too difficult to implement. But you can achieve this result by sending the error output to a temporary file and then inserting the file into a buffer when the subprocess finishes. </p>
</dd> </dl> <p>If <var>display</var> is non-<code>nil</code>, then <code>call-process</code> redisplays the buffer as output is inserted. (However, if the coding system chosen for decoding output is <code>undecided</code>, meaning deduce the encoding from the actual data, then redisplay sometimes cannot continue once non-<acronym>ASCII</acronym> characters are encountered. There are fundamental reasons why it is hard to fix this; see <a href="output-from-processes">Output from Processes</a>.) </p> <p>Otherwise the function <code>call-process</code> does no redisplay, and the results become visible on the screen only when Emacs redisplays that buffer in the normal course of events. </p> <p>The remaining arguments, <var>args</var>, are strings that specify command line arguments for the program. Each string is passed to <var>program</var> as a separate argument. </p> <p>The value returned by <code>call-process</code> (unless you told it not to wait) indicates the reason for process termination. A number gives the exit status of the subprocess; 0 means success, and any other value means failure. If the process terminated with a signal, <code>call-process</code> returns a string describing the signal. If you told <code>call-process</code> not to wait, it returns <code>nil</code>. </p> <p>In the examples below, the buffer ‘<samp>foo</samp>’ is current. </p> <div class="example"> <pre class="example">(call-process "pwd" nil t)
     ⇒ 0

---------- Buffer: foo ----------
/home/lewis/manual
---------- Buffer: foo ----------
</pre>

<pre class="example">(call-process "grep" nil "bar" nil "lewis" "/etc/passwd")
     ⇒ 0

---------- Buffer: bar ----------
lewis:x:1001:1001:Bil Lewis,,,,:/home/lewis:/bin/bash

---------- Buffer: bar ----------
</pre>
</div> <p>Here is an example of the use of <code>call-process</code>, as used to be found in the definition of the <code>insert-directory</code> function: </p> <div class="example"> <pre class="example">(call-process insert-directory-program nil t nil switches
              (if full-directory-p
                  (concat (file-name-as-directory file) ".")
                file))
</pre>
</div> </dd>
</dl> <dl> <dt id="process-file">Function: <strong>process-file</strong> <em>program &amp;optional infile buffer display &amp;rest args</em>
</dt> <dd>
<p>This function processes files synchronously in a separate process. It is similar to <code>call-process</code>, but may invoke a file name handler based on the value of the variable <code>default-directory</code>, which specifies the current working directory of the subprocess. </p> <p>The arguments are handled in almost the same way as for <code>call-process</code>, with the following differences: </p> <p>Some file name handlers may not support all combinations and forms of the arguments <var>infile</var>, <var>buffer</var>, and <var>display</var>. For example, some file name handlers might behave as if <var>display</var> were <code>nil</code>, regardless of the value actually passed. As another example, some file name handlers might not support separating standard output and error output by way of the <var>buffer</var> argument. </p> <p>If a file name handler is invoked, it determines the program to run based on the first argument <var>program</var>. For instance, suppose that a handler for remote files is invoked. Then the path that is used for searching for the program might be different from <code>exec-path</code>. </p> <p>The second argument <var>infile</var> may invoke a file name handler. The file name handler could be different from the handler chosen for the <code>process-file</code> function itself. (For example, <code>default-directory</code> could be on one remote host, and <var>infile</var> on a different remote host. Or <code>default-directory</code> could be non-special, whereas <var>infile</var> is on a remote host.) </p> <p>If <var>buffer</var> is a list of the form <code>(<var>real-destination</var>
<var>error-destination</var>)</code>, and <var>error-destination</var> names a file, then the same remarks as for <var>infile</var> apply. </p> <p>The remaining arguments (<var>args</var>) will be passed to the process verbatim. Emacs is not involved in processing file names that are present in <var>args</var>. To avoid confusion, it may be best to avoid absolute file names in <var>args</var>, but rather to specify all file names as relative to <code>default-directory</code>. The function <code>file-relative-name</code> is useful for constructing such relative file names. Alternatively, you can use <code>file-local-name</code> (see <a href="magic-file-names">Magic File Names</a>) to obtain an absolute file name as seen from the remote host’s perspective. </p>
</dd>
</dl> <dl> <dt id="process-file-side-effects">Variable: <strong>process-file-side-effects</strong>
</dt> <dd>
<p>This variable indicates whether a call of <code>process-file</code> changes remote files. </p> <p>By default, this variable is always set to <code>t</code>, meaning that a call of <code>process-file</code> could potentially change any file on a remote host. When set to <code>nil</code>, a file name handler could optimize its behavior with respect to remote file attribute caching. </p> <p>You should only ever change this variable with a let-binding; never with <code>setq</code>. </p>
</dd>
</dl> <dl> <dt id="process-file-return-signal-string">User Option: <strong>process-file-return-signal-string</strong>
</dt> <dd>
<p>This user option indicates whether a call of <code>process-file</code> returns a string describing the signal interrupting a remote process. </p> <p>When a process returns an exit code greater than 128, it is interpreted as a signal. <code>process-file</code> requires to return a string describing this signal. </p> <p>Since there are processes violating this rule, returning exit codes greater than 128 which are not bound to a signal, <code>process-file</code> returns always the exit code as natural number for remote processes. Setting this user option to non-nil forces <code>process-file</code> to interpret such exit codes as signals, and to return a corresponding string. </p>
</dd>
</dl> <dl> <dt id="call-process-region">Function: <strong>call-process-region</strong> <em>start end program &amp;optional delete destination display &amp;rest args</em>
</dt> <dd>
<p>This function sends the text from <var>start</var> to <var>end</var> as standard input to a process running <var>program</var>. It deletes the text sent if <var>delete</var> is non-<code>nil</code>; this is useful when <var>destination</var> is <code>t</code>, to insert the output in the current buffer in place of the input. </p> <p>The arguments <var>destination</var> and <var>display</var> control what to do with the output from the subprocess, and whether to update the display as it comes in. For details, see the description of <code>call-process</code>, above. If <var>destination</var> is the integer 0, <code>call-process-region</code> discards the output and returns <code>nil</code> immediately, without waiting for the subprocess to finish (this only works if asynchronous subprocesses are supported; i.e., not on MS-DOS). </p> <p>The remaining arguments, <var>args</var>, are strings that specify command line arguments for the program. </p> <p>The return value of <code>call-process-region</code> is just like that of <code>call-process</code>: <code>nil</code> if you told it to return without waiting; otherwise, a number or string which indicates how the subprocess terminated. </p> <p>In the following example, we use <code>call-process-region</code> to run the <code>cat</code> utility, with standard input being the first five characters in buffer ‘<samp>foo</samp>’ (the word ‘<samp>input</samp>’). <code>cat</code> copies its standard input into its standard output. Since the argument <var>destination</var> is <code>t</code>, this output is inserted in the current buffer. </p> <div class="example"> <pre class="example">---------- Buffer: foo ----------
input∗
---------- Buffer: foo ----------
</pre>

<pre class="example">(call-process-region 1 6 "cat" nil t)
     ⇒ 0

---------- Buffer: foo ----------
inputinput∗
---------- Buffer: foo ----------
</pre>
</div> <p>For example, the <code>shell-command-on-region</code> command uses <code>call-shell-region</code> in a manner similar to this: </p> <div class="example"> <pre class="example">(call-shell-region
 start end
 command              ; <span class="roman">shell command</span>
 nil                  ; <span class="roman">do not delete region</span>
 buffer)              ; <span class="roman">send output to <code>buffer</code></span>
</pre>
</div> </dd>
</dl> <dl> <dt id="call-process-shell-command">Function: <strong>call-process-shell-command</strong> <em>command &amp;optional infile destination display</em>
</dt> <dd><p>This function executes the shell command <var>command</var> synchronously. The other arguments are handled as in <code>call-process</code>. An old calling convention allowed passing any number of additional arguments after <var>display</var>, which were concatenated to <var>command</var>; this is still supported, but strongly discouraged. </p></dd>
</dl> <dl> <dt id="process-file-shell-command">Function: <strong>process-file-shell-command</strong> <em>command &amp;optional infile destination display</em>
</dt> <dd><p>This function is like <code>call-process-shell-command</code>, but uses <code>process-file</code> internally. Depending on <code>default-directory</code>, <var>command</var> can be executed also on remote hosts. An old calling convention allowed passing any number of additional arguments after <var>display</var>, which were concatenated to <var>command</var>; this is still supported, but strongly discouraged. </p></dd>
</dl> <dl> <dt id="call-shell-region">Function: <strong>call-shell-region</strong> <em>start end command &amp;optional delete destination</em>
</dt> <dd><p>This function sends the text from <var>start</var> to <var>end</var> as standard input to an inferior shell running <var>command</var>. This function is similar than <code>call-process-region</code>, with process being a shell. The arguments <code>delete</code>, <code>destination</code> and the return value are like in <code>call-process-region</code>. Note that this function doesn’t accept additional arguments. </p></dd>
</dl> <dl> <dt id="shell-command-to-string">Function: <strong>shell-command-to-string</strong> <em>command</em>
</dt> <dd><p>This function executes <var>command</var> (a string) as a shell command, then returns the command’s output as a string. </p></dd>
</dl> <dl> <dt id="process-lines">Function: <strong>process-lines</strong> <em>program &amp;rest args</em>
</dt> <dd>
<p>This function runs <var>program</var>, waits for it to finish, and returns its output as a list of strings. Each string in the list holds a single line of text output by the program; the end-of-line characters are stripped from each line. The arguments beyond <var>program</var>, <var>args</var>, are strings that specify command-line arguments with which to run the program. </p> <p>If <var>program</var> exits with a non-zero exit status, this function signals an error. </p> <p>This function works by calling <code>call-process</code>, so program output is decoded in the same way as for <code>call-process</code>. </p>
</dd>
</dl> <dl> <dt id="process-lines-ignore-status">Function: <strong>process-lines-ignore-status</strong> <em>program &amp;rest args</em>
</dt> <dd><p>This function is just like <code>process-lines</code>, but does not signal an error if <var>program</var> exits with a non-zero exit status. </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/Synchronous-Processes.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Synchronous-Processes.html</a>
  </p>
</div>