summaryrefslogtreecommitdiffstats
path: root/doc/socket.n
diff options
context:
space:
mode:
Diffstat (limited to 'doc/socket.n')
-rw-r--r--doc/socket.n17
1 files changed, 13 insertions, 4 deletions
diff --git a/doc/socket.n b/doc/socket.n
index bb14993..45e2986 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.15 2007/12/13 15:22:33 dgp Exp $
+'\" RCS: @(#) $Id: socket.n,v 1.16 2008/10/17 10:22:25 dkf Exp $
.so man.macros
.TH socket n 8.0 Tcl "Tcl Built-In Commands"
.BS
@@ -18,7 +18,6 @@ socket \- Open a TCP network connection
.sp
\fBsocket\fR \fB\-server \fIcommand\fR ?\fIoptions\fR? \fIport\fR
.BE
-
.SH DESCRIPTION
.PP
This command opens a network socket and returns a channel
@@ -54,6 +53,7 @@ The following options may also be present before \fIhost\fR
to specify additional information about the connection:
.TP
\fB\-myaddr\fI addr\fR
+.
\fIAddr\fR gives the domain-style name or numerical IP address of
the client-side network interface to use for the connection.
This option may be useful if the client machine has multiple network
@@ -61,6 +61,7 @@ interfaces. If the option is omitted then the client-side interface
will be chosen by the system software.
.TP
\fB\-myport\fI port\fR
+.
\fIPort\fR specifies an integer port number (or service name, where
supported and understood by the host operating system) to use for the
client's
@@ -68,6 +69,7 @@ side of the connection. If this option is omitted, the client's
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
@@ -80,6 +82,7 @@ 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
.CE
@@ -104,6 +107,7 @@ the client's port number.
The following additional option may also be specified before \fIhost\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
@@ -129,22 +133,26 @@ 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"
+.PP
The \fBfconfigure\fR command can be used to query several readonly
configuration options for socket channels:
.TP
\fB\-error\fR
+.
This option gets the current error status of the given socket. This
is useful when you need to determine if an asynchronous connect
operation succeeded. If there was an error, the error message is
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.
.TP
\fB\-peername\fR
+.
This option is not supported by server sockets. For client and accepted
sockets, this option returns a list of three elements; these are the
address, the host name and the port to which the peer socket is connected
@@ -152,7 +160,9 @@ 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"
+.PP
Here is a very simple time server:
+.PP
.CS
proc Server {channel clientaddr clientport} {
puts "Connection from $clientaddr registered"
@@ -165,6 +175,7 @@ vwait forever
.CE
.PP
And here is the corresponding client to talk to the server:
+.PP
.CS
set server localhost
set sockChan [\fBsocket\fR $server 9900]
@@ -172,9 +183,7 @@ gets $sockChan line
close $sockChan
puts "The time on $server is $line"
.CE
-
.SH "SEE ALSO"
fconfigure(n), flush(n), open(n), read(n)
-
.SH KEYWORDS
bind, channel, connection, domain name, host, network address, socket, tcp