@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2005
-@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
* 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
(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
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
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
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
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
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
@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.
@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
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
-For a server process, the options specified with
+ 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:
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
To control unpacking and packing, you write a @dfn{data layout
specification}, a special nested list describing named and typed
-@dfn{fields}. This specification conrtols length of each field to be
+@dfn{fields}. This specification controls length of each field to be
processed, and how to pack or unpack it.
@cindex endianness
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 second element of subfield @code{b} of field
+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
Here is a complete example of byte unpacking and packing:
- @lisp
+@lisp
(defvar fcookie-index-spec
'((:version u32)
(:count u32)
(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)))
+ (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))))
+ (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))))
+ (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.
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)))))))
+ (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
The corresponding decoded structure:
@lisp
-(setq decoded-structure (bindat-unpack packet-spec binary-data))
+(setq decoded (bindat-unpack packet-spec binary-data))
@result{}
((header
(dest-ip . [192 168 1 100])
Fetching data from this structure:
@lisp
-(bindat-get-field decoded-structure 'item 1 'id)
+(bindat-get-field decoded 'item 1 'id)
@result{} "BCDEFG"
@end lisp