(Misc Network, Network Feature Testing)

(Network Options, Make Network): New nodes split out of Low-Level Network.

1 files changed, 76 insertions, 50 deletions

diff --git a/lispref/processes.texi b/lispref/processes.texi
index bf92fc387a7..afdeaa1d2a0 100644
--- a/lispref/processes.texi
+++ b/lispref/processes.texi
@@ -52,6 +52,7 @@ This function returns @code{t} if @var{object} is a process,
 * 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
 
@@ -1716,6 +1717,20 @@ sets its remote peer address to @var{address}.
 @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.
@@ -1852,14 +1867,21 @@ happened.
 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}
@@ -1914,13 +1936,8 @@ listening on that port.  If @var{reuseaddr-flag} is @code{nil}, there
 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
@@ -1930,44 +1947,8 @@ The current setting of an option is available via the
 @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:
@@ -2002,8 +1983,8 @@ Non-@code{nil} if the system can select the port for a server.
 (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
@@ -2018,6 +1999,51 @@ That particular network option is supported by
 @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.  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 Byte Packing
 @section Packing and Unpacking Byte Arrays