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

 <h4 class="subsection">make-network-process</h4> <p>The basic function for creating network connections and network servers is <code>make-network-process</code>. It can do either of those jobs, depending on the arguments you give it. </p> <dl> <dt id="make-network-process">Function: <strong>make-network-process</strong> <em>&amp;rest args</em>
</dt> <dd>
<p>This function creates a network connection or server and returns the process object that represents it. 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>, except for <code>:coding</code>, <code>:filter-multibyte</code>, and <code>:reuseaddr</code>. Here are the meaningful keywords (those corresponding to network options are listed in the following section): </p> <dl compact> <dt>:name <var>name</var>
</dt> <dd>
<p>Use the string <var>name</var> as the process name. It is modified if necessary to make it unique. </p> </dd> <dt>:type <var>type</var>
</dt> <dd>
<p>Specify the communication type. A value of <code>nil</code> specifies a stream connection (the default); <code>datagram</code> specifies a datagram connection; <code>seqpacket</code> specifies a sequenced packet stream connection. Both connections and servers can be of these types. </p> </dd> <dt>:server <var>server-flag</var>
</dt> <dd>
<p>If <var>server-flag</var> is non-<code>nil</code>, create a server. Otherwise, create a connection. For a stream type server, <var>server-flag</var> may be an integer, which then specifies the length of the queue of pending connections to the server. The default queue length is 5. </p> </dd> <dt>:host <var>host</var>
</dt> <dd>
<p>Specify the host to connect to. <var>host</var> should be a host name or Internet address, as a string, or the symbol <code>local</code> to specify the local host. If you specify <var>host</var> for a server, it must specify a valid address for the local host, and only clients connecting to that address will be accepted. When using <code>local</code>, by default IPv4 will be used, specify a <var>family</var> of <code>ipv6</code> to override this. To listen on all interfaces, specify an address of ‘<samp>"0.0.0.0"</samp>’ for IPv4 or ‘<samp>"::"</samp>’ for IPv6. Note that on some operating systems, listening on ‘<samp>"::"</samp>’ will also listen on IPv4, so attempting to then listen separately on IPv4 will result in <code>EADDRINUSE</code> errors (‘<samp>"Address already in use"</samp>’). </p> </dd> <dt>:service <var>service</var>
</dt> <dd>
<p><var>service</var> specifies a port number to connect to; or, for a server, the port number to listen on. It should be a service name like ‘<samp>"https"</samp>’ that translates to a port number, or an integer like ‘<samp>443</samp>’ or an integer string like ‘<samp>"443"</samp>’ that specifies the port number directly. For a server, it can also be <code>t</code>, which means to let the system select an unused port number. </p> </dd> <dt>:family <var>family</var>
</dt> <dd>
<p><var>family</var> specifies the address (and protocol) family for communication. <code>nil</code> means determine the proper address family automatically for the given <var>host</var> and <var>service</var>. <code>local</code> specifies a Unix socket, in which case <var>host</var> is ignored. <code>ipv4</code> and <code>ipv6</code> specify to use IPv4 and IPv6, respectively. </p> </dd> <dt>:use-external-socket <var>use-external-socket</var>
</dt> <dd>
<p>If <var>use-external-socket</var> is non-<code>nil</code> use any sockets passed to Emacs on invocation instead of allocating one. This is used by the Emacs server code to allow on-demand socket activation. If Emacs wasn’t passed a socket, this option is silently ignored. </p> </dd> <dt>:local <var>local-address</var>
</dt> <dd>
<p>For a server process, <var>local-address</var> is the address to listen on. It overrides <var>family</var>, <var>host</var> and <var>service</var>, so you might as well not specify them. </p> </dd> <dt>:remote <var>remote-address</var>
</dt> <dd>
<p>For a connection, <var>remote-address</var> is the address to connect to. It overrides <var>family</var>, <var>host</var> and <var>service</var>, so you might as well not specify them. </p> <p>For a datagram server, <var>remote-address</var> specifies the initial setting of the remote datagram address. </p> <p>The format of <var>local-address</var> or <var>remote-address</var> depends on the address family: </p> <ul class="no-bullet"> <li>- An IPv4 address is represented as a five-element vector of four 8-bit integers and one 16-bit integer <code>[<var>a</var> <var>b</var> <var>c</var> <var>d</var> <var>p</var>]</code> corresponding to numeric IPv4 address <var>a</var>.<var>b</var>.<var>c</var>.<var>d</var> and port number <var>p</var>. </li>
<li>- An IPv6 address is represented as a nine-element vector of 16-bit integers <code>[<var>a</var> <var>b</var> <var>c</var> <var>d</var> <var>e</var> <var>f</var>
<var>g</var> <var>h</var> <var>p</var>]</code> corresponding to numeric IPv6 address <var>a</var>:<var>b</var>:<var>c</var>:<var>d</var>:<var>e</var>:<var>f</var>:<var>g</var>:<var>h</var> and port number <var>p</var>. </li>
<li>- A local address is represented as a string, which specifies the address in the local address space. </li>
<li>- An unsupported-family address is represented by a cons <code>(<var>f</var> . <var>av</var>)</code>, where <var>f</var> is the family number and <var>av</var> is a vector specifying the socket address using one element per address data byte. Do not rely on this format in portable code, as it may depend on implementation defined constants, data sizes, and data structure alignment. </li>
</ul> </dd> <dt>:nowait <var>bool</var>
</dt> <dd>
<p>If <var>bool</var> is non-<code>nil</code> for a stream connection, return without waiting for the connection to complete. When the connection succeeds or fails, Emacs will call the sentinel function, with a second argument matching <code>"open"</code> (if successful) or <code>"failed"</code>. The default is to block, so that <code>make-network-process</code> does not return until the connection has succeeded or failed. </p> <p>If you’re setting up an asynchronous TLS connection, you have to also provide the <code>:tls-parameters</code> parameter (see below). </p> <p>Depending on the capabilities of Emacs, how asynchronous <code>:nowait</code> is may vary. The three elements that may (or may not) be done asynchronously are domain name resolution, socket setup, and (for TLS connections) TLS negotiation. </p> <p>Many functions that interact with process objects, (for instance, <code>process-datagram-address</code>) rely on them at least having a socket before they can return a useful value. These functions will block until the socket has achieved the desired status. The recommended way of interacting with asynchronous sockets is to place a sentinel on the process, and not try to interact with it before it has changed status to ‘<samp>"run"</samp>’. That way, none of these functions will block. </p> </dd> <dt>:tls-parameters</dt> <dd>
<p>When opening a TLS connection, this should be where the first element is the TLS type (which should either be <code>gnutls-x509pki</code> or <code>gnutls-anon</code>, and the remaining elements should form a keyword list acceptable for <code>gnutls-boot</code>. (This keyword list can be obtained from the <code>gnutls-boot-parameters</code> function.) The TLS connection will then be negotiated after completing the connection to the host. </p> </dd> <dt>:stop <var>stopped</var>
</dt> <dd>
<p>If <var>stopped</var> is non-<code>nil</code>, start the network connection or server in the stopped state. </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>Use <var>coding</var> as the coding system for this process. To specify different coding systems for decoding data from the connection and for encoding data sent to it, specify <code>(<var>decoding</var> .
<var>encoding</var>)</code> for <var>coding</var>. </p> <p>If you don’t specify this keyword at all, the default is to determine the coding systems from the data. </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>:filter <var>filter</var>
</dt> <dd>
<p>Initialize the process filter to <var>filter</var>. </p> </dd> <dt>:filter-multibyte <var>multibyte</var>
</dt> <dd>
<p>If <var>multibyte</var> is non-<code>nil</code>, strings given to the process filter are multibyte, otherwise they are unibyte. The default is <code>t</code>. </p> </dd> <dt>:sentinel <var>sentinel</var>
</dt> <dd>
<p>Initialize the process sentinel to <var>sentinel</var>. </p> </dd> <dt>:log <var>log</var>
</dt> <dd>
<p>Initialize the log function of a server process to <var>log</var>. The log function is called each time the server accepts a network connection from a client. The arguments passed to the log function are <var>server</var>, <var>connection</var>, and <var>message</var>; where <var>server</var> is the server process, <var>connection</var> is the new process for the connection, and <var>message</var> is a string describing what has happened. </p> </dd> <dt>:plist <var>plist</var>
</dt> <dd><p>Initialize the process plist to <var>plist</var>. </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><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/Network-Processes.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Network-Processes.html</a>
  </p>
</div>