@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003,
-@c 2004, 2005, 2006 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.
@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
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.
+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
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}.
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."
+questions. This produces more reliable results with some processes.
The return value of @code{tq-enqueue} itself is not meaningful.
@end defun
@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
+* 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 Make Network
+@node Network Processes
@subsection @code{make-network-process}
The basic function for creating network connections and network
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.
+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
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
+``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:
String of length @var{len}.
@item strz @var{len}
-Zero-terminated string of length @var{len}.
+Zero-terminated string, in a fixed-size field with length @var{len}.
-@item vec @var{len}
-Vector of @var{len} bytes.
+@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:
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
@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,
@var{tag} matches unconditionally if it is @code{t}.
@end itemize
-@item repeat @var{count} @var{field-spec}@dots{}
-Process the set of @var{field-spec}s recursively, in order, and loop
-starting from the first one, for @var{count} times overall (looping
-@code{@var{count} @minus{} 1} times).
-@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.
+@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{raw-data} to a byte array, and @var{struct} to an
+specification, @code{bindat-raw} to a byte array, and @var{struct} to an
alist representing unpacked field data.
-@defun bindat-unpack spec raw-data &optional pos
+@defun bindat-unpack spec bindat-raw &optional bindat-idx
This function unpacks data from the unibyte string or byte
-array @code{raw-data}
+array @code{bindat-raw}
according to @var{spec}. Normally this starts unpacking at the
-beginning of the byte array, but if @var{pos} is non-@code{nil}, it
+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
according to @var{spec}.
@end defun
-@defun bindat-pack spec struct &optional raw-data pos
+@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{raw-data}
+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{pos} is non-@code{nil}, it specifies the starting
-offset for packing into @code{raw-data}.
+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{raw-data})}
+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
struct data @{
unsigned char type;
unsigned char opcode;
- unsigned long length; /* In little endian order */
+ 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 */];
(setq data-spec
'((type u8)
(opcode u8)
- (length u16r) ;; little endian order
+ (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)
@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 ])
+ [ 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:
(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")