Mercurial > emacs

--- a/lispref/processes.texi	Fri Sep 19 14:38:03 2003 +0000
+++ b/lispref/processes.texi	Fri Sep 19 14:42:17 2003 +0000
@@ -48,6 +48,10 @@
 * Query Before Exit::        Whether to query if exiting will kill a process.
 * Transaction Queues::	     Transaction-based communication with subprocesses.
 * Network::                  Opening network connections.
+* Network Servers::          Network servers let Emacs accept net connections.
+* Datagrams::
+* Low-Level Network::        Lower-level but more general function
+                               to create connections and servers.
 @end menu

 @node Subprocess Creation
@@ -376,6 +380,13 @@
 @end smallexample
 @end defun

+@defun call-process-shell-command command &optional infile destination display &rest args
+This function executes the shell command @var{command} synchronously
+in separate process.  The final arguments @var{args} are additional
+arguments to add at the end of @var{command}.  The other arguments
+are handled as in @code{call-process}.
+@end defun
+
 @defun shell-command-to-string command
 This function executes @var{command} (a string) as a shell command,
 then returns the command's output as a string.
@@ -539,10 +550,13 @@
   Several functions return information about processes.
 @code{list-processes} is provided for interactive use.

-@deffn Command list-processes
+@deffn Command list-processes &optional query-only
 This command displays a listing of all living processes.  In addition,
 it finally deletes any process whose status was @samp{Exited} or
 @samp{Signaled}.  It returns @code{nil}.
+
+If @var{query-only} is non-@code{nil} then it lists only processes
+whose query flag is non-@code{nil}.  @xref{Query Before Exit}.
 @end deffn

 @defun process-list
@@ -594,12 +608,6 @@
 This function returns the name of @var{process}.
 @end defun

-@defun process-contact process
-This function returns @code{t} for an ordinary child process, and
-@code{(@var{hostname} @var{service})} for a net connection
-(@pxref{Network}).
-@end defun
-
 @defun process-status process-name
 This function returns the status of @var{process-name} as a symbol.
 The argument @var{process-name} must be a process, a buffer, a
@@ -622,6 +630,12 @@
 for a network connection that is closed.  Once a connection
 is closed, you cannot reopen it, though you might be able to open
 a new connection to the same place.
+@item connect
+for a non-blocking connection that is waiting to complete.
+@item failed
+for a non-blocking connection that has failed to complete.
+@item listen
+for a network server that is listening.
 @item nil
 if @var{process-name} is not the name of an existing process.
 @end table
@@ -679,6 +693,27 @@
 input.
 @end defun

+  Every process also has a property list that you can use to store
+miscellaneous values associated with the process.
+
+@defun process-get process propname
+This function returns the value of the @var{propname} property
+of @var{process}.
+@end defun
+
+@defun process-put process propname value
+This function sets the value of the @var{propname} property
+of @var{process} to @var{value}.
+@end defun
+
+@defun process-plist process
+This function returns the process plist of @var{process}.
+@end defun
+
+@defun set-process-plist process plist
+This function sets the process plist of @var{process} to @var{plist}.
+@end defun
+
 @node Input to Processes
 @section Sending Input to Processes
 @cindex process input
@@ -859,10 +894,12 @@
 @end defun

 @c Emacs 19 feature
-@defun signal-process pid signal
-This function sends a signal to process @var{pid}, which need not be
-a child of Emacs.  The argument @var{signal} specifies which signal
-to send; it should be an integer.
+@defun signal-process process signal
+This function sends a signal to process @var{process}.  The argument
+@var{signal} specifies which signal to send; it should be an integer.
+
+You can specify the target process by its process @sc{id}; that allows
+you to send signals to processes that are not children of Emacs.
 @end defun

 @node Output from Processes
@@ -1437,24 +1474,46 @@
 @cindex network connection
 @cindex TCP

-  Emacs Lisp programs can open TCP network connections 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 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 process at the other end; that process must decide
-what to do about closure of the connection.
+  Emacs Lisp programs can open TCP and datagram network connections 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
+process @sc{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
+program must decide what to do about closure of the connection.
+
+  Lisp programs can listen for connections by creating network
+servers.  A network server is also represented by a kind of process
+object, but unlike a network connection, the network server never
+transfers data itself.  When it receives a connection request, it
+creates a new network connection to represent the connection just
+made.  (The network connection inherits certain information, including
+the process plist, from the server.)  The network server then goes
+back to listening for more connection requests.

   You can distinguish process objects representing network connections
-from those representing subprocesses with the @code{process-status}
-function.  It always returns either @code{open} or @code{closed} for a
-network connection, and it never returns either of those values for a
-real subprocess.  @xref{Process Information}.
+and servers from those representing subprocesses with the
+@code{process-status} function.  The possible status values for
+network connections are @code{open}, @code{closed}, @code{connect},
+and @code{failed}.  For a network server, the status is always
+@code{listen}.  None of those values is possible for a real
+subprocess.  @xref{Process Information}.
+
+  You can stop and resume operation of a network processes by calling
+@code{stop-process} and @code{continue-process}.  For a server
+process, being stopped means not accepting new connections.  (Up to 5
+connection requests will be queued for when you resume the server;
+this limit is imposed by the operating system.)  For a network
+connection, being stopped means not processing input (any arriving
+input waits until you resume the connection).  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.

 @defun open-network-stream name buffer-or-name host service
-This function opens a TCP connection for a service to a host.  It
-returns a process object to represent the connection.
+This function opens a TCP connection, 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.
@@ -1470,6 +1529,371 @@
 a defined network service (a string) or a port number (an integer).
 @end defun

+@defun open-network-stream-nowait name buffer-or-name host service &optional sentinel filter
+This function opens a TCP connection, like @code{open-network-stream},
+but it returns immediately without waiting for the request to be
+accepted or rejected by the remote server.  When the request is
+subsequently accepted or rejected, the process's sentinel function
+will be called with a string that starts with @code{"open"} (on
+success) or @code{"failed"} (on error).
+
+Some systems do not support non-blocking connections; on those
+systems, @code{open-network-stream-nowait} returns @code{nil}
+and does nothing.
+
+The optional arguments @var{sentinel} and @var{filter} specify the
+sentinel and filter functions for this network connection.  It is
+useful to specify them when opening the connection, because they will
+be used later asynchronously.  The other arguments mean the same as in
+@code{open-network-stream}.
+@end defun
+
+@defun process-contact process &optional key
+This function returns information about how a network process was set
+up.  For a connection, when @var{key} is @code{nil}, it returns
+@code{(@var{hostname} @var{service})} which specifies what you
+connected to.
+
+If @var{key} is @code{t}, the value is the complete status information
+for the connection or server; that is, the list of keywords and values
+specified in @code{make-network-process}, except that some of the
+values represent the current status instead of what you specified:
+
+@table @code
+@item :buffer
+The associated value is the process buffer.
+@item :filter
+The associated value is the process filter function.
+@item :sentinel
+The associated value is the process filter function.
+@item :remote
+In a connection, this is the address in internal format of the remote peer.
+@item :local
+The local address, in internal format.
+@item :service
+In a server, if you specified @code{t} for @var{service},
+this value is the actual port number.
+@end table
+
+@code{:local} and @code{:remote} are included even if they were not
+specified explicitly in @code{make-network-process}.
+
+If @var{key} is a keyword, the function returns the value corresponding
+to that keyword.
+
+For an ordinary child process, this function always returns @code{t}.
+@end defun
+
+@node Network Servers
+@section 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:
+
+@itemize @bullet
+@item
+The connection's process name is constructed by concatenating the
+server process' @var{name} with a client identification string.  The
+client identification string for an IPv4 connection looks like
+@samp{<@var{a}.@var{b}.@var{c}.@var{d}:@var{p}>}.  Otherwise, it is a
+unique number in brackets, as in @samp{<@var{nnn>}}.  The number
+is unique for each connection in the Emacs session.
+
+@item
+If the server's filter is non-@code{nil}, the connection process does
+not get a separate process buffer; otherwise, Emacs creates a bew
+buffer for the purpose.  The buffer name is the server's buffer name
+or process name, concatenated with the client identification string.
+
+The server's process buffer value is never used directly by Emacs, but
+it is passed to the log function, which can log connections by
+inserting text there.
+
+@item
+The communication type and the process filter and sentinel are
+inherited from those of the server.  The server never directly
+uses its filter and sentinel; their sole purpose is to initialize
+connections made to the server.
+
+@item
+The connection's process contact info 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}.
+
+@item
+The connection's local address is set up according to the port
+number used for the connection.
+
+@item
+The client process' plist is initialized from the server's plist.
+@end itemize
+
+@defun open-network-stream-server name buffer-or-name service &optional sentinel filter
+Create a network server process for a TCP service.
+It returns nil if server processes are not supported; otherwise,
+it returns a subprocess-object to represent the server.
+
+When a client connects to the specified service, Emacs creates a new
+subprocess to handle the new connection, and then calls its sentinel
+function (which it has inherited from the server).
+
+The optional arguments @var{sentinel} and @var{filter} specify the
+sentinel and filter functions for the server.  It is useful to specify
+them now, because they will be used later asynchronously when the
+server receives a connection request.  The three arguments @var{name},
+@var{buffer-or-name} and @var{service} mean the same thing as in
+@code{open-network-stream}, but @var{service} can be @code{t}
+meaning ask the system to allocate an unused port to listen on.
+@end defun
+
+@node Datagrams
+@section Datagrams
+@cindex datagrams
+
+  A datagram connection communicates with individual packets
+rather than streams of data.  Each call to @code{process-send}
+sends one datagram packet, and each datagram received results
+in one call to the filter function.
+
+  The datagram connection doesn't have to talk with the same remote
+peer all the time.  It has a @dfn{remote peer address} which specifies
+where to send datagrams to.  Each time an incoming datagram is passed
+to the filter function, the peer address is set to the address that
+datagram came from; that way, if the filter function sends a datagram,
+it will go back to that place.  You can specify the remote peer
+address when you create the datagram connection using the
+@code{:remote} keyword.  You can change it later on by calling
+@code{set-process-datagram-address}.
+
+@defun process-datagram-address process
+If @var{process} is a datagram connection or server, this function
+returns its remote peer address.
+@end defun
+
+@defun set-process-datagram-address process address
+If @var{process} is a datagram connection or server, this function
+sets its remote peer address to @var{address}.
+@end defun
+
+@node Low-Level Network
+@section Low-Level Network Access
+
+   The basic function for creating network connections and network
+servers is @code{make-network-process}.  It can do either of those
+jobs, depending on the arguments you give it.
+
+@defun make-network-process &rest args
+This function creates a network connection or server and returns the
+process object that represents it.  The arguments @var{args} are a
+list of keyword/argument pairs.  Omitting a keyword is always
+equivalent to specifying it with value @code{nil}, except for
+@code{:coding} and @code{:filter-multibyte}.  Here are the meaningful
+keywords:
+
+@table @asis
+@item :name name
+Use the string @var{name} as the process name.  It is modified if
+necessary to make it unique.
+
+@item :type @var{type}
+Specify the communication type.  A value of @code{nil} specifies a
+stream connection (the default); @code{datagram} specifies a datagram
+connection.  Both connections and servers can be of either type.
+
+@item :server @var{server-flag}
+If @var{server-flag} is non-@code{nil}, create a server.  Otherwise,
+create a connection.
+
+@item :host @var{host}
+Specify the host to connect to.  @var{host} should be a host name or
+internet address, as a string, or the symbol @code{local} to specify
+the local host.  If you specify @var{host} for a server, it must
+specify a valid address for the local host, and only clients
+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
+directly.  For a server, it can also be @code{t}, which means to let
+the system select an unused port number.
+
+@item :family @var{family}
+@var{family} specifies the address (and protocol) family for
+communication.  @code{nil} stands for IPv4.  @code{local} specifies a
+Unix socket, in which case @var{host} is 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}, and you
+may 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.
+
+For a datagram server, @var{remote-address} specifies the initial
+setting of the remote datagram address.
+
+The format of @var{local-address} or @var{remote-address} depends on
+the address family:
+
+@itemize -
+@item
+An IPv4 address is represented as a vector of integers @code{[@var{a}
+@var{b} @var{c} @var{d} @var{p}]} corresponding to numeric IP address
+@var{a}.@var{b}.@var{c}.@var{d} and port number @var{p}.
+
+@item
+A local address is represented as a string which specifies the address
+in the local address space.
+
+@item
+An ``unsupported family'' address is represented by a cons
+@code{(@var{f} . @var{av})}, where @var{f} is the family number and
+@var{av} is a vector specifying the socket address using with 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.
+@end itemize
+
+@item :nowait @var{bool}
+If @var{bool} is non-@code{nil} 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"} (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.
+
+@item :stop @var{stopped}
+Start the network connection or server in the `stopped' state if
+@var{stopped} is non-@code{nil}.
+
+@item :buffer @var{buffer}
+Use @var{buffer} as the process buffer.
+
+@item :coding @var{coding}
+Use @var{coding} 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{encoding})} for @var{coding}.
+
+If you don't specify this keyword at all, the default
+is to determine the coding systemx from the data.
+
+@item :options @var{options}
+Set the specified options for the network process.  See
+@code{set-network-process-options} for details.
+
+@item :noquery @var{query-flag}
+Initialize the process query flag to @var{query-flag}.
+
+@item :filter @var{filter}
+Initialize the process filter to @var{filter}.
+
+@item :filter-multibyte @var{bool}
+If @var{bool} is non-@code{nil}, strings given to the process filter
+are multibyte, otherwise they are unibyte.  If you don't specify this
+keyword at all, the default is that the strings are multibyte if
+@code{default-enable-multibyte-characters} is non-@code{nil}.
+
+@item :sentinel @var{sentinel}
+Initialize the process sentinel to @var{sentinel}.
+
+@item :log @var{log}
+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}
+is the server process, @var{connection} is the new process for the
+connection, and @var{message} is a string describing what has
+happened.
+
+@item :plist @var{plist}
+Initialize the process plist to @var{plist}.
+@end table
+
+The original argument list, modified with the actual connection
+information, is available via the `process-contact' function.
+@end defun
+
+@defun network-interface-list
+This function returns a list describing the network interfaces
+of the machine you are using.  The value is an alist whose
+elements have the form @code{(@var{name} . @var{address})}.
+@var{address} has the same form as the @var{local-address}
+and @var{remote-address} arguments to @code{make-network-process}.
+@end defun
+
+@defun network-interface-info ifname
+This function returns information about the network interface named
+@var{ifname}.  The value is a list of the form @code{(@var{addr} @var{bcast} @var{netmask} @var{hwaddr} @var{flags})}.
+
+@table @var
+@item addr
+The internet protocol address.
+@item bcast
+The broadcast address.
+@item netmask
+The network mask.
+@item hwaddr
+The layer 2 address (Ethernet MAC address, for instance).
+@item flags
+The current flags of the interface.
+@end table
+@end defun
+
+@defun format-network-address address &optional omit-port
+This function converts the lisp representation of a network address to
+a string.  For example, a five-element vector @code{[@var{a} @var{b}
+@var{c} @var{d} @var{p}]} represents an IP address
+@var{a}.@var{b}.@var{c}.@var{d} and port number @var{p}.
+@code{format-network-address} converts that to the string
+@code{"@var{a}.@var{b}.@var{c}.@var{d}:@var{p}"}.
+
+If @var{omit-port} is non-@code{nil}, the value does not include
+the port number.
+@end defun
+
+  To test for the availability of a given network feature, use
+@code{featurep} like this:
+
+@example
+(featurep 'make-network-process '(@var{keyword} @var{value}))
+@end example
+
+@noindent
+The result is @code{t} if it works to specify @var{keyword} with value
+@var{value} in @code{make-network-process}.  Here are some of the
+@var{keyword}---@var{value} pairs you can test in this way.
+
+@table @code
+@item (:nowait t)
+Non-@code{nil} if non-blocking connect is supported.
+@item (:type datagram)
+Non-@code{nil} if datagrams are supported.
+@item (:family local)
+Non-@code{nil} if local (aka ``UNIX domain'') sockets are supported.
+@item (:service t)
+Non-@code{nil} if the system can select the port for a server.
+@item (:options bindtodevice)
+@itemx (:options broadcast)
+@itemx (:options dontroute)
+@itemx (:options keepalive)
+@itemx (:options linger)
+@itemx (:options oobinline)
+@itemx (:options priority)
+@itemx (:options reuseaddr)
+That particular socket option is supported.
+@end table
+
 @ignore
    arch-tag: ba9da253-e65f-4e7f-b727-08fba0a1df7a
 @end ignore
+