path: root/devdocs/elisp/process-information.html

 <h3 class="section">Process Information</h3>  <p>Several functions return information about processes. </p> <dl> <dt id="list-processes">Command: <strong>list-processes</strong> <em>&amp;optional query-only buffer</em>
</dt> <dd>
<p>This command displays a listing of all living processes. In addition, it finally deletes any process whose status was ‘<samp>Exited</samp>’ or ‘<samp>Signaled</samp>’. It returns <code>nil</code>. </p> <p>The processes are shown in a buffer named <samp>*Process List*</samp> (unless you specify otherwise using the optional argument <var>buffer</var>), whose major mode is Process Menu mode. </p> <p>If <var>query-only</var> is non-<code>nil</code>, it only lists processes whose query flag is non-<code>nil</code>. See <a href="query-before-exit">Query Before Exit</a>. </p>
</dd>
</dl> <dl> <dt id="process-list">Function: <strong>process-list</strong>
</dt> <dd>
<p>This function returns a list of all processes that have not been deleted. </p> <div class="example"> <pre class="example">(process-list)
     ⇒ (#&lt;process display-time&gt; #&lt;process shell&gt;)
</pre>
</div> </dd>
</dl> <dl> <dt id="num-processors">Function: <strong>num-processors</strong> <em>&amp;optional query</em>
</dt> <dd><p>This function returns the number of processors, a positive integer. Each usable thread execution unit counts as a processor. By default, the count includes the number of available processors, which you can override by setting the <a href="https://www.openmp.org/spec-html/5.1/openmpse59.html"><code>OMP_NUM_THREADS</code> environment variable of OpenMP</a>. If the optional argument <var>query</var> is <code>current</code>, this function ignores <code>OMP_NUM_THREADS</code>; if <var>query</var> is <code>all</code>, this function also counts processors that are on the system but are not available to the current process. </p></dd>
</dl> <dl> <dt id="get-process">Function: <strong>get-process</strong> <em>name</em>
</dt> <dd>
<p>This function returns the process named <var>name</var> (a string), or <code>nil</code> if there is none. The argument <var>name</var> can also be a process object, in which case it is returned. </p> <div class="example"> <pre class="example">(get-process "shell")
     ⇒ #&lt;process shell&gt;
</pre>
</div> </dd>
</dl> <dl> <dt id="process-command">Function: <strong>process-command</strong> <em>process</em>
</dt> <dd>
<p>This function returns the command that was executed to start <var>process</var>. This is a list of strings, the first string being the program executed and the rest of the strings being the arguments that were given to the program. For a network, serial, or pipe connection, this is either <code>nil</code>, which means the process is running or <code>t</code> (process is stopped). </p> <div class="example"> <pre class="example">(process-command (get-process "shell"))
     ⇒ ("bash" "-i")
</pre>
</div> </dd>
</dl> <dl> <dt id="process-contact">Function: <strong>process-contact</strong> <em>process &amp;optional key no-block</em>
</dt> <dd>
<p>This function returns information about how a network, a serial, or a pipe connection was set up. When <var>key</var> is <code>nil</code>, it returns <code>(<var>hostname</var> <var>service</var>)</code> for a network connection, <code>(<var>port</var> <var>speed</var>)</code> for a serial connection, and <code>t</code> for a pipe connection. For an ordinary child process, this function always returns <code>t</code> when called with a <code>nil</code> <var>key</var>. </p> <p>If <var>key</var> is <code>t</code>, the value is the complete status information for the connection, server, serial port, or pipe; that is, the list of keywords and values specified in <code>make-network-process</code>, <code>make-serial-process</code>, or <code>make-pipe-process</code>, except that some of the values represent the current status instead of what you specified. </p> <p>For a network process, the values include (see <code>make-network-process</code> for a complete list): </p> <dl compact> <dt><code>:buffer</code></dt> <dd><p>The associated value is the process buffer. </p></dd> <dt><code>:filter</code></dt> <dd><p>The associated value is the process filter function. See <a href="filter-functions">Filter Functions</a>. </p></dd> <dt><code>:sentinel</code></dt> <dd><p>The associated value is the process sentinel function. See <a href="sentinels">Sentinels</a>. </p></dd> <dt><code>:remote</code></dt> <dd><p>In a connection, the address in internal format of the remote peer. </p></dd> <dt><code>:local</code></dt> <dd><p>The local address, in internal format. </p></dd> <dt><code>:service</code></dt> <dd><p>In a server, if you specified <code>t</code> for <var>service</var>, this value is the actual port number. </p></dd> </dl> <p><code>:local</code> and <code>:remote</code> are included even if they were not specified explicitly in <code>make-network-process</code>. </p> <p>For a serial connection, see <code>make-serial-process</code> and <code>serial-process-configure</code> for the list of keys. For a pipe connection, see <code>make-pipe-process</code> for the list of keys. </p> <p>If <var>key</var> is a keyword, the function returns the value corresponding to that keyword. </p> <p>If <var>process</var> is a non-blocking network stream that hasn’t been fully set up yet, then this function will block until that has happened. If given the optional <var>no-block</var> parameter, this function will return <code>nil</code> instead of blocking. </p>
</dd>
</dl> <dl> <dt id="process-id">Function: <strong>process-id</strong> <em>process</em>
</dt> <dd><p>This function returns the <acronym>PID</acronym> of <var>process</var>. This is an integral number that distinguishes the process <var>process</var> from all other processes running on the same computer at the current time. The <acronym>PID</acronym> of a process is chosen by the operating system kernel when the process is started and remains constant as long as the process exists. For network, serial, and pipe connections, this function returns <code>nil</code>. </p></dd>
</dl> <dl> <dt id="process-name">Function: <strong>process-name</strong> <em>process</em>
</dt> <dd><p>This function returns the name of <var>process</var>, as a string. </p></dd>
</dl> <dl> <dt id="process-status">Function: <strong>process-status</strong> <em>process-name</em>
</dt> <dd>
<p>This function returns the status of <var>process-name</var> as a symbol. The argument <var>process-name</var> must be a process, a buffer, or a process name (a string). </p> <p>The possible values for an actual subprocess are: </p> <dl compact> <dt><code>run</code></dt> <dd><p>for a process that is running. </p></dd> <dt><code>stop</code></dt> <dd><p>for a process that is stopped but continuable. </p></dd> <dt><code>exit</code></dt> <dd><p>for a process that has exited. </p></dd> <dt><code>signal</code></dt> <dd><p>for a process that has received a fatal signal. </p></dd> <dt><code>open</code></dt> <dd><p>for a network, serial, or pipe connection that is open. </p></dd> <dt><code>closed</code></dt> <dd><p>for a network, serial, or pipe connection that is closed. Once a connection is closed, you cannot reopen it, though you might be able to open a new connection to the same place. </p></dd> <dt><code>connect</code></dt> <dd><p>for a non-blocking connection that is waiting to complete. </p></dd> <dt><code>failed</code></dt> <dd><p>for a non-blocking connection that has failed to complete. </p></dd> <dt><code>listen</code></dt> <dd><p>for a network server that is listening. </p></dd> <dt><code>nil</code></dt> <dd><p>if <var>process-name</var> is not the name of an existing process. </p></dd> </dl> <div class="example"> <pre class="example">(process-status (get-buffer "*shell*"))
     ⇒ run
</pre>
</div> <p>For a network, serial, or pipe connection, <code>process-status</code> returns one of the symbols <code>open</code>, <code>stop</code>, or <code>closed</code>. The latter means that the other side closed the connection, or Emacs did <code>delete-process</code>. The value <code>stop</code> means that <code>stop-process</code> was called on the connection. </p>
</dd>
</dl> <dl> <dt id="process-live-p">Function: <strong>process-live-p</strong> <em>process</em>
</dt> <dd><p>This function returns non-<code>nil</code> if <var>process</var> is alive. A process is considered alive if its status is <code>run</code>, <code>open</code>, <code>listen</code>, <code>connect</code> or <code>stop</code>. </p></dd>
</dl> <dl> <dt id="process-type">Function: <strong>process-type</strong> <em>process</em>
</dt> <dd><p>This function returns the symbol <code>network</code> for a network connection or server, <code>serial</code> for a serial port connection, <code>pipe</code> for a pipe connection, or <code>real</code> for a subprocess created for running a program. </p></dd>
</dl> <dl> <dt id="process-exit-status">Function: <strong>process-exit-status</strong> <em>process</em>
</dt> <dd><p>This function returns the exit status of <var>process</var> or the signal number that killed it. (Use the result of <code>process-status</code> to determine which of those it is.) If <var>process</var> has not yet terminated, the value is 0. For network, serial, and pipe connections that are already closed, the value is either 0 or 256, depending on whether the connection was closed normally or abnormally. </p></dd>
</dl> <dl> <dt id="process-tty-name">Function: <strong>process-tty-name</strong> <em>process</em>
</dt> <dd><p>This function returns the terminal name that <var>process</var> is using for its communication with Emacs—or <code>nil</code> if it is using pipes instead of a pty (see <code>process-connection-type</code> in <a href="asynchronous-processes">Asynchronous Processes</a>). If <var>process</var> represents a program running on a remote host, the terminal name used by that program on the remote host is provided as process property <code>remote-tty</code>. If <var>process</var> represents a network, serial, or pipe connection, the value is <code>nil</code>. </p></dd>
</dl> <dl> <dt id="process-coding-system">Function: <strong>process-coding-system</strong> <em>process</em>
</dt> <dd>
<p>This function returns a cons cell <code>(<var>decode</var> . <var>encode</var>)</code>, describing the coding systems in use for decoding output from, and encoding input to, <var>process</var> (see <a href="coding-systems">Coding Systems</a>). </p>
</dd>
</dl> <dl> <dt id="set-process-coding-system">Function: <strong>set-process-coding-system</strong> <em>process &amp;optional decoding-system encoding-system</em>
</dt> <dd><p>This function specifies the coding systems to use for subsequent output from and input to <var>process</var>. It will use <var>decoding-system</var> to decode subprocess output, and <var>encoding-system</var> to encode subprocess input. </p></dd>
</dl> <p>Every process also has a property list that you can use to store miscellaneous values associated with the process. </p> <dl> <dt id="process-get">Function: <strong>process-get</strong> <em>process propname</em>
</dt> <dd><p>This function returns the value of the <var>propname</var> property of <var>process</var>. </p></dd>
</dl> <dl> <dt id="process-put">Function: <strong>process-put</strong> <em>process propname value</em>
</dt> <dd><p>This function sets the value of the <var>propname</var> property of <var>process</var> to <var>value</var>. </p></dd>
</dl> <dl> <dt id="process-plist">Function: <strong>process-plist</strong> <em>process</em>
</dt> <dd><p>This function returns the process plist of <var>process</var>. </p></dd>
</dl> <dl> <dt id="set-process-plist">Function: <strong>set-process-plist</strong> <em>process plist</em>
</dt> <dd><p>This function sets the process plist of <var>process</var> to <var>plist</var>. </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/Process-Information.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Process-Information.html</a>
  </p>
</div>