@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 Free Software Foundation, Inc.
+@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
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 22.1 feature
If @var{process} is a process, and the argument @var{just-this-one} is
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
@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 automatically determine a the
-proper address family 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.
+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.
@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)
@table @var
@item addr
-The internet protocol address.
+The Internet protocol address.
@item bcast
The broadcast address.
@item netmask
@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}
+
+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 @var{omit-port} is
-non-@code{nil}, the result does not include the @code{:@var{p}} suffix.
+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
@var{form} can access and update these dynamically bound variables:
@table @code
-@item raw-data
+@item bindat-raw
The data as a byte array.
-@item pos
-Current position of the unpacking or packing operation.
+@item bindat-idx
+Current index into bindat-raw of the unpacking or packing operation.
@item struct
Alist.
@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?
+@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.
@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
-This function unpacks data from the byte array @code{raw-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{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
@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
-@c ??? I don't understand this at all -- rms
-This function returns the length in bytes of @var{struct}, according
-to @var{spec}.
+This function returns the total length of the data in @var{struct},
+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}
-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}.
+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}.
-@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.
+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
(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)))))))
+ (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