diff options
Diffstat (limited to 'devdocs/elisp/network.html')
| -rw-r--r-- | devdocs/elisp/network.html | 23 |
1 files changed, 23 insertions, 0 deletions
diff --git a/devdocs/elisp/network.html b/devdocs/elisp/network.html new file mode 100644 index 00000000..0a8a8c2c --- /dev/null +++ b/devdocs/elisp/network.html @@ -0,0 +1,23 @@ + <h3 class="section">Network Connections</h3> <p>Emacs Lisp programs can open stream (TCP) and datagram (UDP) network connections (see <a href="datagrams">Datagrams</a>) to other processes on the same machine or other machines. A network connection is handled by Lisp much like a subprocess, and is represented by a process object. However, the process you are communicating with is not a child of the Emacs process, has no process <acronym>ID</acronym>, and you can’t kill it or send it signals. All you can do is send and receive data. <code>delete-process</code> closes the connection, but does not kill the program at the other end; that program must decide what to do about closure of the connection. </p> <p>Lisp programs can listen for connections by creating network servers. A network server is also represented by a kind of process object, but unlike a network connection, the network server never transfers data itself. When it receives a connection request, it creates a new network connection to represent the connection just made. (The network connection inherits certain information, including the process plist, from the server.) The network server then goes back to listening for more connection requests. </p> <p>Network connections and servers are created by calling <code>make-network-process</code> with an argument list consisting of keyword/argument pairs, for example <code>:server t</code> to create a server process, or <code>:type 'datagram</code> to create a datagram connection. See <a href="low_002dlevel-network">Low-Level Network</a>, for details. You can also use the <code>open-network-stream</code> function described below. </p> <p>To distinguish the different types of processes, the <code>process-type</code> 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 real subprocess. </p> <p>The <code>process-status</code> function returns <code>open</code>, <code>closed</code>, <code>connect</code>, <code>stop</code>, or <code>failed</code> for network connections. For a network server, the status is always <code>listen</code>. Except for <code>stop</code>, none of those values is possible for a real subprocess. See <a href="process-information">Process Information</a>. </p> <p>You can stop and resume operation of a network process by calling <code>stop-process</code> and <code>continue-process</code>. For a server process, being stopped means not accepting new connections. (Up to 5 connection requests will be queued for when you resume the server; you can increase this limit, unless it is imposed by the operating system—see the <code>:server</code> keyword of <code>make-network-process</code>, <a href="network-processes">Network Processes</a>.) For a network stream connection, being stopped means not processing input (any arriving input waits until you resume the connection). For a datagram connection, some number of packets may be queued but input may be lost. You can use the function <code>process-command</code> to determine whether a network connection or server is stopped; a non-<code>nil</code> value means yes. </p> <p>Emacs can create encrypted network connections, using the built-in support for the GnuTLS Transport Layer Security Library; see <a href="https://www.gnu.org/software/gnutls/">the GnuTLS project page</a>. If your Emacs was compiled with GnuTLS support, the function <code>gnutls-available-p</code> is defined and returns non-<code>nil</code>. For more details, see <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs-gnutls/index.html#Top">Overview</a> in <cite>The Emacs-GnuTLS manual</cite>. The <code>open-network-stream</code> function can transparently handle the details of creating encrypted connections for you, using whatever support is available. </p> <dl> <dt id="open-network-stream">Function: <strong>open-network-stream</strong> <em>name buffer host service &rest parameters</em> +</dt> <dd> +<p>This function opens a TCP connection, with optional encryption, and returns a process object that represents the connection. </p> <p>The <var>name</var> argument specifies the name for the process object. It is modified as necessary to make it unique. </p> <p>The <var>buffer</var> argument is the buffer to associate with the connection. Output from the connection is inserted in the buffer, unless you specify your own filter function to handle the output. If <var>buffer</var> is <code>nil</code>, it means that the connection is not associated with any buffer. </p> <p>The arguments <var>host</var> and <var>service</var> specify where to connect to; <var>host</var> is the host name (a string), and <var>service</var> is the name of a defined network service (a string) or a port number (an integer like <code>80</code> or an integer string like <code>"80"</code>). </p> <p>The remaining arguments <var>parameters</var> are keyword/argument pairs that are mainly relevant to encrypted connections: </p> <dl compact> <dt><code>:nowait <var>boolean</var></code></dt> <dd> +<p>If non-<code>nil</code>, try to make an asynchronous connection. </p> </dd> <dt><code>:coding <var>coding</var></code></dt> <dd> +<p>Use this to set the coding systems used by the network process, in preference to binding <code>coding-system-for-read</code> or <code>coding-system-for-write</code>. See <a href="network-processes">Network Processes</a>, for details. </p> </dd> <dt><code>:type <var>type</var></code></dt> <dd> +<p>The type of connection. Options are: </p> <dl compact> <dt><code>plain</code></dt> <dd><p>An ordinary, unencrypted connection. </p></dd> <dt><code>tls</code></dt> <dt><code>ssl</code></dt> <dd><p>A <acronym>TLS</acronym> (Transport Layer Security) connection. </p></dd> <dt><code>nil</code></dt> <dt><code>network</code></dt> <dd><p>Start with a plain connection, and if parameters ‘<samp>:success</samp>’ and ‘<samp>:capability-command</samp>’ are supplied, try to upgrade to an encrypted connection via <acronym>STARTTLS</acronym>. If that fails, retain the unencrypted connection. </p></dd> <dt><code>starttls</code></dt> <dd><p>As for <code>nil</code>, but if <acronym>STARTTLS</acronym> fails drop the connection. </p></dd> <dt><code>shell</code></dt> <dd><p>A shell connection. </p></dd> </dl> </dd> <dt><code>:always-query-capabilities <var>boolean</var></code></dt> <dd> +<p>If non-<code>nil</code>, always ask for the server’s capabilities, even when doing a ‘<samp>plain</samp>’ connection. </p> </dd> <dt><code>:capability-command <var>capability-command</var></code></dt> <dd> +<p>Command to query the host capabilities. This can either be a string (which will then be sent verbatim to the server), or a function (called with a single parameter; the "greeting" from the server when connecting), and should return a string. </p> </dd> <dt><code>:end-of-command <var>regexp</var></code></dt> <dt><code>:end-of-capability <var>regexp</var></code></dt> <dd> +<p>Regular expression matching the end of a command, or the end of the command <var>capability-command</var>. The latter defaults to the former. </p> </dd> <dt><code>:starttls-function <var>function</var></code></dt> <dd> +<p>Function of one argument (the response to <var>capability-command</var>), which returns either <code>nil</code>, or the command to activate <acronym>STARTTLS</acronym> if supported. </p> </dd> <dt><code>:success <var>regexp</var></code></dt> <dd> +<p>Regular expression matching a successful <acronym>STARTTLS</acronym> negotiation. </p> </dd> <dt><code>:use-starttls-if-possible <var>boolean</var></code></dt> <dd> +<p>If non-<code>nil</code>, do opportunistic <acronym>STARTTLS</acronym> upgrades even if Emacs doesn’t have built-in <acronym>TLS</acronym> support. </p> </dd> <dt><code>:warn-unless-encrypted <var>boolean</var></code></dt> <dd> +<p>If non-<code>nil</code>, and <code>:return-value</code> is also non-<code>nil</code>, Emacs will warn if the connection isn’t encrypted. This is useful for protocols like <acronym>IMAP</acronym> and the like, where most users would expect the network traffic to be encrypted. </p> </dd> <dt><code>:client-certificate <var>list-or-t</var></code></dt> <dd> +<p>Either a list of the form <code>(<var>key-file</var> <var>cert-file</var>)</code>, naming the certificate key file and certificate file itself, or <code>t</code>, meaning to query <code>auth-source</code> for this information (see <a href="https://www.gnu.org/software/emacs/manual/html_node/auth/Help-for-users.html#Help-for-users">auth-source</a> in <cite>Emacs auth-source Library</cite>). Only used for <acronym>TLS</acronym> or <acronym>STARTTLS</acronym>. To enable automatic queries of <code>auth-source</code> when <code>:client-certificate</code> is not specified customize <code>network-stream-use-client-certificates</code> to t. </p> </dd> <dt><code>:return-list <var>cons-or-nil</var></code></dt> <dd> +<p>The return value of this function. If omitted or <code>nil</code>, return a process object. Otherwise, a cons of the form <code>(<var>process-object</var> +. <var>plist</var>)</code>, where <var>plist</var> has keywords: </p> <dl compact> <dt><code>:greeting <var>string-or-nil</var></code></dt> <dd><p>If non-<code>nil</code>, the greeting string returned by the host. </p></dd> <dt><code>:capabilities <var>string-or-nil</var></code></dt> <dd><p>If non-<code>nil</code>, the host’s capability string. </p></dd> <dt><code>:type <var>symbol</var></code></dt> <dd><p>The connection type: ‘<samp>plain</samp>’ or ‘<samp>tls</samp>’. </p></dd> </dl> </dd> <dt><code>:shell-command <var>string-or-nil</var></code></dt> <dd> +<p>If the connection <code>type</code> is <code>shell</code>, this parameter will be interpreted as a format-spec string that will be executed to make the connection. The specs available are ‘<samp>%s</samp>’ for the host name and ‘<samp>%p</samp>’ for the port number. For instance, if you want to first ssh to ‘<samp>gateway</samp>’ before making a plain connection, then this parameter could be something like ‘<samp>ssh gateway nc %s %p</samp>’. </p> </dd> </dl> </dd> +</dl><div class="_attribution"> + <p class="_attribution-p"> + Copyright © 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/Network.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Network.html</a> + </p> +</div> |