; Merge from origin/emacs-25

[gnu-emacs] / doc / lispref / processes.texi

diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi
index 8234501fd89eb48135e4b26c369388c21552d445..e8a9ad05c22b3c9713759375f19f56552e4d5874 100644 (file)
--- a/doc/lispref/processes.texi
+++ b/doc/lispref/processes.texi
@@ -2128,7 +2128,8 @@ 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).
+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:
@@ -2352,8 +2353,9 @@ connecting to that address will be accepted.
 
 @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.
 
@@ -2365,6 +2367,12 @@ automatically for the given @var{host} and @var{service}.
 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
@@ -2426,12 +2434,20 @@ Depending on the capabilities of Emacs, how asynchronous
 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
-optained from the @code{gnutls-boot-parameters} function.)  The TLS
+obtained from the @code{gnutls-boot-parameters} function.)  The TLS
 connection will then be negotiated after completing the connection to
 the host.