X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/bb5d6d34377a2bcf28877ee572f44091ac0d31c5..fc634b385b55f396dac05ba8d394762ccb5a354d:/lispref/processes.texi diff --git a/lispref/processes.texi b/lispref/processes.texi index 35041677b8..44da398770 100644 --- a/lispref/processes.texi +++ b/lispref/processes.texi @@ -1,7 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999 -@c Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003, +@c 2004, 2005, 2006 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/processes @node Processes, Display, Abbrevs, Top @@ -49,9 +49,11 @@ This function returns @code{t} if @var{object} is a process, * Transaction Queues:: Transaction-based communication with subprocesses. * Network:: Opening network connections. * Network Servers:: Network servers let Emacs accept net connections. -* Datagrams:: +* Datagrams:: UDP network connections. * Low-Level Network:: Lower-level but more general function to create connections and servers. +* Misc Network:: Additional relevant functions for network connections. +* Byte Packing:: Using bindat to pack and unpack binary data. @end menu @node Subprocess Creation @@ -77,11 +79,12 @@ cannot be executed. If the file name is relative, the variable @code{exec-path} contains a list of directories to search. Emacs initializes @code{exec-path} when it starts up, based on the value of the environment variable @code{PATH}. The standard file name -constructs, @samp{~}, @samp{.}, and @samp{..}, are interpreted as usual -in @code{exec-path}, but environment variable substitutions +constructs, @samp{~}, @samp{.}, and @samp{..}, are interpreted as +usual in @code{exec-path}, but environment variable substitutions (@samp{$HOME}, etc.) are not recognized; use @code{substitute-in-file-name} to perform them (@pxref{File Name -Expansion}). +Expansion}). @code{nil} in this list refers to +@code{default-directory}. Executing a program can also try adding suffixes to the specified name: @@ -93,6 +96,10 @@ want the name to be tried exactly as specified. The default value is system-dependent. @end defvar + @strong{Please note:} The argument @var{program} contains only the +name of the program; it may not contain any command-line arguments. You +must use @var{args} to provide those. + Each of the subprocess-creating functions has a @var{buffer-or-name} argument which specifies where the standard output from the program will go. It should be a buffer or a buffer name; if it is a buffer name, @@ -107,12 +114,7 @@ same buffer because their output would be intermixed randomly. argument, @var{args}. The @var{args} must all be strings, and they are supplied to @var{program} as separate command line arguments. Wildcard characters and other shell constructs have no special meanings in these -strings, since the whole strings are passed directly to the specified -program. - - @strong{Please note:} The argument @var{program} contains only the -name of the program; it may not contain any command-line arguments. You -must use @var{args} to provide those. +strings, since the strings are passed directly to the specified program. The subprocess gets its current directory from the value of @code{default-directory} (@pxref{File Name Expansion}). @@ -168,7 +170,7 @@ function. (shell-quote-argument "foo > bar") @result{} "foo\\ \\>\\ bar" -;; @r{This example shows the behavior on MS-DOS and MS-Windows systems.} +;; @r{This example shows the behavior on MS-DOS and MS-Windows.} (shell-quote-argument "foo > bar") @result{} "\"foo > bar\"" @end example @@ -328,7 +330,7 @@ The arguments are handled in almost the same way as for Some file handlers may not support all combinations and forms of the arguments @var{infile}, @var{buffer}, and @var{display}. For example, -some file handlers might behave as if @var{display} was nil, +some file handlers might behave as if @var{display} were @code{nil}, regardless of the value actually passed. As another example, some file handlers might not support separating standard output and error output by way of the @var{buffer} argument. @@ -547,17 +549,16 @@ Information}). subprocess. Processes are deleted automatically after they terminate, but not necessarily right away. You can delete a process explicitly at any time. If you delete a terminated process explicitly before it -is deleted automatically, no harm results. Deletion of a running +is deleted automatically, no harm results. Deleting a running process sends a signal to terminate it (and its child processes if -any), and calls the process sentinel if it has one. +any), and calls the process sentinel if it has one. @xref{Sentinels}. - @code{get-buffer-process} and @code{process-list} do not remember a -deleted process, but the process object itself continues to exist as -long as other Lisp objects point to it. All the Lisp primitives that -work on process objects accept deleted processes, but those that do -I/O or send signals will report an error. The process mark continues -to point to the same place as before, usually into a buffer where -output from the process was being inserted. + When a process is deleted, the process object itself continues to +exist as long as other Lisp objects point to it. All the Lisp +primitives that work on process objects accept deleted processes, but +those that do I/O or send signals will report an error. The process +mark continues to point to the same place as before, usually into a +buffer where output from the process was being inserted. @defopt delete-exited-processes This variable controls automatic deletion of processes that have @@ -567,15 +568,16 @@ terminated (due to calling @code{exit} or to a signal). If it is they exit. @end defopt -@defun delete-process name -This function deletes the process associated with @var{name}, killing -it with a @code{SIGKILL} signal. The argument @var{name} may be a -process, the name of a process, a buffer, or the name of a buffer. -Calling @code{delete-process} on a running process terminates it, -updates the process status, and runs the sentinel (if any) immediately. -If the process has already terminated, calling @code{delete-process} -has no effect on its status, or on the running of its sentinel (which -will happen sooner or later). +@defun delete-process process +This function deletes a process, killing it with a @code{SIGKILL} +signal. The argument may be a process, the name of a process, a +buffer, or the name of a buffer. (A buffer or buffer-name stands for +the process that @code{get-buffer-process} returns.) Calling +@code{delete-process} on a running process terminates it, updates the +process status, and runs the sentinel (if any) immediately. If the +process has already terminated, calling @code{delete-process} has no +effect on its status, or on the running of its sentinel (which will +happen sooner or later). @smallexample @group @@ -728,7 +730,7 @@ for decoding output from @var{process} and for encoding input to @end example @end defun -@defun set-process-coding-system process decoding-system encoding-system +@defun set-process-coding-system process &optional decoding-system encoding-system This function specifies the coding systems to use for subsequent output from and input to @var{process}. It will use @var{decoding-system} to decode subprocess output, and @var{encoding-system} to encode subprocess @@ -766,9 +768,9 @@ specify the process to send input to, and the input data to send. The data appears on the ``standard input'' of the subprocess. Some operating systems have limited space for buffered input in a -@acronym{PTY}. On these systems, Emacs sends an @acronym{EOF} periodically amidst -the other characters, to force them through. For most programs, -these @acronym{EOF}s do no harm. +@acronym{PTY}. On these systems, Emacs sends an @acronym{EOF} +periodically amidst the other characters, to force them through. For +most programs, these @acronym{EOF}s do no harm. Subprocess input is normally encoded using a coding system before the subprocess receives it, much like text written into a file. You can use @@ -784,11 +786,14 @@ again. This gives the subprocess a chance to read more of its pending input and make space in the buffer. It also allows filters, sentinels and timers to run---so take account of that in writing your code. -@defun process-send-string process-name string -This function sends @var{process-name} the contents of @var{string} as -standard input. The argument @var{process-name} must be a process or -the name of a process. If it is @code{nil}, the current buffer's -process is used. + In these functions, the @var{process} argument can be a process or +the name of a process, or a buffer or buffer name (which stands +for a process via @code{get-buffer-process}). @code{nil} means +the current buffer's process. + +@defun process-send-string process string +This function sends @var{process} the contents of @var{string} as +standard input. If it is @code{nil}, the current buffer's process is used. The function returns @code{nil}. @@ -811,26 +816,20 @@ introduction.txt text.texi~ @end smallexample @end defun -@defun process-send-region process-name start end +@defun process-send-region process start end This function sends the text in the region defined by @var{start} and -@var{end} as standard input to @var{process-name}, which is a process or -a process name. (If it is @code{nil}, the current buffer's process is -used.) +@var{end} as standard input to @var{process}. An error is signaled unless both @var{start} and @var{end} are integers or markers that indicate positions in the current buffer. (It is unimportant which number is larger.) @end defun -@defun process-send-eof &optional process-name - This function makes @var{process-name} see an end-of-file in its +@defun process-send-eof &optional process +This function makes @var{process} see an end-of-file in its input. The @acronym{EOF} comes after any text already sent to it. - If @var{process-name} is not supplied, or if it is @code{nil}, then -this function sends the @acronym{EOF} to the current buffer's process. An -error is signaled if the current buffer has no process. - - The function returns @var{process-name}. +The function returns @var{process}. @smallexample @group @@ -873,12 +872,13 @@ processes. (@code{SIGHUP} is a signal that usually indicates that the user hung up the phone.) Each of the signal-sending functions takes two optional arguments: -@var{process-name} and @var{current-group}. +@var{process} and @var{current-group}. - The argument @var{process-name} must be either a process, the name of -one, or @code{nil}. If it is @code{nil}, the process defaults to the -process associated with the current buffer. An error is signaled if -@var{process-name} does not identify a process. + The argument @var{process} must be either a process, a process +name, a buffer, a buffer name, or @code{nil}. A buffer or buffer name +stands for a process through @code{get-buffer-process}. @code{nil} +stands for the process associated with the current buffer. An error +is signaled if @var{process} does not identify a process. The argument @var{current-group} is a flag that makes a difference when you are running a job-control shell as an Emacs subprocess. If it @@ -895,8 +895,8 @@ support the distinction in the case of pipes. For the same reason, job-control shells won't work when a pipe is used. See @code{process-connection-type} in @ref{Asynchronous Processes}. -@defun interrupt-process &optional process-name current-group -This function interrupts the process @var{process-name} by sending the +@defun interrupt-process &optional process current-group +This function interrupts the process @var{process} by sending the signal @code{SIGINT}. Outside of Emacs, typing the ``interrupt character'' (normally @kbd{C-c} on some systems, and @code{DEL} on others) sends this signal. When the argument @var{current-group} is @@ -904,21 +904,21 @@ non-@code{nil}, you can think of this function as ``typing @kbd{C-c}'' on the terminal by which Emacs talks to the subprocess. @end defun -@defun kill-process &optional process-name current-group -This function kills the process @var{process-name} by sending the +@defun kill-process &optional process current-group +This function kills the process @var{process} by sending the signal @code{SIGKILL}. This signal kills the subprocess immediately, and cannot be handled by the subprocess. @end defun -@defun quit-process &optional process-name current-group +@defun quit-process &optional process current-group This function sends the signal @code{SIGQUIT} to the process -@var{process-name}. This signal is the one sent by the ``quit +@var{process}. This signal is the one sent by the ``quit character'' (usually @kbd{C-b} or @kbd{C-\}) when you are not inside Emacs. @end defun -@defun stop-process &optional process-name current-group -This function stops the process @var{process-name} by sending the +@defun stop-process &optional process current-group +This function stops the process @var{process} by sending the signal @code{SIGTSTP}. Use @code{continue-process} to resume its execution. @@ -929,9 +929,9 @@ Outside of Emacs, on systems with job control, the ``stop character'' subprocess. @end defun -@defun continue-process &optional process-name current-group +@defun continue-process &optional process current-group This function resumes execution of the process @var{process} by sending -it the signal @code{SIGCONT}. This presumes that @var{process-name} was +it the signal @code{SIGCONT}. This presumes that @var{process} was stopped previously. @end defun @@ -940,8 +940,9 @@ stopped previously. 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 @acronym{ID}; that allows -you to send signals to processes that are not children of Emacs. +The @var{process} argument can be a system process @acronym{ID}; that +allows you to send signals to processes that are not children of +Emacs. @end defun @node Output from Processes @@ -973,9 +974,9 @@ primitive that waits. @defvar process-adaptive-read-buffering On some systems, when Emacs reads the output from a subprocess, the output data is read in very small blocks, potentially resulting in -very poor performance. This behaviour can be remedied to some extent +very poor performance. This behavior can be remedied to some extent by setting the variable @var{process-adaptive-read-buffering} to a -non-nil value (the default), as it will automatically delay reading +non-@code{nil} value (the default), as it will automatically delay reading from such processes, thus allowing them to produce more output before Emacs tries to read it. @end defvar @@ -1095,9 +1096,10 @@ then free to do whatever it chooses with the output. Quitting is normally inhibited within a filter function---otherwise, the effect of typing @kbd{C-g} at command level or to quit a user -command would be unpredictable. If you want to permit quitting inside a -filter function, bind @code{inhibit-quit} to @code{nil}. -@xref{Quitting}. +command would be unpredictable. If you want to permit quitting inside +a filter function, bind @code{inhibit-quit} to @code{nil}. In most +cases, the right way to do this is with the macro +@code{with-local-quit}. @xref{Quitting}. If an error happens during execution of a filter function, it is caught automatically, so that it doesn't stop the execution of whatever @@ -1240,7 +1242,7 @@ there is no filter function: it decodes the output according to the process output coding system. If the coding system is @code{raw-text} or @code{no-conversion}, Emacs converts the unibyte output to multibyte using -@code{string-to-multibyte}, inserts the resulting multibyte text. +@code{string-to-multibyte}, and inserts the resulting multibyte text. You can use @code{set-process-coding-system} to specify which coding system to use (@pxref{Process Information}). Otherwise, the coding @@ -1307,16 +1309,10 @@ subprocess output. The argument @var{seconds} need not be an integer. If it is a floating point number, this function waits for a fractional number of seconds. -Some systems support only a whole number of seconds; on these systems, -@var{seconds} is rounded down. - -Not all operating systems support waiting periods other than multiples -of a second; on those that do not, you get an error if you specify -nonzero @var{millisec}. -@c Emacs 21.4 feature +@c Emacs 22.1 feature If @var{process} is a process, and the argument @var{just-this-one} is -non-nil, only output from that process is handled, suspending output +non-@code{nil}, only output from that process is handled, suspending output from other processes until some output has been received from that process or the timeout expires. If @var{just-this-one} is an integer, also inhibit running timers. This feature is generally not @@ -1374,16 +1370,22 @@ quick succession, can call the sentinel just once. However, process termination will always run the sentinel exactly once. This is because the process status can't change again after termination. - Quitting is normally inhibited within a sentinel---otherwise, the -effect of typing @kbd{C-g} at command level or to quit a user command -would be unpredictable. If you want to permit quitting inside a -sentinel, bind @code{inhibit-quit} to @code{nil}. @xref{Quitting}. + Emacs explicitly checks for output from the process before running +the process sentinel. Once the sentinel runs due to process +termination, no further output can arrive from the process. A sentinel that writes the output into the buffer of the process should check whether the buffer is still alive. If it tries to insert into a dead buffer, it will get an error. If the buffer is dead, @code{(buffer-name (process-buffer @var{process}))} returns @code{nil}. + Quitting is normally inhibited within a sentinel---otherwise, the +effect of typing @kbd{C-g} at command level or to quit a user command +would be unpredictable. If you want to permit quitting inside a +sentinel, bind @code{inhibit-quit} to @code{nil}. In most cases, the +right way to do this is with the macro @code{with-local-quit}. +@xref{Quitting}. + If an error happens during execution of a sentinel, it is caught automatically, so that it doesn't stop the execution of whatever programs was running when the sentinel was started. However, if @@ -1443,7 +1445,7 @@ was not. @section Querying Before Exit When Emacs exits, it terminates all its subprocesses by sending them -the @code{SIGHUP} signal. Because some subprocesses are doing +the @code{SIGHUP} signal. Because subprocesses may be doing valuable work, Emacs normally asks the user to confirm that it is ok to terminate them. Each process has a query flag which, if non-@code{nil}, says that Emacs should ask for confirmation before @@ -1506,7 +1508,7 @@ process, or it may be a TCP connection to a server, possibly on another machine. @end defun -@defun tq-enqueue queue question regexp closure fn +@defun tq-enqueue queue question regexp closure fn &optional delay-question This function sends a transaction to queue @var{queue}. Specifying the queue has the effect of specifying the subprocess to talk to. @@ -1519,6 +1521,10 @@ The argument @var{regexp} is a regular expression that should match text at the end of the entire answer, but nothing before; that's how @code{tq-enqueue} determines where the answer ends. +If the argument @var{delay-question} is non-nil, delay sending this +question until the process has finished replying to any previous +questions. This produces more reliable results with some processes." + The return value of @code{tq-enqueue} itself is not meaningful. @end defun @@ -1560,9 +1566,7 @@ back to listening for more connection requests. keyword/argument pairs, for example @code{:server t} to create a server process, or @code{:type 'datagram} to create a datagram connection. @xref{Low-Level Network}, for details. You can also use -one of the @code{open-network-...} functions descibed below; -internally, they just call @code{make-network-process} with suitable -arguments. +the @code{open-network-stream} function described below. You can distinguish process objects representing network connections and servers from those representing subprocesses with the @@ -1577,7 +1581,7 @@ subprocess. @xref{Process Information}. process, being stopped means not accepting new connections. (Up to 5 connection requests will be queued for when you resume the server; you can increase this limit, unless it is imposed by the operating -systems.) For a network stream connection, being stopped means not +system.) For a network stream connection, being stopped means not processing input (any arriving input waits until you resume the connection). For a datagram connection, some number of packets may be queued but input may be lost. You can use the function @@ -1602,25 +1606,6 @@ The arguments @var{host} and @var{service} specify where to connect to; 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 @@ -1705,24 +1690,6 @@ number used for the connection. 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 @code{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 @@ -1755,6 +1722,20 @@ sets its remote peer address to @var{address}. @node Low-Level Network @section Low-Level Network Access + You can also create network connections by operating at a lower +level that that of @code{open-network-stream}, using +@code{make-network-process}. + +@menu +* Make Network:: Using @code{make-network-process}. +* Network Options:: Further control over network connections. +* Network Feature Testing:: Determining which network features work on + the machine you are using. +@end menu + +@node Make Network +@subsection @code{make-network-process} + 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. @@ -1768,7 +1749,7 @@ equivalent to specifying it with value @code{nil}, except for are the meaningful keywords: @table @asis -@item :name name +@item :name @var{name} Use the string @var{name} as the process name. It is modified if necessary to make it unique. @@ -1799,8 +1780,11 @@ 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. +communication. @code{nil} means determine the proper address family +automatically for the given @var{host} and @var{service}. +@code{local} specifies a Unix socket, in which case @var{host} is +ignored. @code{ipv4} and @code{ipv6} specify to use IPv4 and IPv6 +respectively. @item :local @var{local-address} For a server process, @var{local-address} is the address to listen on. @@ -1820,9 +1804,18 @@ 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}. +An IPv4 address is represented as a five-element vector of four 8-bit +integers and one 16-bit integer +@code{[@var{a} @var{b} @var{c} @var{d} @var{p}]} corresponding to +numeric IPv4 address @var{a}.@var{b}.@var{c}.@var{d} and port number +@var{p}. + +@item +An IPv6 address is represented as a nine-element vector of 16-bit +integers @code{[@var{a} @var{b} @var{c} @var{d} @var{e} @var{f} +@var{g} @var{h} @var{p}]} corresponding to numeric IPv6 address +@var{a}:@var{b}:@var{c}:@var{d}:@var{e}:@var{f}:@var{g}:@var{h} and +port number @var{p}. @item A local address is represented as a string which specifies the address @@ -1863,7 +1856,8 @@ If you don't specify this keyword at all, the default is to determine the coding systems from the data. @item :noquery @var{query-flag} -Initialize the process query flag to @var{query-flag}. @xref{Query Before Exit}. +Initialize the process query flag to @var{query-flag}. +@xref{Query Before Exit}. @item :filter @var{filter} Initialize the process filter to @var{filter}. @@ -1890,14 +1884,21 @@ happened. Initialize the process plist to @var{plist}. @end table -The following network options can be specified for the network -process. Except for @code{:reuseaddr}, you can set or modify these -options later using @code{set-network-process-option}. +The original argument list, modified with the actual connection +information, is available via the @code{process-contact} function. +@end defun + +@node Network Options +@subsection Network Options + + The following network options can be specified when you create a +network process. Except for @code{:reuseaddr}, you can also set or +modify these options later, using @code{set-network-process-option}. -For a server process, the options specified with + For a server process, the options specified with @code{make-network-process} are not inherited by the client connections, so you will need to set the necessary options for each -child connection as they are created. +child connection as it is created. @table @asis @item :bindtodevice @var{device-name} @@ -1952,13 +1953,8 @@ listening on that port. If @var{reuseaddr-flag} is @code{nil}, there may be a period of time after the last use of that port (by any process on the host), where it is not possible to make a new server on that port. - @end table -The original argument list, modified with the actual connection -information, is available via the @code{process-contact} function. -@end defun - @defun set-network-process-option process option value This function sets or modifies a network option for network process @var{process}. See @code{make-network-process} for details of options @@ -1968,43 +1964,8 @@ The current setting of an option is available via the @code{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 +@node Network Feature Testing +@subsection Testing Availability of Network Features To test for the availability of a given network feature, use @code{featurep} like this: @@ -2028,6 +1989,8 @@ Non-@code{nil} if non-blocking connect is supported. Non-@code{nil} if datagrams are supported. @item (:family local) Non-@code{nil} if local (aka ``UNIX domain'') sockets are supported. +@item (:family ipv6) +Non-@code{nil} if IPv6 is supported. @item (:service t) Non-@code{nil} if the system can select the port for a server. @end table @@ -2039,8 +2002,8 @@ Non-@code{nil} if the system can select the port for a server. (featurep 'make-network-process '@var{keyword}) @end example -Here are some of the option @var{keyword}s you can test in -this way. +@noindent +Here are some of the options you can test in this way. @table @code @item :bindtodevice @@ -2055,7 +2018,463 @@ That particular network option is supported by @code{make-network-process} and @code{set-network-process-option}. @end table +@node Misc Network +@section Misc Network Facilities + + These additional functions are useful for creating and operating +on network connections. + +@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. + +A five-element vector @code{[@var{a} @var{b} @var{c} @var{d} @var{p}]} +represents an IPv4 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}"}. + +A nine-element vector @code{[@var{a} @var{b} @var{c} @var{d} @var{e} +@var{f} @var{g} @var{h} @var{p}]} represents an IPv6 address and port +number. @code{format-network-address} converts that to the string +@code{"[@var{a}:@var{b}:@var{c}:@var{d}:@var{e}:@var{f}:@var{g}:@var{h}]:@var{p}"}. + +If the vector does not include the port number, @var{p}, or if +@var{omit-port} is non-@code{nil}, the result does not include the +@code{:@var{p}} suffix. +@end defun + +@node Byte Packing +@section Packing and Unpacking Byte Arrays + + This section describes how to pack and unpack arrays of bytes, +usually for binary network protocols. These functions convert byte arrays +to alists, and vice versa. The byte array can be represented as a +unibyte string or as a vector of integers, while the alist associates +symbols either with fixed-size objects or with recursive sub-alists. + +@cindex serializing +@cindex deserializing +@cindex packing +@cindex unpacking + Conversion from byte arrays to nested alists is also known as +@dfn{deserializing} or @dfn{unpacking}, while going in the opposite +direction is also known as @dfn{serializing} or @dfn{packing}. + +@menu +* Bindat Spec:: Describing data layout. +* Bindat Functions:: Doing the unpacking and packing. +* Bindat Examples:: Samples of what bindat.el can do for you! +@end menu + +@node Bindat Spec +@subsection Describing Data Layout + + To control unpacking and packing, you write a @dfn{data layout +specification}, a special nested list describing named and typed +@dfn{fields}. This specification controls length of each field to be +processed, and how to pack or unpack it. + +@cindex endianness +@cindex big endian +@cindex little endian +@cindex network byte ordering + A field's @dfn{type} describes the size (in bytes) of the object +that the field represents and, in the case of multibyte fields, how +the bytes are ordered within the field. The two possible orderings +are ``big endian'' (also known as ``network byte ordering'') and +``little endian''. For instance, the number @code{#x23cd} (decimal +9165) in big endian would be the two bytes @code{#x23} @code{#xcd}; +and in little endian, @code{#xcd} @code{#x23}. Here are the possible +type values: + +@table @code +@item u8 +@itemx byte +Unsigned byte, with length 1. + +@item u16 +@itemx word +@itemx short +Unsigned integer in network byte order, with length 2. + +@item u24 +Unsigned integer in network byte order, with length 3. + +@item u32 +@itemx dword +@itemx long +Unsigned integer in network byte order, with length 4. +Note: These values may be limited by Emacs' integer implementation limits. + +@item u16r +@itemx u24r +@itemx u32r +Unsigned integer in little endian order, with length 2, 3 and 4, respectively. + +@item str @var{len} +String of length @var{len}. + +@item strz @var{len} +Zero-terminated string of length @var{len}. + +@item vec @var{len} +Vector of @var{len} bytes. + +@item ip +Four-byte vector representing an Internet address. For example: +@code{[127 0 0 1]} for localhost. + +@item bits @var{len} +List of set bits in @var{len} bytes. The bytes are taken in big +endian order and the bits are numbered starting with @code{8 * +@var{len} @minus{} 1} and ending with zero. For example: @code{bits +2} unpacks @code{#x28} @code{#x1c} to @code{(2 3 4 11 13)} and +@code{#x1c} @code{#x28} to @code{(3 5 10 11 12)}. + +@item (eval @var{form}) +@var{form} is a Lisp expression evaluated at the moment the field is +unpacked or packed. The result of the evaluation should be one of the +above-listed type specifications. +@end table + +A field specification generally has the form @code{([@var{name}] +@var{handler})}. The square braces indicate that @var{name} is +optional. (Don't use names that are symbols meaningful as type +specifications (above) or handler specifications (below), since that +would be ambiguous.) @var{name} can be a symbol or the expression +@code{(eval @var{form})}, in which case @var{form} should evaluate to +a symbol. + +@var{handler} describes how to unpack or pack the field and can be one +of the following: + +@table @code +@item @var{type} +Unpack/pack this field according to the type specification @var{type}. + +@item eval @var{form} +Evaluate @var{form}, a Lisp expression, for side-effect only. If the +field name is specified, the value is bound to that field name. +@var{form} can access and update these dynamically bound variables: + +@table @code +@item raw-data +The data as a byte array. + +@item pos +Current position of the unpacking or packing operation. + +@item struct +Alist. + +@item last +Value of the last field processed. +@end table + +@item fill @var{len} +Skip @var{len} bytes. In packing, this leaves them unchanged, +which normally means they remain zero. In unpacking, this means +they are ignored. + +@item align @var{len} +Skip to the next multiple of @var{len} bytes. + +@item struct @var{spec-name} +Process @var{spec-name} as a sub-specification. This describes a +structure nested within another structure. + +@item union @var{form} (@var{tag} @var{spec})@dots{} +@c ??? I don't see how one would actually use this. +@c ??? what kind of expression would be useful for @var{form}? +Evaluate @var{form}, a Lisp expression, find the first @var{tag} +that matches it, and process its associated data layout specification +@var{spec}. Matching can occur in one of three ways: + +@itemize +@item +If a @var{tag} has the form @code{(eval @var{expr})}, evaluate +@var{expr} with the variable @code{tag} dynamically bound to the value +of @var{form}. A non-@code{nil} result indicates a match. + +@item +@var{tag} matches if it is @code{equal} to the value of @var{form}. + +@item +@var{tag} matches unconditionally if it is @code{t}. +@end itemize + +@item repeat @var{count} @var{field-spec}@dots{} +@var{count} may be an integer, or a list of one element naming a +previous field. For correct operation, each @var{field-spec} must +include a name. +@c ??? What does it MEAN? +@end table + +@node Bindat Functions +@subsection Functions to Unpack and Pack Bytes + + In the following documentation, @var{spec} refers to a data layout +specification, @code{raw-data} to a byte array, and @var{struct} to an +alist representing unpacked field data. + +@defun bindat-unpack spec raw-data &optional pos +This function unpacks data from the byte array @code{raw-data} +according to @var{spec}. Normally this starts unpacking at the +beginning of the byte array, but if @var{pos} is non-@code{nil}, it +specifies a zero-based starting position to use instead. + +The value is an alist or nested alist in which each element describes +one unpacked field. +@end defun + +@defun bindat-get-field struct &rest name +This function selects a field's data from the nested alist +@var{struct}. Usually @var{struct} was returned by +@code{bindat-unpack}. If @var{name} corresponds to just one argument, +that means to extract a top-level field value. Multiple @var{name} +arguments specify repeated lookup of sub-structures. An integer name +acts as an array index. + +For example, if @var{name} is @code{(a b 2 c)}, that means to find +field @code{c} in the third element of subfield @code{b} of field +@code{a}. (This corresponds to @code{struct.a.b[2].c} in C.) +@end defun + +@defun bindat-length spec struct +@c ??? I don't understand this at all -- rms +This function returns the length in bytes of @var{struct}, according +to @var{spec}. +@end defun + +@defun bindat-pack spec struct &optional raw-data pos +This function returns a byte array packed according to @var{spec} from +the data in the alist @var{struct}. Normally it creates and fills a +new byte array starting at the beginning. However, if @var{raw-data} +is non-@code{nil}, it specifies a pre-allocated string or vector to +pack into. If @var{pos} is non-@code{nil}, it specifies the starting +offset for packing into @code{raw-data}. + +@c ??? Isn't this a bug? Shouldn't it always be unibyte? +Note: The result is a multibyte string; use @code{string-make-unibyte} +on it to make it unibyte if necessary. +@end defun + +@defun bindat-ip-to-string ip +Convert the Internet address vector @var{ip} to a string in the usual +dotted notation. + +@example +(bindat-ip-to-string [127 0 0 1]) + @result{} "127.0.0.1" +@end example +@end defun + +@node Bindat Examples +@subsection Examples of Byte Unpacking and Packing + + Here is a complete example of byte unpacking and packing: + +@lisp +(defvar fcookie-index-spec + '((:version u32) + (:count u32) + (:longest u32) + (:shortest u32) + (:flags u32) + (:delim u8) + (:ignored fill 3) + (:offset repeat (:count) + (:foo u32))) + "Description of a fortune cookie index file's contents.") + +(defun fcookie (cookies &optional index) + "Display a random fortune cookie from file COOKIES. +Optional second arg INDEX specifies the associated index +filename, which is by default constructed by appending +\".dat\" to COOKIES. Display cookie text in possibly +new buffer \"*Fortune Cookie: BASENAME*\" where BASENAME +is COOKIES without the directory part." + (interactive "fCookies file: ") + (let* ((info (with-temp-buffer + (insert-file-contents-literally + (or index (concat cookies ".dat"))) + (bindat-unpack fcookie-index-spec + (buffer-string)))) + (sel (random (bindat-get-field info :count))) + (beg (cdar (bindat-get-field info :offset sel))) + (end (or (cdar (bindat-get-field info + :offset (1+ sel))) + (nth 7 (file-attributes cookies))))) + (switch-to-buffer + (get-buffer-create + (format "*Fortune Cookie: %s*" + (file-name-nondirectory cookies)))) + (erase-buffer) + (insert-file-contents-literally + cookies nil beg (- end 3)))) + +(defun fcookie-create-index (cookies &optional index delim) + "Scan file COOKIES, and write out its index file. +Optional second arg INDEX specifies the index filename, +which is by default constructed by appending \".dat\" to +COOKIES. Optional third arg DELIM specifies the unibyte +character which, when found on a line of its own in +COOKIES, indicates the border between entries." + (interactive "fCookies file: ") + (setq delim (or delim ?%)) + (let ((delim-line (format "\n%c\n" delim)) + (count 0) + (max 0) + min p q len offsets) + (unless (= 3 (string-bytes delim-line)) + (error "Delimiter cannot be represented in one byte")) + (with-temp-buffer + (insert-file-contents-literally cookies) + (while (and (setq p (point)) + (search-forward delim-line (point-max) t) + (setq len (- (point) 3 p))) + (setq count (1+ count) + max (max max len) + min (min (or min max) len) + offsets (cons (1- p) offsets)))) + (with-temp-buffer + (set-buffer-multibyte nil) + (insert + (string-make-unibyte + (bindat-pack + fcookie-index-spec + `((:version . 2) + (:count . ,count) + (:longest . ,max) + (:shortest . ,min) + (:flags . 0) + (:delim . ,delim) + (:offset . ,(mapcar (lambda (o) + (list (cons :foo o))) + (nreverse offsets))))))) + (let ((coding-system-for-write 'raw-text-unix)) + (write-file (or index (concat cookies ".dat"))))))) +@end lisp + +Following is an example of defining and unpacking a complex structure. +Consider the following C structures: + +@example +struct header @{ + unsigned long dest_ip; + unsigned long src_ip; + unsigned short dest_port; + unsigned short src_port; +@}; + +struct data @{ + unsigned char type; + unsigned char opcode; + unsigned long length; /* In little endian order */ + unsigned char id[8]; /* null-terminated string */ + unsigned char data[/* (length + 3) & ~3 */]; +@}; + +struct packet @{ + struct header header; + unsigned char items; + unsigned char filler[3]; + struct data item[/* items */]; + +@}; +@end example + +The corresponding data layout specification: + +@lisp +(setq header-spec + '((dest-ip ip) + (src-ip ip) + (dest-port u16) + (src-port u16))) + +(setq data-spec + '((type u8) + (opcode u8) + (length u16r) ;; little endian order + (id strz 8) + (data vec (length)) + (align 4))) + +(setq packet-spec + '((header struct header-spec) + (items u8) + (fill 3) + (item repeat (items) + (struct data-spec)))) +@end lisp + +A binary data representation: + +@lisp +(setq binary-data + [ 192 168 1 100 192 168 1 101 01 28 21 32 2 0 0 0 + 2 3 5 0 ?A ?B ?C ?D ?E ?F 0 0 1 2 3 4 5 0 0 0 + 1 4 7 0 ?B ?C ?D ?E ?F ?G 0 0 6 7 8 9 10 11 12 0 ]) +@end lisp + +The corresponding decoded structure: + +@lisp +(setq decoded (bindat-unpack packet-spec binary-data)) + @result{} +((header + (dest-ip . [192 168 1 100]) + (src-ip . [192 168 1 101]) + (dest-port . 284) + (src-port . 5408)) + (items . 2) + (item ((data . [1 2 3 4 5]) + (id . "ABCDEF") + (length . 5) + (opcode . 3) + (type . 2)) + ((data . [6 7 8 9 10 11 12]) + (id . "BCDEFG") + (length . 7) + (opcode . 4) + (type . 1)))) +@end lisp + +Fetching data from this structure: + +@lisp +(bindat-get-field decoded 'item 1 'id) + @result{} "BCDEFG" +@end lisp + @ignore arch-tag: ba9da253-e65f-4e7f-b727-08fba0a1df7a @end ignore -