diff options
Diffstat (limited to 'doc/socket.n')
| -rw-r--r-- | doc/socket.n | 78 |
1 files changed, 63 insertions, 15 deletions
diff --git a/doc/socket.n b/doc/socket.n index 8c269db..7050429 100644 --- a/doc/socket.n +++ b/doc/socket.n @@ -5,9 +5,8 @@ '\" 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.5 1999/08/21 19:40:48 hobbs Exp $ -.so man.macros .TH socket n 8.0 Tcl "Tcl Built-In Commands" +.so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME @@ -29,7 +28,13 @@ 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, +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 @@ -37,8 +42,10 @@ connection is opened and the command returns a channel identifier that can be used for both reading and writing. \fIPort\fR and \fIhost\fR specify a port to connect to; there must be a server accepting connections on -this port. \fIPort\fR is an integer port number and \fIhost\fR -is either a domain-style name such as \fBwww.sunlabs.com\fR or +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. Use \fIlocalhost\fR to refer to the host on which the command is invoked. .PP @@ -53,7 +60,9 @@ 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 to use for the client's +\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 side of the connection. If this option is omitted, the client's port number will be chosen at random by the system software. .TP @@ -66,12 +75,24 @@ 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. - +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 +.CS +\fBfconfigure \fIchan \fB\-blocking 0\fR +.CE +.PP +See the \fBfconfigure\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. +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. For each connection Tcl will create a new channel that may be used to communicate with the client. Tcl then invokes \fIcommand\fR @@ -79,7 +100,7 @@ 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 \fIhost\fR: +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 @@ -96,22 +117,28 @@ channel shuts down the server so that no new connections will be accepted; however, existing connections will be unaffected. .PP Server sockets depend on the Tcl event mechanism to find out when -new connections are opened. If the application doesn't enter the +new connections are opened. If the application does not enter the event loop, for example by invoking the \fBvwait\fR command or calling the C procedure \fBTcl_DoOneEvent\fR, then no connections 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 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: -.VS 8.0.5 .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. -.VE 8.0.5 + +Note that the error status is reset by the read operation; this mimics +the underlying getsockopt(SO_ERROR) call. .TP \fB\-sockname\fR This option returns a list of three elements, the address, the host name @@ -126,9 +153,30 @@ 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" -flush(n), open(n), read(n) +fconfigure(n), flush(n), open(n), read(n) .SH KEYWORDS bind, channel, connection, domain name, host, network address, socket, tcp |