@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
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