@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
@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
@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.
@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.
-If @var{seconds} is 0, the function accepts whatever output is
-pending but does not wait.
+
+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
@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
@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
+level than that of @code{open-network-stream}, using
@code{make-network-process}.
@menu
@section Misc Network Facilities
These additional functions are useful for creating and operating
-on network connections.
+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
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
+@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
@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
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 bindat-raw
-The data as a byte array.
-
-@item bindat-idx
-Current index into bindat-raw 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,
@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. @var{count} may be an integer, or a list of one
-element that names a previous field. For correct operation, each spec
-in @var{field-specs} must include a name.
+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
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")
HCoop / bpt / emacs.git / blobdiff