@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2016 Free Software
@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Processes
Precisely what this function does depends on your operating system. The
function is designed to work with the syntax of your system's standard
shell; if you use an unusual shell, you will need to redefine this
-function.
+function. @xref{Security Considerations}.
@example
;; @r{This example shows the behavior on GNU and Unix systems.}
Insert the output in that buffer, before point. This includes both the
standard output stream and the standard error stream of the process.
-@item a string
+@item a buffer name (a string)
Insert the output in a buffer with that name, before point.
@item @code{t}
stopped state.
@item :filter @var{filter}
-Initialize the process filter to @var{filter}.
+Initialize the process filter to @var{filter}. If not specified, a
+default filter will be provided. @xref{Filter Functions}.
@item :sentinel @var{sentinel}
-Initialize the process sentinel to @var{sentinel}.
+Initialize the process sentinel to @var{sentinel}. If not specified,
+a default sentinel will be used. @xref{Sentinels}.
@item :stderr @var{stderr}
Associate @var{stderr} with the standard error of the process.
stopped state.
@item :filter @var{filter}
-Initialize the process filter to @var{filter}.
+Initialize the process filter to @var{filter}. If not specified, a
+default filter will be provided. @xref{Filter Functions}.
@item :sentinel @var{sentinel}
-Initialize the process sentinel to @var{sentinel}.
+Initialize the process sentinel to @var{sentinel}. If not specified,
+a default sentinel will be used. @xref{Sentinels}.
@end table
The original argument list, modified with the actual connection
@item :buffer
The associated value is the process buffer.
@item :filter
-The associated value is the process filter function.
+The associated value is the process filter function. @xref{Filter
+Functions}.
@item :sentinel
-The associated value is the process sentinel function.
+The associated value is the process sentinel function. @xref{Sentinels}.
@item :remote
In a connection, the address in internal format of the remote peer.
@item :local
@end defun
@defun process-running-child-p &optional process
-This function will tell you whether a @var{process} has given control of
-its terminal to its own child process. The value is @code{t} if this is
-true, or if Emacs cannot tell; it is @code{nil} if Emacs can be certain
-that this is not so.
+This function will tell you whether a @var{process} has given control
+of its terminal to its own child process. If this is true, the
+function returns the numeric ID of the foreground process group of
+@var{process}; it returns @code{nil} if Emacs can be certain that this
+is not so. The value is @code{t} if Emacs cannot tell whether this is
+true.
@end defun
@node Signals to Processes
subprocess with a @code{SIGHUP} signal (@pxref{Signals to Processes}).
@end defun
+If the process's buffer is displayed in a window, your Lisp program
+may wish telling the process the dimensions of that window, so that
+the process could adapt its output to those dimensions, much as it
+adapts to the screen dimensions. The following functions allow to
+communicate this kind of information to processes; however, not all
+systems support the underlying functionality, so it is best to provide
+fallbacks, e.g., via command-line arguments or environment variables.
+
+@defun set-process-window-size process height width
+Tell @var{process} that its logical window size has dimensions
+@var{width} by @var{height}, in character units. If this function
+succeeds in communicating this information to the process, it returns
+@code{t}; otherwise it returns @code{nil}.
+@end defun
+
+When windows that display buffers associated with process change their
+dimensions, the affected processes should be told about these changes.
+By default, when the window configuration changes, Emacs will
+automatically call @code{set-process-window-size} on behalf of every
+process whose buffer is displayed in a window, passing it the smallest
+dimensions of all the windows displaying the process's buffer. This
+works via @code{window-configuration-change-hook} (@pxref{Window
+Hooks}), which is told to invoke the function that is the value of
+the variable @code{window-adjust-process-window-size-function} for
+each process whose buffer is displayed in at least one window. You
+can customize this behavior by setting the value of that variable.
+
+@defopt window-adjust-process-window-size-function
+The value of this variable should be a function of two arguments: a
+process and the list of windows displaying the process's buffer. When
+the function is called, the process's buffer is the current buffer.
+The function should return a cons cell @w{@code{(@var{width}
+. @var{height})}} that describes the dimensions of the logical process
+window to be passed via a call to @code{set-process-window-size}. The
+function can also return @code{nil}, in which case Emacs will not call
+@code{set-process-window-size} for this process.
+
+Emacs supplies two predefined values for this variable:
+@code{window-adjust-process-window-size-smallest}, which returns the
+smallest of all the dimensions of the windows that display a process's
+buffer; and @code{window-adjust-process-window-size-largest}, which
+returns the largest dimensions. For more complex strategies, write
+your own function.
+
+This variable can be buffer-local.
+@end defopt
+
+If the process has the @code{adjust-window-size-function} property
+(@pxref{Process Information}), its value overrides the global and
+buffer-local values of
+@code{window-adjust-process-window-size-function}.
+
@node Filter Functions
@subsection Process Filter Functions
@cindex filter function
@cindex process filter
+@cindex default filter function of a process
A process @dfn{filter function} is a function that receives the
standard output from the associated process. @emph{All} output from
that process is passed to the filter. The default filter simply
arguments: the process for which the event occurred, and a string
describing the type of event.
+@cindex default sentinel function of a process
+ If no sentinel function was specified for a process, it will use the
+default sentinel function, which inserts a message in the process's
+buffer with the process name and the string describing the event.
+
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"}.
@item
-@code{"exited abnormally with code @var{exitcode}\n"}.
+@code{"deleted\n"}.
@item
-@code{"@var{name-of-signal}\n"}.
+@code{"exited abnormally with code @var{exitcode} (core dumped)\n"}.
+The ``core dumped'' part is optional, and only appears if the process
+dumped core.
@item
-@code{"@var{name-of-signal} (core dumped)\n"}.
+@code{"failed with code @var{fail-code}\n"}.
+
+@item
+@code{"@var{signal-description} (core dumped)\n"}. The
+@var{signal-description} is a system-dependent textual description of
+a signal, e.g., @code{"killed"} for @code{SIGKILL}. The ``core
+dumped'' part is optional, and only appears if the process dumped
+core.
+
+@item
+@code{"open from @var{host-name}\n"}.
+
+@item
+@code{"open\n"}.
+
+@item
+@code{"connection broken by remote peer\n"}.
@end itemize
A sentinel runs only while Emacs is waiting (e.g., for terminal
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).
+a defined network service (a string) or a port number (an integer like
+@code{80} or an integer string like @code{"80"}).
The remaining arguments @var{parameters} are keyword/argument pairs
that are mainly relevant to encrypted connections:
@item :service @var{service}
@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
+the port number to listen on. It should be a service name like
+@samp{"http"} that translates to a port number, or an integer like @samp{80}
+or an integer string like @samp{"80"} that specifies the port number
directly. For a server, it can also be @code{t}, which means to let
the system select an unused port number.
ignored. @code{ipv4} and @code{ipv6} specify to use IPv4 and IPv6,
respectively.
+@item :use-external-socket @var{use-external-socket}
+If @var{use-external-socket} is non-@code{nil} 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.
+
@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}, so you
succeeds or fails, Emacs will call the sentinel function, with a
second argument matching @code{"open"} (if successful) or
@code{"failed"}. The default is to block, so that
-@code{make-network-process} does not return until the connection
-has succeeded or failed.
+@code{make-network-process} does not return until the connection has
+succeeded or failed.
+
+If you're setting up an asynchronous TLS connection, you have to also
+provide the @code{:tls-parameters} parameter (see below).
+
+Depending on the capabilities of Emacs, how asynchronous
+@code{:nowait} 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.
+
+Many functions that interact with process objects, (for instance,
+@code{process-datagram-address}) 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"}. That way, none of these functions will block.
+
+@item :tls-parameters
+When opening a TLS connection, this should be where the first element
+is the TLS type (which should either be @code{gnutls-x509pki} or
+@code{gnutls-anon}, and the remaining elements should form a keyword
+list acceptable for @code{gnutls-boot}. (This keyword list can be
+obtained from the @code{gnutls-boot-parameters} function.) The TLS
+connection will then be negotiated after completing the connection to
+the host.
@item :stop @var{stopped}
If @var{stopped} is non-@code{nil}, start the network connection or
@item (:type datagram)
Non-@code{nil} if datagrams are supported.
@item (:family local)
-Non-@code{nil} if local (a.k.a.@: UNIX domain) sockets are supported.
+Non-@code{nil} if local (a.k.a.@: ``UNIX domain'') sockets are supported.
@item (:family ipv6)
Non-@code{nil} if IPv6 is supported.
@item (:service t)
A field's @dfn{type} describes the size (in bytes) of the object
that the field represents and, in the case of multibyte fields, how
the bytes are ordered within the field. The two possible orderings
-are big endian (also known as network byte ordering) and
-little endian. For instance, the number @code{#x23cd} (decimal
+are @dfn{big endian} (also known as ``network byte ordering'') and
+@dfn{little endian}. For instance, the number @code{#x23cd} (decimal
9165) in big endian would be the two bytes @code{#x23} @code{#xcd};
and in little endian, @code{#xcd} @code{#x23}. Here are the possible
type values: