output, Emacs won't receive that output.
Output from a subprocess can arrive only while Emacs is waiting: when
-reading terminal input, in @code{sit-for} and @code{sleep-for}
-(@pxref{Waiting}), and in @code{accept-process-output} (@pxref{Accepting
-Output}). This minimizes the problem of timing errors that usually
-plague parallel programming. For example, you can safely create a
-process and only then specify its buffer or filter function; no output
-can arrive before you finish, if the code in between does not call any
-primitive that waits.
+reading terminal input (see the function @code{waiting-for-user-input-p}),
+in @code{sit-for} and @code{sleep-for} (@pxref{Waiting}), and in
+@code{accept-process-output} (@pxref{Accepting Output}). This
+minimizes the problem of timing errors that usually plague parallel
+programming. For example, you can safely create a process and only
+then specify its buffer or filter function; no output can arrive
+before you finish, if the code in between does not call any primitive
+that waits.
@defvar process-adaptive-read-buffering
On some systems, when Emacs reads the output from a subprocess, the
The filter function can only be called when Emacs is waiting for
something, because process output arrives only at such times. Emacs
-waits when reading terminal input, in @code{sit-for} and
-@code{sleep-for} (@pxref{Waiting}), and in @code{accept-process-output}
-(@pxref{Accepting Output}).
+waits when reading terminal input (see the function
+@code{waiting-for-user-input-p}), in @code{sit-for} and
+@code{sleep-for} (@pxref{Waiting}), and in
+@code{accept-process-output} (@pxref{Accepting Output}).
A filter function must accept two arguments: the associated process
and a string, which is output just received from it. The function is
then free to do whatever it chooses with the output.
+@c Note this text is duplicated in the sentinels section.
Quitting is normally inhibited within a filter function---otherwise,
the effect of typing @kbd{C-g} at command level or to quit a user
command would be unpredictable. If you want to permit quitting inside
The string describing the event looks like one of the following:
+@c FIXME? Also "killed\n" - see example below?
@itemize @bullet
@item
@code{"finished\n"}.
A sentinel runs only while Emacs is waiting (e.g., for terminal
input, or for time to elapse, or for process output). This avoids the
-timing errors that could result from running them at random places in
+timing errors that could result from running sentinels at random places in
the middle of other Lisp programs. A program can wait, so that
sentinels will run, by calling @code{sit-for} or @code{sleep-for}
(@pxref{Waiting}), or @code{accept-process-output} (@pxref{Accepting
into a dead buffer, it will get an error. If the buffer is dead,
@code{(buffer-name (process-buffer @var{process}))} returns @code{nil}.
+@c Note this text is duplicated in the filter functions section.
Quitting is normally inhibited within a sentinel---otherwise, the
effect of typing @kbd{C-g} at command level or to quit a user command
would be unpredictable. If you want to permit quitting inside a
If an error happens during execution of a sentinel, it is caught
automatically, so that it doesn't stop the execution of whatever
programs was running when the sentinel was started. However, if
-@code{debug-on-error} is non-@code{nil}, the error-catching is turned
-off. This makes it possible to use the Lisp debugger to debug the
+@code{debug-on-error} is non-@code{nil}, errors are not caught.
+This makes it possible to use the Lisp debugger to debug the
sentinel. @xref{Debugger}.
While a sentinel is running, the process sentinel is temporarily
For this reason it is not possible for a sentinel to specify
a new sentinel.
+@ignore
In earlier Emacs versions, every sentinel that did regular expression
searching or matching had to explicitly save and restore the match data.
Now Emacs does this automatically for sentinels; they never need to do
-it explicitly. @xref{Match Data}.
+it explicitly.
+@end ignore
+ Note that Emacs automatically saves and restores the match data
+while executing sentinels. @xref{Match Data}.
@defun set-process-sentinel process sentinel
This function associates @var{sentinel} with @var{process}. If
The default behavior when there is no sentinel is to insert a message in
the process's buffer when the process status changes.
-Changes in process sentinel take effect immediately---if the sentinel
+Changes in process sentinels take effect immediately---if the sentinel
is slated to be run but has not been called yet, and you specify a new
sentinel, the eventual call to the sentinel will use the new one.
@defun waiting-for-user-input-p
While a sentinel or filter function is running, this function returns
non-@code{nil} if Emacs was waiting for keyboard input from the user at
-the time the sentinel or filter function was called, @code{nil} if it
+the time the sentinel or filter function was called, or @code{nil} if it
was not.
@end defun
When Emacs exits, it terminates all its subprocesses by sending them
the @code{SIGHUP} signal. Because subprocesses may be doing
valuable work, Emacs normally asks the user to confirm that it is ok
-to terminate them. Each process has a query flag which, if
+to terminate them. Each process has a query flag, which, if
non-@code{nil}, says that Emacs should ask for confirmation before
exiting and thus killing that process. The default for the query flag
is @code{t}, meaning @emph{do} query.
@smallexample
@group
(set-process-query-on-exit-flag (get-process "shell") nil)
- @result{} t
+ @result{} nil
@end group
@end smallexample
@end defun
In addition to accessing and manipulating processes that are
subprocesses of the current Emacs session, Emacs Lisp programs can
also access other processes running on the same machine. We call
-these @dfn{system processes}, to distinguish between them and Emacs
+these @dfn{system processes}, to distinguish them from Emacs
subprocesses.
Emacs provides several primitives for accessing system processes.
by its process ID @var{pid}. Each association in the alist is of the
form @code{(@var{key} . @var{value})}, where @var{key} designates the
attribute and @var{value} is the value of that attribute. The various
-attribute @var{key}'s that this function can return are listed below.
+attribute @var{key}s that this function can return are listed below.
Not all platforms support all of these attributes; if an attribute is
not supported, its association will not appear in the returned alist.
Values that are numbers can be either integer or floating-point,
@section Transaction Queues
@cindex transaction queue
+@c That's not very informative. What is a transaction, and when might
+@c I want to use one?
You can use a @dfn{transaction queue} to communicate with a subprocess
using transactions. First use @code{tq-create} to create a transaction
queue communicating with a specified process. Then you can call
If the argument @var{delay-question} is non-@code{nil}, delay sending
this question until the process has finished replying to any previous
questions. This produces more reliable results with some processes.
+@ignore
+@c Let's not mention it then.
The return value of @code{tq-enqueue} itself is not meaningful.
+@end ignore
@end defun
@defun tq-close queue
@cindex UDP
Emacs Lisp programs can open stream (TCP) and datagram (UDP) network
-connections to other processes on the same machine or other machines.
+connections (@pxref{Datagrams}) 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, so it has no
+communicating with is not a child of the Emacs process, has no
process @acronym{ID}, and you can't kill it or send it signals. All you
can do is send and receive data. @code{delete-process} closes the
connection, but does not kill the program at the other end; that
connection, or @code{real} for a real subprocess.
The @code{process-status} function returns @code{open},
-@code{closed}, @code{connect}, and @code{failed} for network
+@code{closed}, @code{connect}, or @code{failed} for network
connections. For a network server, the status is always
@code{listen}. None of those values is possible for a real
subprocess. @xref{Process Information}.
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.) 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
+system---see the @code{:server} keyword of @code{make-network-process},
+@ref{Network Processes}.) 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} to determine whether a network connection or
server is stopped; a non-@code{nil} value means yes.
@cindex network connection, encrypted
@cindex encrypted network connections
-@cindex TLS network connections
-@cindex STARTTLS network connections
-@defun open-network-stream name buffer-or-name host service &rest parameters
+@cindex @acronym{TLS} network connections
+@cindex @acronym{STARTTLS} network connections
+Emacs can create encrypted network connections, using either built-in
+or external support. The built-in support uses the GnuTLS
+(``Transport Layer Security'') library; see
+@uref{http://www.gnu.org/software/gnutls/, the GnuTLS project page}.
+If your Emacs was compiled with GnuTLS support, the function
+@code{gnutls-available-p} is defined and returns non-@code{nil}. For
+more details, @pxref{Top,, Overview, emacs-gnutls, The Emacs-GnuTLS manual}.
+The external support uses the @file{starttls.el} library, which
+requires a helper utility such as @command{gnutls-cli} to be installed
+on the system. The @code{open-network-stream} function can
+transparently handle the details of creating encrypted connections for
+you, using whatever support is available.
+
+@defun open-network-stream name buffer host service &rest parameters
This function opens a TCP connection, with optional encryption, and
returns a process object that represents the connection.
The @var{name} argument specifies the name for the process object. It
is modified as necessary to make it unique.
-The @var{buffer-or-name} argument is the buffer to associate with the
+The @var{buffer} argument is the buffer to associate with the
connection. Output from the connection is inserted in the buffer,
unless you specify a filter function to handle the output. If
-@var{buffer-or-name} is @code{nil}, it means that the connection is not
+@var{buffer} is @code{nil}, it means that the connection is not
associated with any buffer.
The arguments @var{host} and @var{service} specify where to connect to;
@var{host} is the host name (a string), and @var{service} is the name of
a defined network service (a string) or a port number (an integer).
-@c FIXME? Is this too lengthy for the printed manual?
The remaining arguments @var{parameters} are keyword/argument pairs
that are mainly relevant to encrypted connections:
An ordinary, unencrypted connection.
@item tls
@itemx ssl
-A TLS (``Transport Layer Security'') connection.
+A @acronym{TLS} (``Transport Layer Security'') connection.
@item nil
@itemx network
Start with a plain connection, and if parameters @samp{:success}
and @samp{:capability-command} are supplied, try to upgrade to an encrypted
-connection via STARTTLS. If that fails, retain the unencrypted connection.
+connection via @acronym{STARTTLS}. If that fails, retain the
+unencrypted connection.
@item starttls
-As for @code{nil}, but if STARTTLS fails drop the connection.
+As for @code{nil}, but if @acronym{STARTTLS} fails drop the connection.
@item shell
A shell connection.
@end table
@item :starttls-function @var{function}
Function of one argument (the response to @var{capability-command}),
-which returns either @code{nil}, or the command to activate STARTTLS
+which returns either @code{nil}, or the command to activate @acronym{STARTTLS}
if supported.
@item :success @var{regexp}
-Regular expression matching a successful STARTTLS negotiation.
+Regular expression matching a successful @acronym{STARTTLS} negotiation.
@item :use-starttls-if-possible @var{boolean}
-If non-@code{nil}, do opportunistic STARTTLS upgrades even if Emacs
-doesn't have built-in TLS support.
+If non-@code{nil}, do opportunistic @acronym{STARTTLS} upgrades even if Emacs
+doesn't have built-in @acronym{TLS} support.
@item :client-certificate @var{list-or-t}
Either a list of the form @code{(@var{key-file} @var{cert-file})},
naming the certificate key file and certificate file itself, or
@code{t}, meaning to query @code{auth-source} for this information
-(@pxref{Top,,auth-source, auth, Emacs auth-source Library}).
-Only used for TLS or STARTTLS.
+(@pxref{Top,,Overview, auth, The Auth-Source Manual}).
+Only used for @acronym{TLS} or @acronym{STARTTLS}.
@item :return-list @var{cons-or-nil}
The return value of this function. If omitted or @code{nil}, return a
@section Network Servers
@cindex network servers
- You create a server by calling @code{make-network-process} with
-@code{:server t}. The server will listen for connection requests from
-clients. When it accepts a client connection request, that creates a
-new network connection, itself a process object, with the following
-parameters:
+ You create a server by calling @code{make-network-process}
+(@pxref{Network Processes}) with @code{:server t}. The server will
+listen for connection requests from clients. When it accepts a client
+connection request, that creates a new network connection, itself a
+process object, with the following parameters:
@itemize @bullet
@item
The connection's process name is constructed by concatenating the
server process's @var{name} with a client identification string. The
+@c FIXME? What about IPv6? Say briefly what the difference is?
client identification string for an IPv4 connection looks like
-@samp{<@var{a}.@var{b}.@var{c}.@var{d}:@var{p}>}. Otherwise, it is a
+@samp{<@var{a}.@var{b}.@var{c}.@var{d}:@var{p}>}, which represents an
+address and port number. Otherwise, it is a
unique number in brackets, as in @samp{<@var{nnn}>}. The number
is unique for each connection in the Emacs session.
connections made to the server.
@item
-The connection's process contact info is set according to the client's
+The connection's process contact information is set according to the client's
addressing information (typically an IP address and a port number).
This information is associated with the @code{process-contact}
keywords @code{:host}, @code{:service}, @code{:remote}.
@section Datagrams
@cindex datagrams
- A datagram connection communicates with individual packets rather
+ A @dfn{datagram} connection communicates with individual packets rather
than streams of data. Each call to @code{process-send} sends one
datagram packet (@pxref{Input to Processes}), and each datagram
received results in one call to the filter function.
list of keyword/argument pairs. Omitting a keyword is always
equivalent to specifying it with value @code{nil}, except for
@code{:coding}, @code{:filter-multibyte}, and @code{:reuseaddr}. Here
-are the meaningful keywords:
+are the meaningful keywords (those corresponding to network options
+are listed in the following section):
@table @asis
@item :name @var{name}
@item :server @var{server-flag}
If @var{server-flag} is non-@code{nil}, create a server. Otherwise,
create a connection. For a stream type server, @var{server-flag} may
-be an integer which then specifies the length of the queue of pending
+be an integer, which then specifies the length of the queue of pending
connections to the server. The default queue length is 5.
@item :host @var{host}
connecting to that address will be accepted.
@item :service @var{service}
-@var{service} specifies a port number to connect to, or, for a server,
+@var{service} specifies a port number to connect to; or, for a server,
the port number to listen on. It should be a service name that
translates to a port number, or an integer specifying the port number
directly. For a server, it can also be @code{t}, which means to let
communication. @code{nil} means determine the proper address family
automatically for the given @var{host} and @var{service}.
@code{local} specifies a Unix socket, in which case @var{host} is
-ignored. @code{ipv4} and @code{ipv6} specify to use IPv4 and IPv6
+ignored. @code{ipv4} and @code{ipv6} specify to use IPv4 and IPv6,
respectively.
@item :local @var{local-address}
For a server process, @var{local-address} is the address to listen on.
-It overrides @var{family}, @var{host} and @var{service}, and you
-may as well not specify them.
+It overrides @var{family}, @var{host} and @var{service}, so you
+might as well not specify them.
@item :remote @var{remote-address}
For a connection, @var{remote-address} is the address to connect to.
-It overrides @var{family}, @var{host} and @var{service}, and you
-may as well not specify them.
+It overrides @var{family}, @var{host} and @var{service}, so you
+might as well not specify them.
For a datagram server, @var{remote-address} specifies the initial
setting of the remote datagram address.
port number @var{p}.
@item
-A local address is represented as a string which specifies the address
+A local address is represented as a string, which specifies the address
in the local address space.
@item
has succeeded or failed.
@item :stop @var{stopped}
-Start the network connection or server in the `stopped' state if
-@var{stopped} is non-@code{nil}.
+If @var{stopped} is non-@code{nil}, start the network connection or
+server in the ``stopped'' state.
@item :buffer @var{buffer}
Use @var{buffer} as the process buffer.
@item :filter @var{filter}
Initialize the process filter to @var{filter}.
+@item :filter-multibyte @var{multibyte}
+If @var{multibyte} is non-@code{nil}, strings given to the process
+filter are multibyte, otherwise they are unibyte. The default is the
+default value of @code{enable-multibyte-characters}.
+
@item :sentinel @var{sentinel}
Initialize the process sentinel to @var{sentinel}.
Initialize the log function of a server process to @var{log}. 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{connection}, and @var{message}, where @var{server}
+@var{server}, @var{connection}, and @var{message}; where @var{server}
is the server process, @var{connection} is the new process for the
connection, and @var{message} is a string describing what has
happened.
@item :broadcast @var{broadcast-flag}
If @var{broadcast-flag} is non-@code{nil} for a datagram process, the
process will receive datagram packet sent to a broadcast address, and
-be able to send packets to a broadcast address. Ignored for a stream
+be able to send packets to a broadcast address. This is ignored for a stream
connection.
@item :dontroute @var{dontroute-flag}
transmission of all queued packets on the connection before it is
deleted (see @code{delete-process}). If @var{linger-arg} is an
integer, it specifies the maximum time in seconds to wait for queued
-packets to be sent before closing the connection. Default is
-@code{nil} which means to discard unsent queued packets when the
+packets to be sent before closing the connection. The default is
+@code{nil}, which means to discard unsent queued packets when the
process is deleted.
+@c FIXME Where out-of-band data is ...?
@item :oobinline @var{oobinline-flag}
If @var{oobinline-flag} is non-@code{nil} for a stream connection,
receive out-of-band data in the normal data stream. Otherwise, ignore
@item :priority @var{priority}
Set the priority for packets sent on this connection to the integer
@var{priority}. The interpretation of this number is protocol
-specific, such as setting the TOS (type of service) field on IP
+specific; such as setting the TOS (type of service) field on IP
packets sent on this connection. It may also have system dependent
effects, such as selecting a specific output queue on the network
interface.
@item :reuseaddr @var{reuseaddr-flag}
If @var{reuseaddr-flag} is non-@code{nil} (the default) for a stream
server process, allow this server to reuse a specific port number (see
-@code{:service}) unless another process on this host is already
+@code{:service}), unless another process on this host is already
listening on that port. If @var{reuseaddr-flag} is @code{nil}, there
may be a period of time after the last use of that port (by any
-process on the host), where it is not possible to make a new server on
+process on the host) where it is not possible to make a new server on
that port.
@end table
@defun set-network-process-option process option value &optional no-error
This function sets or modifies a network option for network process
-@var{process}. See @code{make-network-process} for details of options
-@var{option} and their corresponding values @var{value}. If
-@var{no-error} is non-@code{nil}, this function returns @code{nil}
-instead of signaling an error if @var{option} is not a supported
-option. If the function successfully completes, it returns @code{t}.
+@var{process}. The accepted options and values are as for
+@code{make-network-process}. If @var{no-error} is non-@code{nil},
+this function returns @code{nil} instead of signaling an error if
+@var{option} is not a supported option. If the function successfully
+completes, it returns @code{t}.
The current setting of an option is available via the
@code{process-contact} function.
@end example
@noindent
-The result of the first form is @code{t} if it works to specify
+The result of this form is @code{t} if it works to specify
@var{keyword} with value @var{value} in @code{make-network-process}.
-The result of the second form is @code{t} if @var{keyword} is
-supported by @code{make-network-process}. Here are some of the
-@var{keyword}---@var{value} pairs you can test in
+Here are some of the @var{keyword}---@var{value} pairs you can test in
this way.
@table @code
@end example
@noindent
-Here are some of the options you can test in this way.
-
-@table @code
-@item :bindtodevice
-@itemx :broadcast
-@itemx :dontroute
-@itemx :keepalive
-@itemx :linger
-@itemx :oobinline
-@itemx :priority
-@itemx :reuseaddr
-That particular network option is supported by
-@code{make-network-process} and @code{set-network-process-option}.
-@end table
+The accepted @var{keyword} values are @code{:bindtodevice}, etc.
+For the complete list, @pxref{Network Options}. This form returns
+non-@code{nil} if that particular network option is supported by
+@code{make-network-process} (or @code{set-network-process-option}).
@node Misc Network
@section Misc Network Facilities
Before Exit}. The flags defaults to @code{nil} if unspecified.
@item :stop @var{bool}
-Start process in the @code{stopped} state if @var{bool} is
+Start process in the ``stopped'' state if @var{bool} is
non-@code{nil}. In the stopped state, a serial process does not
accept incoming data, but you can send outgoing data. The stopped
state is cleared by @code{continue-process} and set by
HCoop / bpt / emacs.git / blobdiff