@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
* 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
@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:
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,
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}).
(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
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.
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
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
@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
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
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}.
@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
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
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
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.
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
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
@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
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
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
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
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
@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
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.
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
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
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
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
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
@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.
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.
@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.
@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
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}.
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}
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
@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:
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
(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
@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
-