1 files changed, 64 insertions, 50 deletions
diff --git a/doc/socket.n b/doc/socket.n
index 7596abb..0fa8872 100644
--- a/doc/socket.n
+++ b/doc/socket.n
@@ -5,9 +5,9 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-'\" RCS: @(#) $Id: socket.n,v 1.20 2010/02/24 10:11:46 dkf Exp $
+'\" RCS: @(#) $Id: socket.n,v 1.21 2010/09/28 15:13:54 rmax Exp $
 .so man.macros
-.TH socket n 8.0 Tcl "Tcl Built-In Commands"
+.TH socket n 8.6 Tcl "Tcl Built-In Commands"
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -20,18 +20,17 @@ socket \- Open a TCP network connection
 .BE
 .SH DESCRIPTION
 .PP
-This command opens a network socket and returns a channel
-identifier that may be used in future invocations of commands like
-\fBread\fR, \fBputs\fR and \fBflush\fR.
-At present only the TCP network protocol is supported;  future
-releases may include support for additional protocols.
-The \fBsocket\fR command may be used to open either the client or
-server side of a connection, depending on whether the \fB\-server\fR
-switch is specified.
+This command opens a network socket and returns a channel identifier
+that may be used in future invocations of commands like \fBread\fR,
+\fBputs\fR and \fBflush\fR.  At present only the TCP network protocol
+is supported over IPv4 and IPv6; future releases may include support
+for additional protocols.  The \fBsocket\fR command may be used to
+open either the client or server side of a connection, depending on
+whether the \fB\-server\fR switch is specified.
 .PP
 Note that the default encoding for \fIall\fR sockets is the system
 encoding, as returned by \fBencoding system\fR.  Most of the time, you
-will need to use \fBfconfigure\fR to alter this to something else,
+will need to use \fBchan configure\fR to alter this to something else,
 such as \fIutf\-8\fR (ideal for communicating with other Tcl
 processes) or \fIiso8859\-1\fR (useful for many network protocols,
 especially the older ones).
@@ -46,7 +45,7 @@ this port.  \fIPort\fR is an integer port number
 (or service name, where supported and understood by the host operating
 system) and \fIhost\fR
 is either a domain-style name such as \fBwww.tcl.tk\fR or
-a numerical IP address such as \fB127.0.0.1\fR.
+a numerical IPv4 or IPv6 address such as \fB127.0.0.1\fR or \fB2001:DB8::1\fR.
 Use \fIlocalhost\fR to refer to the host on which the command is invoked.
 .PP
 The following options may also be present before \fIhost\fR
@@ -70,51 +69,55 @@ port number will be chosen at random by the system software.
 .TP
 \fB\-async\fR
 .
-The \fB\-async\fR option will cause the client socket to be connected
-asynchronously. This means that the socket will be created immediately but
-may not yet be connected to the server, when the call to \fBsocket\fR
-returns. When a \fBgets\fR or \fBflush\fR is done on the socket before the
-connection attempt succeeds or fails, if the socket is in blocking mode, the
-operation will wait until the connection is completed or fails. If the
-socket is in nonblocking mode and a \fBgets\fR or \fBflush\fR is done on
-the socket before the connection attempt succeeds or fails, the operation
-returns immediately and \fBfblocked\fR on the socket returns 1. Synchronous
-client sockets may be switched (after they have connected) to operating in
-asynchronous mode using:
+This option will cause the client socket to be connected
+asynchronously. This means that the socket will be created immediately
+but may not yet be connected to the server, when the call to
+\fBsocket\fR returns. When a \fBgets\fR or \fBflush\fR is done on the
+socket before the connection attempt succeeds or fails, if the socket
+is in blocking mode, the operation will wait until the connection is
+completed or fails. If the socket is in nonblocking mode and a
+\fBgets\fR or \fBflush\fR is done on the socket before the connection
+attempt succeeds or fails, the operation returns immediately and
+\fBfblocked\fR on the socket returns 1. Synchronous client sockets may
+be switched (after they have connected) to operating in asynchronous
+mode using:
 .RS
 .PP
 .CS
-\fBfconfigure \fIchan \fB\-blocking 0\fR
+\fBchan configure \fIchan \fB\-blocking 0\fR
 .CE
 .PP
-See the \fBfconfigure\fR command for more details.
+See the \fBchan\fR \fBconfigure\fR command for more details.
 .RE
 .SH "SERVER SOCKETS"
 .PP
-If the \fB\-server\fR option is specified then the new socket
-will be a server for the port given by \fIport\fR (either an integer
-or a service name, where supported and understood by the host
-operating system; if \fIport\fR is zero, the operating system will
-allocate a free port to the server socket which may be discovered by
-using \fBfconfigure\fR to read the \fB\-sockname\fR option).
-Tcl will automatically accept connections to the given port.
+If the \fB\-server\fR option is specified then the new socket will be
+a server that listens on the given \fIport\fR (either an integer or a
+service name, where supported and understood by the host operating
+system; if \fIport\fR is zero, the operating system will allocate a
+free port to the server socket which may be discovered by using
+\fBchan configure\fR to read the \fB\-sockname\fR option). If the host
+supports both, IPv4 and IPv6, the socket will listen on both address
+families. Tcl will automatically accept connections to the given port.
 For each connection Tcl will create a new channel that may be used to
-communicate with the client.  Tcl then invokes \fIcommand\fR
-(properly a command prefix list, see the \fBEXAMPLES\fR below)
-with three additional arguments: the name of the new channel, the
-address, in network address notation, of the client's host, and
-the client's port number.
+communicate with the client.  Tcl then invokes \fIcommand\fR (properly
+a command prefix list, see the \fBEXAMPLES\fR below) with three
+additional arguments: the name of the new channel, the address, in
+network address notation, of the client's host, and the client's port
+number.
 .PP
 The following additional option may also be specified before \fIport\fR:
 .TP
 \fB\-myaddr\fI addr\fR
 .
-\fIAddr\fR gives the domain-style name or numerical IP address of
-the server-side network interface to use for the connection.
-This option may be useful if the server machine has multiple network
-interfaces.  If the option is omitted then the server socket is bound
-to the special address INADDR_ANY so that it can accept connections from
-any interface.
+\fIAddr\fR gives the domain-style name or numerical IP address of the
+server-side network interface to use for the connection.  This option
+may be useful if the server machine has multiple network interfaces.
+If the option is omitted then the server socket is bound to the
+wildcard address so that it can accept connections from any
+interface. If \fIaddr\fR is a domain name that resolves to multiple IP
+addresses that are available on the local machine, the socket will
+listen on all of them.
 .PP
 Server channels cannot be used for input or output; their sole use is to
 accept new client connections. The channels created for each incoming
@@ -131,11 +134,11 @@ will be accepted.
 If \fIport\fR is specified as zero, the operating system will allocate
 an unused port for use as a server socket.  The port number actually
 allocated may be retrieved from the created server socket using the
-\fBfconfigure\fR command to retrieve the \fB\-sockname\fR option as
+\fBchan configure\fR command to retrieve the \fB\-sockname\fR option as
 described below.
 .SH "CONFIGURATION OPTIONS"
 .PP
-The \fBfconfigure\fR command can be used to query several readonly
+The \fBchan configure\fR command can be used to query several readonly
 configuration options for socket channels:
 .TP
 \fB\-error\fR
@@ -147,10 +150,19 @@ returned.  If there was no error, an empty string is returned.
 .TP
 \fB\-sockname\fR
 .
-This option returns a list of three elements, the address, the host name
-and the port number for the socket. If the host name cannot be computed,
-the second element is identical to the address, the first element of the
-list.
+For client sockets (including the channels that get created when a
+client connects to a server socket) this option returns a list of
+three elements, the address, the host name and the port number for the
+socket. If the host name cannot be computed, the second element is
+identical to the address, the first element of the list.
+
+For server sockets this option returns a list of a multiple of three
+elements each group of which have the same meaning as described
+above. The list contains more than one group when the server socket
+was created without \fB-myaddr\fR or with the argument to
+\fB-myaddr\fR being a domain name that resolves multiple IP addresses
+that are local to the invoking host.
+
 .TP
 \fB\-peername\fR
 .
@@ -189,8 +201,10 @@ close $sockChan
 puts "The time on $server is $line1"
 puts "That is [lindex $line2 0]s since the server started"
 .CE
+.SH "HISTORY"
+Support for IPv6 was added in Tcl 8.6.
 .SH "SEE ALSO"
-fconfigure(n), flush(n), open(n), read(n)
+chan(n), flush(n), open(n), read(n)
 .SH KEYWORDS
 asynchronous I/O, bind, channel, connection, domain name, host, network address, socket, tcp
 '\" Local Variables: