/[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.32 by miles, Mon Sep 1 15:45:41 2003 UTC revision 1.33 by rms, Fri Sep 19 14:42:17 2003 UTC
# Line 48  This function returns @code{t} if @var{o Line 48  This function returns @code{t} if @var{o
48  * Query Before Exit::        Whether to query if exiting will kill a process.  * Query Before Exit::        Whether to query if exiting will kill a process.
49  * Transaction Queues::       Transaction-based communication with subprocesses.  * Transaction Queues::       Transaction-based communication with subprocesses.
50  * Network::                  Opening network connections.  * Network::                  Opening network connections.
51    * Network Servers::          Network servers let Emacs accept net connections.
52    * Datagrams::
53    * Low-Level Network::        Lower-level but more general function
54                                   to create connections and servers.
55  @end menu  @end menu
56    
57  @node Subprocess Creation  @node Subprocess Creation
# Line 376  inputinput@point{} Line 380  inputinput@point{}
380  @end smallexample  @end smallexample
381  @end defun  @end defun
382    
383    @defun call-process-shell-command command &optional infile destination display &rest args
384    This function executes the shell command @var{command} synchronously
385    in separate process.  The final arguments @var{args} are additional
386    arguments to add at the end of @var{command}.  The other arguments
387    are handled as in @code{call-process}.
388    @end defun
389    
390  @defun shell-command-to-string command  @defun shell-command-to-string command
391  This function executes @var{command} (a string) as a shell command,  This function executes @var{command} (a string) as a shell command,
392  then returns the command's output as a string.  then returns the command's output as a string.
# Line 539  will happen sooner or later). Line 550  will happen sooner or later).
550    Several functions return information about processes.    Several functions return information about processes.
551  @code{list-processes} is provided for interactive use.  @code{list-processes} is provided for interactive use.
552    
553  @deffn Command list-processes  @deffn Command list-processes &optional query-only
554  This command displays a listing of all living processes.  In addition,  This command displays a listing of all living processes.  In addition,
555  it finally deletes any process whose status was @samp{Exited} or  it finally deletes any process whose status was @samp{Exited} or
556  @samp{Signaled}.  It returns @code{nil}.  @samp{Signaled}.  It returns @code{nil}.
557    
558    If @var{query-only} is non-@code{nil} then it lists only processes
559    whose query flag is non-@code{nil}.  @xref{Query Before Exit}.
560  @end deffn  @end deffn
561    
562  @defun process-list  @defun process-list
# Line 594  process is started and remains constant Line 608  process is started and remains constant
608  This function returns the name of @var{process}.  This function returns the name of @var{process}.
609  @end defun  @end defun
610    
 @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  
   
611  @defun process-status process-name  @defun process-status process-name
612  This function returns the status of @var{process-name} as a symbol.  This function returns the status of @var{process-name} as a symbol.
613  The argument @var{process-name} must be a process, a buffer, a  The argument @var{process-name} must be a process, a buffer, a
# Line 622  for a network connection that is open. Line 630  for a network connection that is open.
630  for a network connection that is closed.  Once a connection  for a network connection that is closed.  Once a connection
631  is closed, you cannot reopen it, though you might be able to open  is closed, you cannot reopen it, though you might be able to open
632  a new connection to the same place.  a new connection to the same place.
633    @item connect
634    for a non-blocking connection that is waiting to complete.
635    @item failed
636    for a non-blocking connection that has failed to complete.
637    @item listen
638    for a network server that is listening.
639  @item nil  @item nil
640  if @var{process-name} is not the name of an existing process.  if @var{process-name} is not the name of an existing process.
641  @end table  @end table
# Line 679  decode subprocess output, and @var{encod Line 693  decode subprocess output, and @var{encod
693  input.  input.
694  @end defun  @end defun
695    
696      Every process also has a property list that you can use to store
697    miscellaneous values associated with the process.
698    
699    @defun process-get process propname
700    This function returns the value of the @var{propname} property
701    of @var{process}.
702    @end defun
703    
704    @defun process-put process propname value
705    This function sets the value of the @var{propname} property
706    of @var{process} to @var{value}.
707    @end defun
708    
709    @defun process-plist process
710    This function returns the process plist of @var{process}.
711    @end defun
712    
713    @defun set-process-plist process plist
714    This function sets the process plist of @var{process} to @var{plist}.
715    @end defun
716    
717  @node Input to Processes  @node Input to Processes
718  @section Sending Input to Processes  @section Sending Input to Processes
719  @cindex process input  @cindex process input
# Line 859  stopped previously. Line 894  stopped previously.
894  @end defun  @end defun
895    
896  @c Emacs 19 feature  @c Emacs 19 feature
897  @defun signal-process pid signal  @defun signal-process process signal
898  This function sends a signal to process @var{pid}, which need not be  This function sends a signal to process @var{process}.  The argument
899  a child of Emacs.  The argument @var{signal} specifies which signal  @var{signal} specifies which signal to send; it should be an integer.
900  to send; it should be an integer.  
901    You can specify the target process by its process @sc{id}; that allows
902    you to send signals to processes that are not children of Emacs.
903  @end defun  @end defun
904    
905  @node Output from Processes  @node Output from Processes
# Line 1437  Transaction queues are implemented by me Line 1474  Transaction queues are implemented by me
1474  @cindex network connection  @cindex network connection
1475  @cindex TCP  @cindex TCP
1476    
1477    Emacs Lisp programs can open TCP network connections to other processes on    Emacs Lisp programs can open TCP and datagram network connections to
1478  the same machine or other machines.  A network connection is handled by Lisp  other processes on the same machine or other machines.  A network
1479  much like a subprocess, and is represented by a process object.  connection is handled by Lisp much like a subprocess, and is
1480  However, the process you are communicating with is not a child of the  represented by a process object.  However, the process you are
1481  Emacs process, so you can't kill it or send it signals.  All you can do  communicating with is not a child of the Emacs process, so it has no
1482  is send and receive data.  @code{delete-process} closes the connection,  process @sc{id}, and you can't kill it or send it signals.  All you
1483  but does not kill the process at the other end; that process must decide  can do is send and receive data.  @code{delete-process} closes the
1484  what to do about closure of the connection.  connection, but does not kill the program at the other end; that
1485    program must decide what to do about closure of the connection.
1486    
1487      Lisp programs can listen for connections by creating network
1488    servers.  A network server is also represented by a kind of process
1489    object, but unlike a network connection, the network server never
1490    transfers data itself.  When it receives a connection request, it
1491    creates a new network connection to represent the connection just
1492    made.  (The network connection inherits certain information, including
1493    the process plist, from the server.)  The network server then goes
1494    back to listening for more connection requests.
1495    
1496    You can distinguish process objects representing network connections    You can distinguish process objects representing network connections
1497  from those representing subprocesses with the @code{process-status}  and servers from those representing subprocesses with the
1498  function.  It always returns either @code{open} or @code{closed} for a  @code{process-status} function.  The possible status values for
1499  network connection, and it never returns either of those values for a  network connections are @code{open}, @code{closed}, @code{connect},
1500  real subprocess.  @xref{Process Information}.  and @code{failed}.  For a network server, the status is always
1501    @code{listen}.  None of those values is possible for a real
1502    subprocess.  @xref{Process Information}.
1503    
1504      You can stop and resume operation of a network processes by calling
1505    @code{stop-process} and @code{continue-process}.  For a server
1506    process, being stopped means not accepting new connections.  (Up to 5
1507    connection requests will be queued for when you resume the server;
1508    this limit is imposed by the operating system.)  For a network
1509    connection, being stopped means not processing input (any arriving
1510    input waits until you resume the connection).  You can use the
1511    function @code{process-command} to determine whether a network
1512    connection or server is stopped; a non-@code{nil} value means yes.
1513    
1514  @defun open-network-stream name buffer-or-name host service  @defun open-network-stream name buffer-or-name host service
1515  This function opens a TCP connection for a service to a host.  It  This function opens a TCP connection, and returns a process object
1516  returns a process object to represent the connection.  that represents the connection.
1517    
1518  The @var{name} argument specifies the name for the process object.  It  The @var{name} argument specifies the name for the process object.  It
1519  is modified as necessary to make it unique.  is modified as necessary to make it unique.
# Line 1470  The arguments @var{host} and @var{servic Line 1529  The arguments @var{host} and @var{servic
1529  a defined network service (a string) or a port number (an integer).  a defined network service (a string) or a port number (an integer).
1530  @end defun  @end defun
1531    
1532    @defun open-network-stream-nowait name buffer-or-name host service &optional sentinel filter
1533    This function opens a TCP connection, like @code{open-network-stream},
1534    but it returns immediately without waiting for the request to be
1535    accepted or rejected by the remote server.  When the request is
1536    subsequently accepted or rejected, the process's sentinel function
1537    will be called with a string that starts with @code{"open"} (on
1538    success) or @code{"failed"} (on error).
1539    
1540    Some systems do not support non-blocking connections; on those
1541    systems, @code{open-network-stream-nowait} returns @code{nil}
1542    and does nothing.
1543    
1544    The optional arguments @var{sentinel} and @var{filter} specify the
1545    sentinel and filter functions for this network connection.  It is
1546    useful to specify them when opening the connection, because they will
1547    be used later asynchronously.  The other arguments mean the same as in
1548    @code{open-network-stream}.
1549    @end defun
1550    
1551    @defun process-contact process &optional key
1552    This function returns information about how a network process was set
1553    up.  For a connection, when @var{key} is @code{nil}, it returns
1554    @code{(@var{hostname} @var{service})} which specifies what you
1555    connected to.
1556    
1557    If @var{key} is @code{t}, the value is the complete status information
1558    for the connection or server; that is, the list of keywords and values
1559    specified in @code{make-network-process}, except that some of the
1560    values represent the current status instead of what you specified:
1561    
1562    @table @code
1563    @item :buffer
1564    The associated value is the process buffer.
1565    @item :filter
1566    The associated value is the process filter function.
1567    @item :sentinel
1568    The associated value is the process filter function.
1569    @item :remote
1570    In a connection, this is the address in internal format of the remote peer.
1571    @item :local
1572    The local address, in internal format.
1573    @item :service
1574    In a server, if you specified @code{t} for @var{service},
1575    this value is the actual port number.
1576    @end table
1577    
1578    @code{:local} and @code{:remote} are included even if they were not
1579    specified explicitly in @code{make-network-process}.
1580    
1581    If @var{key} is a keyword, the function returns the value corresponding
1582    to that keyword.
1583    
1584    For an ordinary child process, this function always returns @code{t}.
1585    @end defun
1586    
1587    @node Network Servers
1588    @section Network Servers
1589    
1590      You create a server by calling @code{make-network-process} with
1591    @code{:server t}.  The server will listen for connection requests from
1592    clients.  When it accepts a client connection request, that creates a
1593    new network connection, itself a process object, with the following
1594    parameters:
1595    
1596    @itemize @bullet
1597    @item
1598    The connection's process name is constructed by concatenating the
1599    server process' @var{name} with a client identification string.  The
1600    client identification string for an IPv4 connection looks like
1601    @samp{<@var{a}.@var{b}.@var{c}.@var{d}:@var{p}>}.  Otherwise, it is a
1602    unique number in brackets, as in @samp{<@var{nnn>}}.  The number
1603    is unique for each connection in the Emacs session.
1604    
1605    @item
1606    If the server's filter is non-@code{nil}, the connection process does
1607    not get a separate process buffer; otherwise, Emacs creates a bew
1608    buffer for the purpose.  The buffer name is the server's buffer name
1609    or process name, concatenated with the client identification string.
1610    
1611    The server's process buffer value is never used directly by Emacs, but
1612    it is passed to the log function, which can log connections by
1613    inserting text there.
1614    
1615    @item
1616    The communication type and the process filter and sentinel are
1617    inherited from those of the server.  The server never directly
1618    uses its filter and sentinel; their sole purpose is to initialize
1619    connections made to the server.
1620    
1621    @item
1622    The connection's process contact info is set according to the client's
1623    addressing information (typically an IP address and a port number).
1624    This information is associated with the @code{process-contact}
1625    keywords @code{:host}, @code{:service}, @code{:remote}.
1626    
1627    @item
1628    The connection's local address is set up according to the port
1629    number used for the connection.
1630    
1631    @item
1632    The client process' plist is initialized from the server's plist.
1633    @end itemize
1634    
1635    @defun open-network-stream-server name buffer-or-name service &optional sentinel filter
1636    Create a network server process for a TCP service.
1637    It returns nil if server processes are not supported; otherwise,
1638    it returns a subprocess-object to represent the server.
1639    
1640    When a client connects to the specified service, Emacs creates a new
1641    subprocess to handle the new connection, and then calls its sentinel
1642    function (which it has inherited from the server).
1643    
1644    The optional arguments @var{sentinel} and @var{filter} specify the
1645    sentinel and filter functions for the server.  It is useful to specify
1646    them now, because they will be used later asynchronously when the
1647    server receives a connection request.  The three arguments @var{name},
1648    @var{buffer-or-name} and @var{service} mean the same thing as in
1649    @code{open-network-stream}, but @var{service} can be @code{t}
1650    meaning ask the system to allocate an unused port to listen on.
1651    @end defun
1652    
1653    @node Datagrams
1654    @section Datagrams
1655    @cindex datagrams
1656    
1657      A datagram connection communicates with individual packets
1658    rather than streams of data.  Each call to @code{process-send}
1659    sends one datagram packet, and each datagram received results
1660    in one call to the filter function.
1661    
1662      The datagram connection doesn't have to talk with the same remote
1663    peer all the time.  It has a @dfn{remote peer address} which specifies
1664    where to send datagrams to.  Each time an incoming datagram is passed
1665    to the filter function, the peer address is set to the address that
1666    datagram came from; that way, if the filter function sends a datagram,
1667    it will go back to that place.  You can specify the remote peer
1668    address when you create the datagram connection using the
1669    @code{:remote} keyword.  You can change it later on by calling
1670    @code{set-process-datagram-address}.
1671    
1672    @defun process-datagram-address process
1673    If @var{process} is a datagram connection or server, this function
1674    returns its remote peer address.
1675    @end defun
1676    
1677    @defun set-process-datagram-address process address
1678    If @var{process} is a datagram connection or server, this function
1679    sets its remote peer address to @var{address}.
1680    @end defun
1681    
1682    @node Low-Level Network
1683    @section Low-Level Network Access
1684    
1685       The basic function for creating network connections and network
1686    servers is @code{make-network-process}.  It can do either of those
1687    jobs, depending on the arguments you give it.
1688    
1689    @defun make-network-process &rest args
1690    This function creates a network connection or server and returns the
1691    process object that represents it.  The arguments @var{args} are a
1692    list of keyword/argument pairs.  Omitting a keyword is always
1693    equivalent to specifying it with value @code{nil}, except for
1694    @code{:coding} and @code{:filter-multibyte}.  Here are the meaningful
1695    keywords:
1696    
1697    @table @asis
1698    @item :name name
1699    Use the string @var{name} as the process name.  It is modified if
1700    necessary to make it unique.
1701    
1702    @item :type @var{type}
1703    Specify the communication type.  A value of @code{nil} specifies a
1704    stream connection (the default); @code{datagram} specifies a datagram
1705    connection.  Both connections and servers can be of either type.
1706    
1707    @item :server @var{server-flag}
1708    If @var{server-flag} is non-@code{nil}, create a server.  Otherwise,
1709    create a connection.
1710    
1711    @item :host @var{host}
1712    Specify the host to connect to.  @var{host} should be a host name or
1713    internet address, as a string, or the symbol @code{local} to specify
1714    the local host.  If you specify @var{host} for a server, it must
1715    specify a valid address for the local host, and only clients
1716    connecting to that address will be accepted.
1717    
1718    @item :service @var{service}
1719    @var{service} specifies a port number to connect to, or, for a server,
1720    the port number to listen on.  It should be a service name that
1721    translates to a port number, or an integer specifying the port number
1722    directly.  For a server, it can also be @code{t}, which means to let
1723    the system select an unused port number.
1724    
1725    @item :family @var{family}
1726    @var{family} specifies the address (and protocol) family for
1727    communication.  @code{nil} stands for IPv4.  @code{local} specifies a
1728    Unix socket, in which case @var{host} is ignored.
1729    
1730    @item :local @var{local-address}
1731    For a server process, @var{local-address} is the address to listen on.
1732    It overrides @var{family}, @var{host} and @var{service}, and you
1733    may as well not specify them.
1734    
1735    @item :remote @var{remote-address}
1736    For a connection, @var{remote-address} is the address to connect to.
1737    It overrides @var{family}, @var{host} and @var{service}, and you
1738    may as well not specify them.
1739    
1740    For a datagram server, @var{remote-address} specifies the initial
1741    setting of the remote datagram address.
1742    
1743    The format of @var{local-address} or @var{remote-address} depends on
1744    the address family:
1745    
1746    @itemize -
1747    @item
1748    An IPv4 address is represented as a vector of integers @code{[@var{a}
1749    @var{b} @var{c} @var{d} @var{p}]} corresponding to numeric IP address
1750    @var{a}.@var{b}.@var{c}.@var{d} and port number @var{p}.
1751    
1752    @item
1753    A local address is represented as a string which specifies the address
1754    in the local address space.
1755    
1756    @item
1757    An ``unsupported family'' address is represented by a cons
1758    @code{(@var{f} . @var{av})}, where @var{f} is the family number and
1759    @var{av} is a vector specifying the socket address using with one
1760    element per address data byte.  Do not rely on this format in portable
1761    code, as it may depend on implementation defined constants, data
1762    sizes, and data structure alignment.
1763    @end itemize
1764    
1765    @item :nowait @var{bool}
1766    If @var{bool} is non-@code{nil} for a stream connection, return
1767    without waiting for the connection to complete.  When the connection
1768    succeeds or fails, Emacs will call the sentinel function, with a
1769    second argument matching @code{"open"} (if successful) or
1770    @code{"failed"}.  The default is to block, so that
1771    @code{make-network-process} does not return until the connection
1772    has succeeded or failed.
1773    
1774    @item :stop @var{stopped}
1775    Start the network connection or server in the `stopped' state if
1776    @var{stopped} is non-@code{nil}.
1777    
1778    @item :buffer @var{buffer}
1779    Use @var{buffer} as the process buffer.
1780    
1781    @item :coding @var{coding}
1782    Use @var{coding} as the coding system for this process.  To specify
1783    different coding systems for decoding data from the connection and for
1784    encoding data sent to it, specify @code{(@var{decoding} .
1785    @var{encoding})} for @var{coding}.
1786    
1787    If you don't specify this keyword at all, the default
1788    is to determine the coding systemx from the data.
1789    
1790    @item :options @var{options}
1791    Set the specified options for the network process.  See
1792    @code{set-network-process-options} for details.
1793    
1794    @item :noquery @var{query-flag}
1795    Initialize the process query flag to @var{query-flag}.
1796    
1797    @item :filter @var{filter}
1798    Initialize the process filter to @var{filter}.
1799    
1800    @item :filter-multibyte @var{bool}
1801    If @var{bool} is non-@code{nil}, strings given to the process filter
1802    are multibyte, otherwise they are unibyte.  If you don't specify this
1803    keyword at all, the default is that the strings are multibyte if
1804    @code{default-enable-multibyte-characters} is non-@code{nil}.
1805    
1806    @item :sentinel @var{sentinel}
1807    Initialize the process sentinel to @var{sentinel}.
1808    
1809    @item :log @var{log}
1810    Initialize the log function of a server process to @var{log}.  The log
1811    function is called each time the server accepts a network connection
1812    from a client.  The arguments passed to the log function are
1813    @var{server}, @var{connection}, and @var{message}, where @var{server}
1814    is the server process, @var{connection} is the new process for the
1815    connection, and @var{message} is a string describing what has
1816    happened.
1817    
1818    @item :plist @var{plist}
1819    Initialize the process plist to @var{plist}.
1820    @end table
1821    
1822    The original argument list, modified with the actual connection
1823    information, is available via the `process-contact' function.
1824    @end defun
1825    
1826    @defun network-interface-list
1827    This function returns a list describing the network interfaces
1828    of the machine you are using.  The value is an alist whose
1829    elements have the form @code{(@var{name} . @var{address})}.
1830    @var{address} has the same form as the @var{local-address}
1831    and @var{remote-address} arguments to @code{make-network-process}.
1832    @end defun
1833    
1834    @defun network-interface-info ifname
1835    This function returns information about the network interface named
1836    @var{ifname}.  The value is a list of the form @code{(@var{addr} @var{bcast} @var{netmask} @var{hwaddr} @var{flags})}.
1837    
1838    @table @var
1839    @item addr
1840    The internet protocol address.
1841    @item bcast
1842    The broadcast address.
1843    @item netmask
1844    The network mask.
1845    @item hwaddr
1846    The layer 2 address (Ethernet MAC address, for instance).
1847    @item flags
1848    The current flags of the interface.
1849    @end table
1850    @end defun
1851    
1852    @defun format-network-address address &optional omit-port
1853    This function converts the lisp representation of a network address to
1854    a string.  For example, a five-element vector @code{[@var{a} @var{b}
1855    @var{c} @var{d} @var{p}]} represents an IP address
1856    @var{a}.@var{b}.@var{c}.@var{d} and port number @var{p}.
1857    @code{format-network-address} converts that to the string
1858    @code{"@var{a}.@var{b}.@var{c}.@var{d}:@var{p}"}.
1859    
1860    If @var{omit-port} is non-@code{nil}, the value does not include
1861    the port number.
1862    @end defun
1863    
1864      To test for the availability of a given network feature, use
1865    @code{featurep} like this:
1866    
1867    @example
1868    (featurep 'make-network-process '(@var{keyword} @var{value}))
1869    @end example
1870    
1871    @noindent
1872    The result is @code{t} if it works to specify @var{keyword} with value
1873    @var{value} in @code{make-network-process}.  Here are some of the
1874    @var{keyword}---@var{value} pairs you can test in this way.
1875    
1876    @table @code
1877    @item (:nowait t)
1878    Non-@code{nil} if non-blocking connect is supported.
1879    @item (:type datagram)
1880    Non-@code{nil} if datagrams are supported.
1881    @item (:family local)
1882    Non-@code{nil} if local (aka ``UNIX domain'') sockets are supported.
1883    @item (:service t)
1884    Non-@code{nil} if the system can select the port for a server.
1885    @item (:options bindtodevice)
1886    @itemx (:options broadcast)
1887    @itemx (:options dontroute)
1888    @itemx (:options keepalive)
1889    @itemx (:options linger)
1890    @itemx (:options oobinline)
1891    @itemx (:options priority)
1892    @itemx (:options reuseaddr)
1893    That particular socket option is supported.
1894    @end table
1895    
1896  @ignore  @ignore
1897     arch-tag: ba9da253-e65f-4e7f-b727-08fba0a1df7a     arch-tag: ba9da253-e65f-4e7f-b727-08fba0a1df7a
1898  @end ignore  @end ignore
1899    

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

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