# HG changeset patch # User Richard M. Stallman # Date 1063982537 0 # Node ID 0df4c5163e4ec69ddef96e1c1b648be0abf95165 # Parent b0b4c9f22ee70cfea474def0eac78c45972c2633 (Process Information): Add list-processes arg QUERY-ONLY. Delete process-contact from here. Add new status values for process-status. Add process-get, process-put, process-plist, set-process-plist. (Synchronous Processes): Add call-process-shell-command. (Signals to Processes): signal-process allows process objects. (Network): Complete rewrite. (Network Servers, Datagrams, Low-Level Network): New nodes. diff -r b0b4c9f22ee7 -r 0df4c5163e4e lispref/processes.texi --- 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 +