/[emacs]/emacs/lispref/processes.texi
ViewVC logotype

Diff of /emacs/lispref/processes.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.33 by rms, Fri Sep 19 14:42:17 2003 UTC revision 1.34 by kfstorm, Tue Sep 23 22:05:38 2003 UTC
# Line 1473  Transaction queues are implemented by me Line 1473  Transaction queues are implemented by me
1473  @section Network Connections  @section Network Connections
1474  @cindex network connection  @cindex network connection
1475  @cindex TCP  @cindex TCP
1476    @cindex UDP
1477    
1478    Emacs Lisp programs can open TCP and datagram network connections to    Emacs Lisp programs can open stream (TCP) and datagram (UDP) network
1479  other processes on the same machine or other machines.  A network  connections to other processes on the same machine or other machines.
1480  connection is handled by Lisp much like a subprocess, and is  A network connection is handled by Lisp much like a subprocess, and is
1481  represented by a process object.  However, the process you are  represented by a process object.  However, the process you are
1482  communicating with is not a child of the Emacs process, so it has no  communicating with is not a child of the Emacs process, so it has no
1483  process @sc{id}, and you can't kill it or send it signals.  All you  process @sc{id}, and you can't kill it or send it signals.  All you
# Line 1504  subprocess.  @xref{Process Information}. Line 1505  subprocess.  @xref{Process Information}.
1505    You can stop and resume operation of a network processes by calling    You can stop and resume operation of a network processes by calling
1506  @code{stop-process} and @code{continue-process}.  For a server  @code{stop-process} and @code{continue-process}.  For a server
1507  process, being stopped means not accepting new connections.  (Up to 5  process, being stopped means not accepting new connections.  (Up to 5
1508  connection requests will be queued for when you resume the server;  connection requests will be queued for when you resume the server; you
1509  this limit is imposed by the operating system.)  For a network  can increase this limit, unless it is imposed by the operating
1510  connection, being stopped means not processing input (any arriving  systems.)  For a network connection, being stopped means not
1511  input waits until you resume the connection).  You can use the  processing input (any arriving input waits until you resume the
1512  function @code{process-command} to determine whether a network  connection).  You can use the function @code{process-command} to
1513  connection or server is stopped; a non-@code{nil} value means yes.  determine whether a network connection or server is stopped; a
1514    non-@code{nil} value means yes.
1515    
1516  @defun open-network-stream name buffer-or-name host service  @defun open-network-stream name buffer-or-name host service
1517  This function opens a TCP connection, and returns a process object  This function opens a TCP connection, and returns a process object
# Line 1565  The associated value is the process buff Line 1567  The associated value is the process buff
1567  @item :filter  @item :filter
1568  The associated value is the process filter function.  The associated value is the process filter function.
1569  @item :sentinel  @item :sentinel
1570  The associated value is the process filter function.  The associated value is the process sentinel function.
1571  @item :remote  @item :remote
1572  In a connection, this is the address in internal format of the remote peer.  In a connection, this is the address in internal format of the remote peer.
1573  @item :local  @item :local
# Line 1599  The connection's process name is constru Line 1601  The connection's process name is constru
1601  server process' @var{name} with a client identification string.  The  server process' @var{name} with a client identification string.  The
1602  client identification string for an IPv4 connection looks like  client identification string for an IPv4 connection looks like
1603  @samp{<@var{a}.@var{b}.@var{c}.@var{d}:@var{p}>}.  Otherwise, it is a  @samp{<@var{a}.@var{b}.@var{c}.@var{d}:@var{p}>}.  Otherwise, it is a
1604  unique number in brackets, as in @samp{<@var{nnn>}}.  The number  unique number in brackets, as in @samp{<@var{nnn}>}.  The number
1605  is unique for each connection in the Emacs session.  is unique for each connection in the Emacs session.
1606    
1607  @item  @item
1608  If the server's filter is non-@code{nil}, the connection process does  If the server's filter is non-@code{nil}, the connection process does
1609  not get a separate process buffer; otherwise, Emacs creates a bew  not get a separate process buffer; otherwise, Emacs creates a new
1610  buffer for the purpose.  The buffer name is the server's buffer name  buffer for the purpose.  The buffer name is the server's buffer name
1611  or process name, concatenated with the client identification string.  or process name, concatenated with the client identification string.
1612    
# Line 1691  This function creates a network connecti Line 1693  This function creates a network connecti
1693  process object that represents it.  The arguments @var{args} are a  process object that represents it.  The arguments @var{args} are a
1694  list of keyword/argument pairs.  Omitting a keyword is always  list of keyword/argument pairs.  Omitting a keyword is always
1695  equivalent to specifying it with value @code{nil}, except for  equivalent to specifying it with value @code{nil}, except for
1696  @code{:coding} and @code{:filter-multibyte}.  Here are the meaningful  @code{:coding}, @code{:filter-multibyte}, and @code{:reuseaddr}.  Here
1697  keywords:  are the meaningful keywords:
1698    
1699  @table @asis  @table @asis
1700  @item :name name  @item :name name
# Line 1706  connection.  Both connections and server Line 1708  connection.  Both connections and server
1708    
1709  @item :server @var{server-flag}  @item :server @var{server-flag}
1710  If @var{server-flag} is non-@code{nil}, create a server.  Otherwise,  If @var{server-flag} is non-@code{nil}, create a server.  Otherwise,
1711  create a connection.  create a connection.  For a stream type server, @var{server-flag} may
1712    be an integer which then specifies the length of the queue of pending
1713    connections to the server.  The default queue length is 5.
1714    
1715  @item :host @var{host}  @item :host @var{host}
1716  Specify the host to connect to.  @var{host} should be a host name or  Specify the host to connect to.  @var{host} should be a host name or
# Line 1785  encoding data sent to it, specify @code{ Line 1789  encoding data sent to it, specify @code{
1789  @var{encoding})} for @var{coding}.  @var{encoding})} for @var{coding}.
1790    
1791  If you don't specify this keyword at all, the default  If you don't specify this keyword at all, the default
1792  is to determine the coding systemx from the data.  is to determine the coding systems from the data.
   
 @item :options @var{options}  
 Set the specified options for the network process.  See  
 @code{set-network-process-options} for details.  
1793    
1794  @item :noquery @var{query-flag}  @item :noquery @var{query-flag}
1795  Initialize the process query flag to @var{query-flag}.  Initialize the process query flag to @var{query-flag}.  @xref{Query Before Exit}.
1796    
1797  @item :filter @var{filter}  @item :filter @var{filter}
1798  Initialize the process filter to @var{filter}.  Initialize the process filter to @var{filter}.
# Line 1819  happened. Line 1819  happened.
1819  Initialize the process plist to @var{plist}.  Initialize the process plist to @var{plist}.
1820  @end table  @end table
1821    
1822    The following network options can be specified for the network
1823    process.  Except for @code{:reuseaddr}, you can set or modify these
1824    options later using @code{set-network-process-option}.
1825    
1826    For a server process, the options specified with
1827    @code{make-network-process} are not inherited by the client
1828    connections, so you will need to set the necessary options for each
1829    child connection as they are created.
1830    
1831    @table asis
1832    @item :bindtodevice @var{device-name}
1833    If @var{device-name} is a non-empty string identifying a network
1834    interface name (see @code{network-interface-list}), only handle
1835    packets received on that interface.  If @var{device-name} is nil (the
1836    default), handle packets received on any interface.
1837    
1838    Using this option may require special privileges on some systems.
1839    
1840    @item :broadcast @var{broadcast-flag}
1841    If @var{broadcast-flag} is non-@code{nil} for a datagram process, the
1842    process will receive datagram packet sent to a broadcast address, and
1843    be able to send packets to a broadcast address.  Ignored for a stream
1844    connection.
1845    
1846    @item :dontroute @var{dontroute-flag}
1847    If @var{dontroute-flag} is non-@code{nil}, the process can only send
1848    to hosts on the same network as the local host.
1849    
1850    @item :keepalive @var{keepalive-flag}
1851    If @var{keepalive-flag} is non-@code{nil} for a stream connection,
1852    enable exchange of low-level keep-alive messa
1853    
1854    @item :linger @var{linger-arg}
1855    If @var{linger-arg} is non-@code{nil}, wait for successful
1856    transmission of all queued packets on the connection before it is
1857    deleted (see @code{delete-process}).  If @var{linger-arg} is an
1858    integer, it specifies the maximum time in seconds to wait for queued
1859    packets to be sent before closing the connection.  Default is
1860    @code{nil} which means to discard unsent queued packets when the
1861    process is deleted.
1862    
1863    @item :oobinline @var{oobinline-flag}
1864    If @var{oobinline-flag} is non-@code{nil} for a stream connection,
1865    receive out-of-band data in the normal data stream.  Otherwise, ignore
1866    out-of-band data.
1867    
1868    @item :priority @var{priority}
1869    Set the priority for packets sent on this connection to the integer
1870    @var{priority}.  The interpretation of this number is protocol
1871    specific, such as setting the TOS (type of service) field on IP
1872    packets sent on this connection.  It may also have system dependent
1873    effects, such as selecting a specific output queue on the network
1874    interface.
1875    
1876    @item :reuseaddr @var{reuseaddr-flag}
1877    If @var{reuseaddr-flag} is non-@code{nil} (the default) for a stream
1878    server process, allow this server to reuse a specific port number (see
1879    @code{:service}) unless another process on this host is already
1880    listening on that port.  If @var{reuseaddr-flag} is @code{nil}, there
1881    may be a period of time after the last use of that port (by any
1882    process on the host), where it is not possible to make a new server on
1883    that port.
1884    
1885    @end table
1886    
1887  The original argument list, modified with the actual connection  The original argument list, modified with the actual connection
1888  information, is available via the `process-contact' function.  information, is available via the `process-contact' function.
1889  @end defun  @end defun
1890    
1891    @defun set-network-process-option process option value
1892    This function sets or modifies a network option for network process
1893    @var{process}.  See @code{make-network-process} for details of options
1894    @var{option} and their corresponding values @var{value}.
1895    
1896    The current setting of an option is available via the
1897    `process-contact' function.
1898    @end defun
1899    
1900  @defun network-interface-list  @defun network-interface-list
1901  This function returns a list describing the network interfaces  This function returns a list describing the network interfaces
1902  of the machine you are using.  The value is an alist whose  of the machine you are using.  The value is an alist whose
# Line 1869  the port number. Line 1943  the port number.
1943  @end example  @end example
1944    
1945  @noindent  @noindent
1946  The result is @code{t} if it works to specify @var{keyword} with value  The result of the first form is @code{t} if it works to specify
1947  @var{value} in @code{make-network-process}.  Here are some of the  @var{keyword} with value @var{value} in @code{make-network-process}.
1948  @var{keyword}---@var{value} pairs you can test in this way.  The result of the second form is @code{t} if @var{keyword} is
1949    supported by @code{make-network-process}.  Here are some of the
1950    @var{keyword}---@var{value} pairs you can test in
1951    this way.
1952    
1953  @table @code  @table @code
1954  @item (:nowait t)  @item (:nowait t)
# Line 1882  Non-@code{nil} if datagrams are supporte Line 1959  Non-@code{nil} if datagrams are supporte
1959  Non-@code{nil} if local (aka ``UNIX domain'') sockets are supported.  Non-@code{nil} if local (aka ``UNIX domain'') sockets are supported.
1960  @item (:service t)  @item (:service t)
1961  Non-@code{nil} if the system can select the port for a server.  Non-@code{nil} if the system can select the port for a server.
1962  @item (:options bindtodevice)  @end table
1963  @itemx (:options broadcast)  
1964  @itemx (:options dontroute)    To test for the availability of a given network option, use
1965  @itemx (:options keepalive)  @code{featurep} like this:
1966  @itemx (:options linger)  
1967  @itemx (:options oobinline)  @example
1968  @itemx (:options priority)  (featurep 'make-network-process '@var{keyword})
1969  @itemx (:options reuseaddr)  @end example
1970  That particular socket option is supported.  
1971    Here are some of the option @var{keyword}s you can test in
1972    this way.
1973    
1974    @table @code
1975    @item :bindtodevice
1976    @itemx :broadcast
1977    @itemx :dontroute
1978    @itemx :keepalive
1979    @itemx :linger
1980    @itemx :oobinline
1981    @itemx :priority
1982    @itemx :reuseaddr
1983    That particular network option is supported by
1984    @code{make-network-process} and @code{set-network-process-option}.
1985  @end table  @end table
1986    
1987  @ignore  @ignore

Legend:
Removed from v.1.33  
changed lines
  Added in v.1.34

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26