Yet more doc update backporting

1 files changed, 27 insertions, 7 deletions

diff --git a/doc/socket.n b/doc/socket.n
index ba0feb5..21dd33c 100644
--- a/doc/socket.n
+++ b/doc/socket.n
@@ -5,7 +5,7 @@
 '\" 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.7.2.2 2003/05/15 18:41:06 hobbs Exp $
+'\" RCS: @(#) $Id: socket.n,v 1.7.2.3 2004/10/27 14:23:58 dkf Exp $
 .so man.macros
 .TH socket n 8.0 Tcl "Tcl Built-In Commands"
 .BS
@@ -36,7 +36,6 @@ will need to use \fBfconfigure\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).
-
 .SH "CLIENT SOCKETS"
 .PP
 If the \fB\-server\fR option is not specified, then the client side of a
@@ -47,7 +46,7 @@ to connect to;  there must be a server accepting connections on
 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.sunlabs.com\fR or
+is either a domain-style name such as \fBwww.tcl.tk\fR or
 a numerical IP address such as \fB127.0.0.1\fR.
 Use \fIlocalhost\fR to refer to the host on which the command is invoked.
 .PP
@@ -78,13 +77,14 @@ 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.
-
 .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).
+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.
 For each connection Tcl will create a new channel that may be used to
 communicate with the client.  Tcl then invokes \fIcommand\fR
@@ -116,10 +116,9 @@ will be accepted.
 .PP
 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 my be retrieved from the created server socket using the
+allocated may be retrieved from the created server socket using the
 \fBfconfigure\fR command to retrieve the \fB\-sockname\fR option as
 described below.
-
 .SH "CONFIGURATION OPTIONS"
 The \fBfconfigure\fR command can be used to query several readonly
 configuration options for socket channels:
@@ -143,6 +142,27 @@ address, the host name and the port to which the peer socket is connected
 or bound. If the host name cannot be computed, the second element of the
 list is identical to the address, its first element.
 .PP
+.SH "EXAMPLES"
+Here is a very simple time server:
+.CS
+proc Server {channel clientaddr clientport} {
+   puts "Connection from $clientaddr registered"
+   puts $channel [clock format [clock seconds]]
+   close $channel
+}
+
+\fBsocket\fR -server Server 9900
+vwait forever
+.CE
+.PP
+And here is the corresponding client to talk to the server:
+.CS
+set server localhost
+set sockChan [\fBsocket\fR $server 9900]
+gets $sockChan line
+close $sockChan
+puts "The time on $server is $line"
+.CE
 
 .SH "SEE ALSO"
 fconfigure(n), flush(n), open(n), read(n)