@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, 2001,
+@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/processes
@node Processes, Display, Abbrevs, Top
before continuing execution. When you create an asynchronous
subprocess, it can run in parallel with the Lisp program. This kind of
subprocess is represented within Emacs by a Lisp object which is also
-called a ``process''. Lisp programs can use this object to communicate
+called a ``process.'' Lisp programs can use this object to communicate
with the subprocess or to control it. For example, you can send
signals, obtain status information, receive output from the process, or
send input to it.
* 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
@node Shell Arguments
@section Shell Arguments
+@cindex arguments for shell commands
+@cindex shell command arguments
Lisp programs sometimes need to run a shell and give it a command
that contains file names that were specified by the user. These
(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
@var{infile} is on another remote host. Or @code{default-directory}
could be non-special, whereas @var{infile} is on a remote host.)
-If @var{buffer} has the form @code{(@var{real-destination}
+If @var{buffer} is a list of the form @code{(@var{real-destination}
@var{error-destination})}, and @var{error-destination} names a file,
then the same remarks as for @var{infile} apply.
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
@end defun
@defun process-running-child-p process
-@tindex process-running-child-p process
This function will tell you whether a subprocess has given control of
its terminal to its own child process. The value is @code{t} if this is
true, or if Emacs cannot tell; it is @code{nil} if Emacs can be certain
@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-@code{nil} value (the default), as it will automatically delay reading
from such processes, thus allowing them to produce more output before
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
@node Decoding Output
@subsection Decoding Process Output
+@cindex decode process output
When Emacs writes process output directly into a multibyte buffer,
it decodes the output according to the process output coding system.
@node Accepting Output
@subsection Accepting Output from Processes
+@cindex accept input from processes
Output from asynchronous subprocesses normally arrives only while
Emacs is waiting for some sort of external event, such as elapsed time
periods. The former specifies a period measured in seconds and the
latter specifies one measured in milliseconds. The two time periods
thus specified are added together, and @code{accept-process-output}
-returns after that much time whether or not there has been any
+returns after that much time, whether or not there has been any
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}.
+
+The argument @var{millisec} is semi-obsolete nowadays because
+@var{seconds} can be a floating point number to specify waiting a
+fractional number of seconds. If @var{seconds} is 0, the function
+accepts whatever output is pending but does not wait.
@c Emacs 22.1 feature
If @var{process} is a process, and the argument @var{just-this-one} is
@node Sentinels
@section Sentinels: Detecting Process Status Changes
@cindex process sentinel
-@cindex sentinel
+@cindex sentinel (of process)
A @dfn{process sentinel} is a function that is called whenever the
associated process changes status for any reason, including signals
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
exiting and thus killing that process. The default for the query flag
is @code{t}, meaning @emph{do} query.
-@tindex process-query-on-exit-flag
@defun process-query-on-exit-flag process
This returns the query flag of @var{process}.
@end defun
-@tindex set-process-query-on-exit-flag
@defun set-process-query-on-exit-flag process flag
This function sets the query flag of @var{process} to @var{flag}. It
returns @var{flag}.
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
@item :sentinel
The associated value is the process sentinel function.
@item :remote
-In a connection, this is the address in internal format of the remote peer.
+In a connection, the address in internal format of the remote peer.
@item :local
The local address, in internal format.
@item :service
@node Network Servers
@section Network Servers
+@cindex network servers
You create a server by calling @code{make-network-process} with
@code{:server t}. The server will listen for connection requests from
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 than that of @code{open-network-stream}, using
+@code{make-network-process}.
+
+@menu
+* Proc: Network Processes. Using @code{make-network-process}.
+* Options: Network Options. Further control over network connections.
+* Features: Network Feature Testing.
+ Determining which network features work on
+ the machine you are using.
+@end menu
+
+@node Network Processes
+@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.
@item :host @var{host}
Specify the host to connect to. @var{host} should be a host name or
-internet address, as a string, or the symbol @code{local} to specify
+Internet address, as a string, or the symbol @code{local} to specify
the local host. If you specify @var{host} for a server, it must
specify a valid address for the local host, and only clients
connecting to that address will be accepted.
@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
-For a server process, the options specified with
+@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
@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:
@item (:type datagram)
Non-@code{nil} if datagrams are supported.
@item (:family local)
-Non-@code{nil} if local (aka ``UNIX domain'') sockets are supported.
+Non-@code{nil} if local (a.k.a.@: ``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. Note that they are supported only on some
+systems.
+
+@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 along
+with a 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
+@cindex byte packing and unpacking
+
+ 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. We normally keep bindat specs
+in variables whose names end in @samp{-bindat-spec}; that kind of name
+is automatically recognized as ``risky.''
+
+@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, in a fixed-size field with length @var{len}.
+
+@item vec @var{len} [@var{type}]
+Vector of @var{len} elements of type @var{type}, or bytes if not
+@var{type} is specified.
+The @var{type} is any of the simple types above, or another vector
+specified as a list @code{(vec @var{len} [@var{type}])}.
+
+@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
+
+For a fixed-size field, the length @var{len} is given as an integer
+specifying the number of bytes in the field.
+
+When the length of a field is not fixed, it typically depends on the
+value of a preceding field. In this case, the length @var{len} can be
+given either as a list @code{(@var{name} ...)} identifying a
+@dfn{field name} in the format specified for @code{bindat-get-field}
+below, or by an expression @code{(eval @var{form})} where @var{form}
+should evaluate to an integer, specifying the field length.
+
+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.
+
+@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-specs}@dots{}
+Process the @var{field-specs} recursively, in order, then repeat
+starting from the first one, processing all the specs @var{count}
+times overall. The @var{count} is given using the same formats as a
+field length---if an @code{eval} form is used, it is evaluated just once.
+For correct operation, each spec in @var{field-specs} must include a name.
+@end table
+
+For the @code{(eval @var{form})} forms used in a bindat specification,
+the @var{form} can access and update these dynamically bound variables
+during evaluation:
+
+@table @code
+@item last
+Value of the last field processed.
+
+@item bindat-raw
+The data as a byte array.
+
+@item bindat-idx
+Current index (within @code{bindat-raw}) for unpacking or packing.
+
+@item struct
+The alist containing the structured data that have been unpacked so
+far, or the entire structure being packed. You can use
+@code{bindat-get-field} to access specific fields of this structure.
+
+@item count
+@itemx index
+Inside a @code{repeat} block, these contain the maximum number of
+repetitions (as specified by the @var{count} parameter), and the
+current repetition number (counting from 0). Setting @code{count} to
+zero will terminate the inner-most repeat block after the current
+repetition has completed.
+@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{bindat-raw} to a byte array, and @var{struct} to an
+alist representing unpacked field data.
+
+@defun bindat-unpack spec bindat-raw &optional bindat-idx
+This function unpacks data from the unibyte string or byte
+array @code{bindat-raw}
+according to @var{spec}. Normally this starts unpacking at the
+beginning of the byte array, but if @var{bindat-idx} 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
+
+ Although packing and unpacking operations change the organization of
+data (in memory), they preserve the data's @dfn{total length}, which is
+the sum of all the fields' lengths, in bytes. This value is not
+generally inherent in either the specification or alist alone; instead,
+both pieces of information contribute to its calculation. Likewise, the
+length of a string or array being unpacked may be longer than the data's
+total length as described by the specification.
+
+@defun bindat-length spec struct
+This function returns the total length of the data in @var{struct},
+according to @var{spec}.
+@end defun
+
+@defun bindat-pack spec struct &optional bindat-raw bindat-idx
+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{bindat-raw}
+is non-@code{nil}, it specifies a pre-allocated unibyte string or vector to
+pack into. If @var{bindat-idx} is non-@code{nil}, it specifies the starting
+offset for packing into @code{bindat-raw}.
+
+When pre-allocating, you should make sure @code{(length @var{bindat-raw})}
+meets or exceeds the total length to avoid an out-of-range error.
+@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
+ (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 short length; /* In network byte order */
+ unsigned char id[8]; /* null-terminated string */
+ unsigned char data[/* (length + 3) & ~3 */];
+@};
+
+struct packet @{
+ struct header header;
+ unsigned long counters[2]; /* In little endian order */
+ 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 u16) ;; network byte order
+ (id strz 8)
+ (data vec (length))
+ (align 4)))
+
+(setq packet-spec
+ '((header struct header-spec)
+ (counters vec 2 u32r) ;; little endian order
+ (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
+ 160 134 1 0 5 1 0 0 2 0 0 0
+ 2 3 0 5 ?A ?B ?C ?D ?E ?F 0 0 1 2 3 4 5 0 0 0
+ 1 4 0 7 ?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))
+ (counters . [100000 261])
+ (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
-
HCoop / bpt / emacs.git / blobdiff