/[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.26.2.1 by miles, Fri Apr 4 06:20:42 2003 UTC revision 1.26.2.2 by miles, Tue Oct 14 23:10:12 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 79  in @code{exec-path}, but environment var Line 83  in @code{exec-path}, but environment var
83  @code{substitute-in-file-name} to perform them (@pxref{File Name  @code{substitute-in-file-name} to perform them (@pxref{File Name
84  Expansion}).  Expansion}).
85    
86      Executing a program can also try adding suffixes to the specified
87    name:
88    
89    @defvar exec-suffixes
90    This variable is a list of suffixes (strings) to try adding to the
91    specified program file name.  The list should include @code{""} if you
92    want the name to be tried exactly as specified.  The default value is
93    system-dependent.
94    @end defvar
95    
96    Each of the subprocess-creating functions has a @var{buffer-or-name}    Each of the subprocess-creating functions has a @var{buffer-or-name}
97  argument which specifies where the standard output from the program will  argument which specifies where the standard output from the program will
98  go.  It should be a buffer or a buffer name; if it is a buffer name,  go.  It should be a buffer or a buffer name; if it is a buffer name,
# Line 366  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 529  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 584  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 612  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 669  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 849  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 888  you want to keep the output to those str Line 935  you want to keep the output to those str
935  redirect one of them to a file--for example, by using an appropriate  redirect one of them to a file--for example, by using an appropriate
936  shell command.  shell command.
937    
   Subprocess output is normally decoded using a coding system before the  
 buffer or filter function receives it, much like text read from a file.  
 You can use @code{set-process-coding-system} to specify which coding  
 system to use (@pxref{Process Information}).  Otherwise, the coding  
 system comes from @code{coding-system-for-read}, if that is  
 non-@code{nil}; or else from the defaulting mechanism (@pxref{Default  
 Coding Systems}).  
   
   @strong{Warning:} Coding systems such as @code{undecided} which  
 determine the coding system from the data do not work entirely reliably  
 with asynchronous subprocess output.  This is because Emacs has to  
 process asynchronous subprocess output in batches, as it arrives.  Emacs  
 must try to detect the proper coding system from one batch at a time,  
 and this does not always work.  Therefore, if at all possible, use a  
 coding system which determines both the character code conversion and  
 the end of line conversion---that is, one like @code{latin-1-unix},  
 rather than @code{undecided} or @code{latin-1}.  
   
938  @menu  @menu
939  * Process Buffers::       If no filter, output is put in a buffer.  * Process Buffers::         If no filter, output is put in a buffer.
940  * Filter Functions::      Filter functions accept output from the process.  * Filter Functions::        Filter functions accept output from the process.
941  * Accepting Output::      Explicitly permitting subprocess output.  * Decoding Output::         Filters can get unibyte or multibyte strings.
942                              Waiting for subprocess output.  * Accepting Output::        How to wait until process output arrives.
943  @end menu  @end menu
944    
945  @node Process Buffers  @node Process Buffers
# Line 1152  there is no filter function: Line 1181  there is no filter function:
1181  @end smallexample  @end smallexample
1182  @end ignore  @end ignore
1183    
1184    @node Decoding Output
1185    @subsection Decoding Process Output
1186    
1187      When Emacs writes process output directly into a multibyte buffer,
1188    it decodes the output according to the process output coding system.
1189    If the coding system is @code{raw-text} or @code{no-conversion}, Emacs
1190    converts the unibyte output to multibyte using
1191    @code{string-to-multibyte}, inserts the resulting multibyte text.
1192    
1193      You can use @code{set-process-coding-system} to specify which coding
1194    system to use (@pxref{Process Information}).  Otherwise, the coding
1195    system comes from @code{coding-system-for-read}, if that is
1196    non-@code{nil}; or else from the defaulting mechanism (@pxref{Default
1197    Coding Systems}).
1198    
1199      @strong{Warning:} Coding systems such as @code{undecided} which
1200    determine the coding system from the data do not work entirely
1201    reliably with asynchronous subprocess output.  This is because Emacs
1202    has to process asynchronous subprocess output in batches, as it
1203    arrives.  Emacs must try to detect the proper coding system from one
1204    batch at a time, and this does not always work.  Therefore, if at all
1205    possible, specify a coding system that determines both the character
1206    code conversion and the end of line conversion---that is, one like
1207    @code{latin-1-unix}, rather than @code{undecided} or @code{latin-1}.
1208    
1209    @cindex filter multibyte flag, of process
1210    @cindex process filter multibyte flag
1211      When Emacs calls a process filter function, it provides the process
1212    output as a multibyte string or as a unibyte string according to the
1213    process's filter multibyte flag.  If the flag is non-@code{nil}, Emacs
1214    decodes the output according to the process output coding system to
1215    produce a multibyte string, and passes that to the process.  If the
1216    flag is @code{nil}, Emacs puts the output into a unibyte string, with
1217    no decoding, and passes that.
1218    
1219      When you create a process, the filter multibyte flag takes its
1220    initial value from @code{default-enable-multibyte-characters}.  If you
1221    want to change the flag later on, use
1222    @code{set-process-filter-multibyte}.
1223    
1224    @defun set-process-filter-multibyte process multibyte
1225    This function sets the filter multibyte flag of @var{process}
1226    to @var{multibyte}.
1227    @end defun
1228    
1229    @defun process-filter-multibyte-p process
1230    This function returns the filter multibyte flag of @var{process}.
1231    @end defun
1232    
1233  @node Accepting Output  @node Accepting Output
1234  @subsection Accepting Output from Processes  @subsection Accepting Output from Processes
1235    
# Line 1395  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 network connections to other processes on    Emacs Lisp programs can open stream (TCP) and datagram (UDP) network
1479  the same machine or other machines.  A network connection is handled by Lisp  connections to other processes on the same machine or other machines.
1480  much like a subprocess, and is represented by a process object.  A network connection is handled by Lisp much like a subprocess, and is
1481  However, the process you are communicating with is not a child of the  represented by a process object.  However, the process you are
1482  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
1483  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
1484  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
1485  what to do about closure of the connection.  connection, but does not kill the program at the other end; that
1486    program must decide what to do about closure of the connection.
1487    
1488      Lisp programs can listen for connections by creating network
1489    servers.  A network server is also represented by a kind of process
1490    object, but unlike a network connection, the network server never
1491    transfers data itself.  When it receives a connection request, it
1492    creates a new network connection to represent the connection just
1493    made.  (The network connection inherits certain information, including
1494    the process plist, from the server.)  The network server then goes
1495    back to listening for more connection requests.
1496    
1497      Network connections and servers are created by calling
1498    @code{make-network-process} with an argument list consisting of
1499    keyword/argument pairs, for example @code{:server t} to create a
1500    server process, or @code{:type 'datagram} to create a datagram
1501    connection.  @xref{Low-Level Network}, for details.  You can also use
1502    one of the @code{open-network-...} functions descibed below;
1503    internally, they just call @code{make-network-process} with suitable
1504    arguments.
1505    
1506    You can distinguish process objects representing network connections    You can distinguish process objects representing network connections
1507  from those representing subprocesses with the @code{process-status}  and servers from those representing subprocesses with the
1508  function.  It always returns either @code{open} or @code{closed} for a  @code{process-status} function.  The possible status values for
1509  network connection, and it never returns either of those values for a  network connections are @code{open}, @code{closed}, @code{connect},
1510  real subprocess.  @xref{Process Information}.  and @code{failed}.  For a network server, the status is always
1511    @code{listen}.  None of those values is possible for a real
1512    subprocess.  @xref{Process Information}.
1513    
1514      You can stop and resume operation of a network processes by calling
1515    @code{stop-process} and @code{continue-process}.  For a server
1516    process, being stopped means not accepting new connections.  (Up to 5
1517    connection requests will be queued for when you resume the server; you
1518    can increase this limit, unless it is imposed by the operating
1519    systems.)  For a network stream connection, being stopped means not
1520    processing input (any arriving input waits until you resume the
1521    connection).  For a datagram connection, some number of packets may be
1522    queued but input may be lost.  You can use the function
1523    @code{process-command} to determine whether a network connection or
1524    server is stopped; a non-@code{nil} value means yes.
1525    
1526  @defun open-network-stream name buffer-or-name host service  @defun open-network-stream name buffer-or-name host service
1527  This function opens a TCP connection for a service to a host.  It  This function opens a TCP connection, and returns a process object
1528  returns a process object to represent the connection.  that represents the connection.
1529    
1530  The @var{name} argument specifies the name for the process object.  It  The @var{name} argument specifies the name for the process object.  It
1531  is modified as necessary to make it unique.  is modified as necessary to make it unique.
# Line 1428  The arguments @var{host} and @var{servic Line 1540  The arguments @var{host} and @var{servic
1540  @var{host} is the host name (a string), and @var{service} is the name of  @var{host} is the host name (a string), and @var{service} is the name of
1541  a defined network service (a string) or a port number (an integer).  a defined network service (a string) or a port number (an integer).
1542  @end defun  @end defun
1543    
1544    @defun open-network-stream-nowait name buffer-or-name host service &optional sentinel filter
1545    This function opens a TCP connection, like @code{open-network-stream},
1546    but it returns immediately without waiting for the request to be
1547    accepted or rejected by the remote server.  When the request is
1548    subsequently accepted or rejected, the process's sentinel function
1549    will be called with a string that starts with @code{"open"} (on
1550    success) or @code{"failed"} (on error).
1551    
1552    Some systems do not support non-blocking connections; on those
1553    systems, @code{open-network-stream-nowait} returns @code{nil}
1554    and does nothing.
1555    
1556    The optional arguments @var{sentinel} and @var{filter} specify the
1557    sentinel and filter functions for this network connection.  It is
1558    useful to specify them when opening the connection, because they will
1559    be used later asynchronously.  The other arguments mean the same as in
1560    @code{open-network-stream}.
1561    @end defun
1562    
1563    @defun process-contact process &optional key
1564    This function returns information about how a network process was set
1565    up.  For a connection, when @var{key} is @code{nil}, it returns
1566    @code{(@var{hostname} @var{service})} which specifies what you
1567    connected to.
1568    
1569    If @var{key} is @code{t}, the value is the complete status information
1570    for the connection or server; that is, the list of keywords and values
1571    specified in @code{make-network-process}, except that some of the
1572    values represent the current status instead of what you specified:
1573    
1574    @table @code
1575    @item :buffer
1576    The associated value is the process buffer.
1577    @item :filter
1578    The associated value is the process filter function.
1579    @item :sentinel
1580    The associated value is the process sentinel function.
1581    @item :remote
1582    In a connection, this is the address in internal format of the remote peer.
1583    @item :local
1584    The local address, in internal format.
1585    @item :service
1586    In a server, if you specified @code{t} for @var{service},
1587    this value is the actual port number.
1588    @end table
1589    
1590    @code{:local} and @code{:remote} are included even if they were not
1591    specified explicitly in @code{make-network-process}.
1592    
1593    If @var{key} is a keyword, the function returns the value corresponding
1594    to that keyword.
1595    
1596    For an ordinary child process, this function always returns @code{t}.
1597    @end defun
1598    
1599    @node Network Servers
1600    @section Network Servers
1601    
1602      You create a server by calling @code{make-network-process} with
1603    @code{:server t}.  The server will listen for connection requests from
1604    clients.  When it accepts a client connection request, that creates a
1605    new network connection, itself a process object, with the following
1606    parameters:
1607    
1608    @itemize @bullet
1609    @item
1610    The connection's process name is constructed by concatenating the
1611    server process' @var{name} with a client identification string.  The
1612    client identification string for an IPv4 connection looks like
1613    @samp{<@var{a}.@var{b}.@var{c}.@var{d}:@var{p}>}.  Otherwise, it is a
1614    unique number in brackets, as in @samp{<@var{nnn}>}.  The number
1615    is unique for each connection in the Emacs session.
1616    
1617    @item
1618    If the server's filter is non-@code{nil}, the connection process does
1619    not get a separate process buffer; otherwise, Emacs creates a new
1620    buffer for the purpose.  The buffer name is the server's buffer name
1621    or process name, concatenated with the client identification string.
1622    
1623    The server's process buffer value is never used directly by Emacs, but
1624    it is passed to the log function, which can log connections by
1625    inserting text there.
1626    
1627    @item
1628    The communication type and the process filter and sentinel are
1629    inherited from those of the server.  The server never directly
1630    uses its filter and sentinel; their sole purpose is to initialize
1631    connections made to the server.
1632    
1633    @item
1634    The connection's process contact info is set according to the client's
1635    addressing information (typically an IP address and a port number).
1636    This information is associated with the @code{process-contact}
1637    keywords @code{:host}, @code{:service}, @code{:remote}.
1638    
1639    @item
1640    The connection's local address is set up according to the port
1641    number used for the connection.
1642    
1643    @item
1644    The client process' plist is initialized from the server's plist.
1645    @end itemize
1646    
1647    @defun open-network-stream-server name buffer-or-name service &optional sentinel filter
1648    Create a network server process for a TCP service.
1649    It returns nil if server processes are not supported; otherwise,
1650    it returns a subprocess-object to represent the server.
1651    
1652    When a client connects to the specified service, Emacs creates a new
1653    subprocess to handle the new connection, and then calls its sentinel
1654    function (which it has inherited from the server).
1655    
1656    The optional arguments @var{sentinel} and @var{filter} specify the
1657    sentinel and filter functions for the server.  It is useful to specify
1658    them now, because they will be used later asynchronously when the
1659    server receives a connection request.  The three arguments @var{name},
1660    @var{buffer-or-name} and @var{service} mean the same thing as in
1661    @code{open-network-stream}, but @var{service} can be @code{t}
1662    meaning ask the system to allocate an unused port to listen on.
1663    @end defun
1664    
1665    @node Datagrams
1666    @section Datagrams
1667    @cindex datagrams
1668    
1669      A datagram connection communicates with individual packets
1670    rather than streams of data.  Each call to @code{process-send}
1671    sends one datagram packet, and each datagram received results
1672    in one call to the filter function.
1673    
1674      The datagram connection doesn't have to talk with the same remote
1675    peer all the time.  It has a @dfn{remote peer address} which specifies
1676    where to send datagrams to.  Each time an incoming datagram is passed
1677    to the filter function, the peer address is set to the address that
1678    datagram came from; that way, if the filter function sends a datagram,
1679    it will go back to that place.  You can specify the remote peer
1680    address when you create the datagram connection using the
1681    @code{:remote} keyword.  You can change it later on by calling
1682    @code{set-process-datagram-address}.
1683    
1684    @defun process-datagram-address process
1685    If @var{process} is a datagram connection or server, this function
1686    returns its remote peer address.
1687    @end defun
1688    
1689    @defun set-process-datagram-address process address
1690    If @var{process} is a datagram connection or server, this function
1691    sets its remote peer address to @var{address}.
1692    @end defun
1693    
1694    @node Low-Level Network
1695    @section Low-Level Network Access
1696    
1697       The basic function for creating network connections and network
1698    servers is @code{make-network-process}.  It can do either of those
1699    jobs, depending on the arguments you give it.
1700    
1701    @defun make-network-process &rest args
1702    This function creates a network connection or server and returns the
1703    process object that represents it.  The arguments @var{args} are a
1704    list of keyword/argument pairs.  Omitting a keyword is always
1705    equivalent to specifying it with value @code{nil}, except for
1706    @code{:coding}, @code{:filter-multibyte}, and @code{:reuseaddr}.  Here
1707    are the meaningful keywords:
1708    
1709    @table @asis
1710    @item :name name
1711    Use the string @var{name} as the process name.  It is modified if
1712    necessary to make it unique.
1713    
1714    @item :type @var{type}
1715    Specify the communication type.  A value of @code{nil} specifies a
1716    stream connection (the default); @code{datagram} specifies a datagram
1717    connection.  Both connections and servers can be of either type.
1718    
1719    @item :server @var{server-flag}
1720    If @var{server-flag} is non-@code{nil}, create a server.  Otherwise,
1721    create a connection.  For a stream type server, @var{server-flag} may
1722    be an integer which then specifies the length of the queue of pending
1723    connections to the server.  The default queue length is 5.
1724    
1725    @item :host @var{host}
1726    Specify the host to connect to.  @var{host} should be a host name or
1727    internet address, as a string, or the symbol @code{local} to specify
1728    the local host.  If you specify @var{host} for a server, it must
1729    specify a valid address for the local host, and only clients
1730    connecting to that address will be accepted.
1731    
1732    @item :service @var{service}
1733    @var{service} specifies a port number to connect to, or, for a server,
1734    the port number to listen on.  It should be a service name that
1735    translates to a port number, or an integer specifying the port number
1736    directly.  For a server, it can also be @code{t}, which means to let
1737    the system select an unused port number.
1738    
1739    @item :family @var{family}
1740    @var{family} specifies the address (and protocol) family for
1741    communication.  @code{nil} stands for IPv4.  @code{local} specifies a
1742    Unix socket, in which case @var{host} is ignored.
1743    
1744    @item :local @var{local-address}
1745    For a server process, @var{local-address} is the address to listen on.
1746    It overrides @var{family}, @var{host} and @var{service}, and you
1747    may as well not specify them.
1748    
1749    @item :remote @var{remote-address}
1750    For a connection, @var{remote-address} is the address to connect to.
1751    It overrides @var{family}, @var{host} and @var{service}, and you
1752    may as well not specify them.
1753    
1754    For a datagram server, @var{remote-address} specifies the initial
1755    setting of the remote datagram address.
1756    
1757    The format of @var{local-address} or @var{remote-address} depends on
1758    the address family:
1759    
1760    @itemize -
1761    @item
1762    An IPv4 address is represented as a vector of integers @code{[@var{a}
1763    @var{b} @var{c} @var{d} @var{p}]} corresponding to numeric IP address
1764    @var{a}.@var{b}.@var{c}.@var{d} and port number @var{p}.
1765    
1766    @item
1767    A local address is represented as a string which specifies the address
1768    in the local address space.
1769    
1770    @item
1771    An ``unsupported family'' address is represented by a cons
1772    @code{(@var{f} . @var{av})}, where @var{f} is the family number and
1773    @var{av} is a vector specifying the socket address using with one
1774    element per address data byte.  Do not rely on this format in portable
1775    code, as it may depend on implementation defined constants, data
1776    sizes, and data structure alignment.
1777    @end itemize
1778    
1779    @item :nowait @var{bool}
1780    If @var{bool} is non-@code{nil} for a stream connection, return
1781    without waiting for the connection to complete.  When the connection
1782    succeeds or fails, Emacs will call the sentinel function, with a
1783    second argument matching @code{"open"} (if successful) or
1784    @code{"failed"}.  The default is to block, so that
1785    @code{make-network-process} does not return until the connection
1786    has succeeded or failed.
1787    
1788    @item :stop @var{stopped}
1789    Start the network connection or server in the `stopped' state if
1790    @var{stopped} is non-@code{nil}.
1791    
1792    @item :buffer @var{buffer}
1793    Use @var{buffer} as the process buffer.
1794    
1795    @item :coding @var{coding}
1796    Use @var{coding} as the coding system for this process.  To specify
1797    different coding systems for decoding data from the connection and for
1798    encoding data sent to it, specify @code{(@var{decoding} .
1799    @var{encoding})} for @var{coding}.
1800    
1801    If you don't specify this keyword at all, the default
1802    is to determine the coding systems from the data.
1803    
1804    @item :noquery @var{query-flag}
1805    Initialize the process query flag to @var{query-flag}.  @xref{Query Before Exit}.
1806    
1807    @item :filter @var{filter}
1808    Initialize the process filter to @var{filter}.
1809    
1810    @item :filter-multibyte @var{bool}
1811    If @var{bool} is non-@code{nil}, strings given to the process filter
1812    are multibyte, otherwise they are unibyte.  If you don't specify this
1813    keyword at all, the default is that the strings are multibyte if
1814    @code{default-enable-multibyte-characters} is non-@code{nil}.
1815    
1816    @item :sentinel @var{sentinel}
1817    Initialize the process sentinel to @var{sentinel}.
1818    
1819    @item :log @var{log}
1820    Initialize the log function of a server process to @var{log}.  The log
1821    function is called each time the server accepts a network connection
1822    from a client.  The arguments passed to the log function are
1823    @var{server}, @var{connection}, and @var{message}, where @var{server}
1824    is the server process, @var{connection} is the new process for the
1825    connection, and @var{message} is a string describing what has
1826    happened.
1827    
1828    @item :plist @var{plist}
1829    Initialize the process plist to @var{plist}.
1830    @end table
1831    
1832    The following network options can be specified for the network
1833    process.  Except for @code{:reuseaddr}, you can set or modify these
1834    options later using @code{set-network-process-option}.
1835    
1836    For a server process, the options specified with
1837    @code{make-network-process} are not inherited by the client
1838    connections, so you will need to set the necessary options for each
1839    child connection as they are created.
1840    
1841    @table @asis
1842    @item :bindtodevice @var{device-name}
1843    If @var{device-name} is a non-empty string identifying a network
1844    interface name (see @code{network-interface-list}), only handle
1845    packets received on that interface.  If @var{device-name} is nil (the
1846    default), handle packets received on any interface.
1847    
1848    Using this option may require special privileges on some systems.
1849    
1850    @item :broadcast @var{broadcast-flag}
1851    If @var{broadcast-flag} is non-@code{nil} for a datagram process, the
1852    process will receive datagram packet sent to a broadcast address, and
1853    be able to send packets to a broadcast address.  Ignored for a stream
1854    connection.
1855    
1856    @item :dontroute @var{dontroute-flag}
1857    If @var{dontroute-flag} is non-@code{nil}, the process can only send
1858    to hosts on the same network as the local host.
1859    
1860    @item :keepalive @var{keepalive-flag}
1861    If @var{keepalive-flag} is non-@code{nil} for a stream connection,
1862    enable exchange of low-level keep-alive messa
1863    
1864    @item :linger @var{linger-arg}
1865    If @var{linger-arg} is non-@code{nil}, wait for successful
1866    transmission of all queued packets on the connection before it is
1867    deleted (see @code{delete-process}).  If @var{linger-arg} is an
1868    integer, it specifies the maximum time in seconds to wait for queued
1869    packets to be sent before closing the connection.  Default is
1870    @code{nil} which means to discard unsent queued packets when the
1871    process is deleted.
1872    
1873    @item :oobinline @var{oobinline-flag}
1874    If @var{oobinline-flag} is non-@code{nil} for a stream connection,
1875    receive out-of-band data in the normal data stream.  Otherwise, ignore
1876    out-of-band data.
1877    
1878    @item :priority @var{priority}
1879    Set the priority for packets sent on this connection to the integer
1880    @var{priority}.  The interpretation of this number is protocol
1881    specific, such as setting the TOS (type of service) field on IP
1882    packets sent on this connection.  It may also have system dependent
1883    effects, such as selecting a specific output queue on the network
1884    interface.
1885    
1886    @item :reuseaddr @var{reuseaddr-flag}
1887    If @var{reuseaddr-flag} is non-@code{nil} (the default) for a stream
1888    server process, allow this server to reuse a specific port number (see
1889    @code{:service}) unless another process on this host is already
1890    listening on that port.  If @var{reuseaddr-flag} is @code{nil}, there
1891    may be a period of time after the last use of that port (by any
1892    process on the host), where it is not possible to make a new server on
1893    that port.
1894    
1895    @end table
1896    
1897    The original argument list, modified with the actual connection
1898    information, is available via the `process-contact' function.
1899    @end defun
1900    
1901    @defun set-network-process-option process option value
1902    This function sets or modifies a network option for network process
1903    @var{process}.  See @code{make-network-process} for details of options
1904    @var{option} and their corresponding values @var{value}.
1905    
1906    The current setting of an option is available via the
1907    `process-contact' function.
1908    @end defun
1909    
1910    @defun network-interface-list
1911    This function returns a list describing the network interfaces
1912    of the machine you are using.  The value is an alist whose
1913    elements have the form @code{(@var{name} . @var{address})}.
1914    @var{address} has the same form as the @var{local-address}
1915    and @var{remote-address} arguments to @code{make-network-process}.
1916    @end defun
1917    
1918    @defun network-interface-info ifname
1919    This function returns information about the network interface named
1920    @var{ifname}.  The value is a list of the form @code{(@var{addr} @var{bcast} @var{netmask} @var{hwaddr} @var{flags})}.
1921    
1922    @table @var
1923    @item addr
1924    The internet protocol address.
1925    @item bcast
1926    The broadcast address.
1927    @item netmask
1928    The network mask.
1929    @item hwaddr
1930    The layer 2 address (Ethernet MAC address, for instance).
1931    @item flags
1932    The current flags of the interface.
1933    @end table
1934    @end defun
1935    
1936    @defun format-network-address address &optional omit-port
1937    This function converts the Lisp representation of a network address to
1938    a string.  For example, a five-element vector @code{[@var{a} @var{b}
1939    @var{c} @var{d} @var{p}]} represents an IP address
1940    @var{a}.@var{b}.@var{c}.@var{d} and port number @var{p}.
1941    @code{format-network-address} converts that to the string
1942    @code{"@var{a}.@var{b}.@var{c}.@var{d}:@var{p}"}.
1943    
1944    If @var{omit-port} is non-@code{nil}, the value does not include
1945    the port number.
1946    @end defun
1947    
1948      To test for the availability of a given network feature, use
1949    @code{featurep} like this:
1950    
1951    @example
1952    (featurep 'make-network-process '(@var{keyword} @var{value}))
1953    @end example
1954    
1955    @noindent
1956    The result of the first form is @code{t} if it works to specify
1957    @var{keyword} with value @var{value} in @code{make-network-process}.
1958    The result of the second form is @code{t} if @var{keyword} is
1959    supported by @code{make-network-process}.  Here are some of the
1960    @var{keyword}---@var{value} pairs you can test in
1961    this way.
1962    
1963    @table @code
1964    @item (:nowait t)
1965    Non-@code{nil} if non-blocking connect is supported.
1966    @item (:type datagram)
1967    Non-@code{nil} if datagrams are supported.
1968    @item (:family local)
1969    Non-@code{nil} if local (aka ``UNIX domain'') sockets are supported.
1970    @item (:service t)
1971    Non-@code{nil} if the system can select the port for a server.
1972    @end table
1973    
1974      To test for the availability of a given network option, use
1975    @code{featurep} like this:
1976    
1977    @example
1978    (featurep 'make-network-process '@var{keyword})
1979    @end example
1980    
1981    Here are some of the option @var{keyword}s you can test in
1982    this way.
1983    
1984    @table @code
1985    @item :bindtodevice
1986    @itemx :broadcast
1987    @itemx :dontroute
1988    @itemx :keepalive
1989    @itemx :linger
1990    @itemx :oobinline
1991    @itemx :priority
1992    @itemx :reuseaddr
1993    That particular network option is supported by
1994    @code{make-network-process} and @code{set-network-process-option}.
1995    @end table
1996    
1997    @ignore
1998       arch-tag: ba9da253-e65f-4e7f-b727-08fba0a1df7a
1999    @end ignore
2000    

Legend:
Removed from v.1.26.2.1  
changed lines
  Added in v.1.26.2.2

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