2 '\" Copyright (c) 1996 Sun Microsystems, Inc.
3 '\" Copyright (c) 1998-1999 by Scriptics Corporation.
5 '\" See the file "license.terms" for information on usage and redistribution
6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
8 .TH socket n 8.6 Tcl "Tcl Built-In Commands"
9 .\" The -*- nroff -*- definitions below are for supplemental macros used
10 .\" in Tcl/Tk manual entries.
12 .\" .AP type name in/out ?indent?
13 .\" Start paragraph describing an argument to a library procedure.
14 .\" type is type of argument (int, etc.), in/out is either "in", "out",
15 .\" or "in/out" to describe whether procedure reads or modifies arg,
16 .\" and indent is equivalent to second arg of .IP (shouldn't ever be
17 .\" needed; use .AS below instead)
20 .\" Give maximum sizes of arguments for setting tab stops. Type and
21 .\" name are examples of largest possible arguments that will be passed
22 .\" to .AP later. If args are omitted, default tab stops are used.
25 .\" Start box enclosure. From here until next .BE, everything will be
26 .\" enclosed in one large box.
29 .\" End of box enclosure.
32 .\" Begin code excerpt.
37 .\" .VS ?version? ?br?
38 .\" Begin vertical sidebar, for use in marking newly-changed parts
39 .\" of man pages. The first argument is ignored and used for recording
40 .\" the version when the .VS was added, so that the sidebars can be
41 .\" found and removed when they reach a certain age. If another argument
42 .\" is present, then a line break is forced before starting the sidebar.
45 .\" End of vertical sidebar.
48 .\" Begin an indented unfilled display.
51 .\" End of indented unfilled display.
54 .\" Start of list of standard options for a Tk widget. The manpage
55 .\" argument defines where to look up the standard options; if
56 .\" omitted, defaults to "options". The options follow on successive
57 .\" lines, in three columns separated by tabs.
60 .\" End of list of standard options for a Tk widget.
62 .\" .OP cmdName dbName dbClass
63 .\" Start of description of a specific option. cmdName gives the
64 .\" option's name as specified in the class command, dbName gives
65 .\" the option's name in the option database, and dbClass gives
66 .\" the option's class in the option database.
69 .\" Print arg1 underlined, then print arg2 normally.
72 .\" Print arg1 in quotes, then arg2 normally (for trailing punctuation).
75 .\" Print an open parenthesis, arg1 in quotes, then arg2 normally
76 .\" (for trailing punctuation) and then a closing parenthesis.
78 .\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
82 .\" # Start an argument description
86 . ie !"\\$2"" .TP \\n()Cu
91 \&\\$1 \\fI\\$2\\fP (\\$3)
104 .\" # define tabbing values for .AP
107 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
110 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
111 .nr )C \\n()Bu+\\w'(in/out)'u+2n
113 .AS Tcl_Interp Tcl_CreateInterp in/out
114 .\" # BS - start boxed text
115 .\" # ^y = starting y location
123 .if n \l'\\n(.lu\(ul'
126 .\" # BE - end boxed text (draw box now)
131 .ie n \l'\\n(^lu\(ul'
133 .\" Draw four-sided box normally, but don't draw top of
134 .\" box if the box started on an earlier page.
136 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
139 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
146 .\" # VS - start vertical sidebar
147 .\" # ^Y = starting y location
148 .\" # ^v = 1 (for troff; for nroff this doesn't matter)
152 .ie n 'mc \s12\(br\s0
155 .\" # VE - end of vertical sidebar
163 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
170 .\" # Special macro to handle page bottom: finish off current
171 .\" # box/sidebar if in box/sidebar mode, then invoked standard
172 .\" # page bottom macro.
179 .\" Draw three-sided box if this is the box's first page,
180 .\" draw two sides but no top otherwise.
181 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
182 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
185 .nr ^x \\n(^tu+1v-\\n(^Yu
186 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
199 .\" # DS - begin display
205 .\" # DE - end display
211 .\" # SO - start of list of standard options
213 'ie '\\$1'' .ds So \\fBoptions\\fR
214 'el .ds So \\fB\\$1\\fR
215 .SH "STANDARD OPTIONS"
221 .\" # SE - end of list of standard options
226 See the \\*(So manual entry for details on the standard options.
228 .\" # OP - start of full description for a single option
233 Command-Line Name: \\fB\\$1\\fR
234 Database Name: \\fB\\$2\\fR
235 Database Class: \\fB\\$3\\fR
239 .\" # CS - begin code excerpt
245 .\" # CE - end code excerpt
250 .\" # UL - underline word
254 .\" # QW - apply quotation marks to word
256 .ie '\\*(lq'"' ``\\$1''\\$2
257 .\"" fix emacs highlighting
258 .el \\*(lq\\$1\\*(rq\\$2
260 .\" # PQ - apply parens and quotation marks to word
262 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
263 .\"" fix emacs highlighting
264 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
266 .\" # QR - quoted range
268 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
269 .\"" fix emacs highlighting
270 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
272 .\" # MT - "empty" string
277 '\" Note: do not modify the .SH NAME line immediately below!
279 socket \- Open a TCP network connection
282 \fBsocket \fR?\fIoptions\fR? \fIhost port\fR
284 \fBsocket\fR \fB\-server \fIcommand\fR ?\fIoptions\fR? \fIport\fR
288 This command opens a network socket and returns a channel identifier
289 that may be used in future invocations of commands like \fBread\fR,
290 \fBputs\fR and \fBflush\fR. At present only the TCP network protocol
291 is supported over IPv4 and IPv6; future releases may include support
292 for additional protocols. The \fBsocket\fR command may be used to
293 open either the client or server side of a connection, depending on
294 whether the \fB\-server\fR switch is specified.
296 Note that the default encoding for \fIall\fR sockets is the system
297 encoding, as returned by \fBencoding system\fR. Most of the time, you
298 will need to use \fBchan configure\fR to alter this to something else,
299 such as \fIutf\-8\fR (ideal for communicating with other Tcl
300 processes) or \fIiso8859\-1\fR (useful for many network protocols,
301 especially the older ones).
304 If the \fB\-server\fR option is not specified, then the client side of a
305 connection is opened and the command returns a channel identifier
306 that can be used for both reading and writing.
307 \fIPort\fR and \fIhost\fR specify a port
308 to connect to; there must be a server accepting connections on
309 this port. \fIPort\fR is an integer port number
310 (or service name, where supported and understood by the host operating
311 system) and \fIhost\fR
312 is either a domain-style name such as \fBwww.tcl.tk\fR or
313 a numerical IPv4 or IPv6 address such as \fB127.0.0.1\fR or \fB2001:DB8::1\fR.
314 Use \fIlocalhost\fR to refer to the host on which the command is invoked.
316 The following options may also be present before \fIhost\fR
317 to specify additional information about the connection:
319 \fB\-myaddr\fI addr\fR
321 \fIAddr\fR gives the domain-style name or numerical IP address of
322 the client-side network interface to use for the connection.
323 This option may be useful if the client machine has multiple network
324 interfaces. If the option is omitted then the client-side interface
325 will be chosen by the system software.
327 \fB\-myport\fI port\fR
329 \fIPort\fR specifies an integer port number (or service name, where
330 supported and understood by the host operating system) to use for the
332 side of the connection. If this option is omitted, the client's
333 port number will be chosen at random by the system software.
337 This option will cause the client socket to be connected
338 asynchronously. This means that the socket will be created immediately
339 but may not yet be connected to the server, when the call to
340 \fBsocket\fR returns.
343 When a \fBgets\fR or \fBflush\fR is done on the socket before the
344 connection attempt succeeds or fails, if the socket is in blocking
345 mode, the operation will wait until the connection is completed or
346 fails. If the socket is in nonblocking mode and a \fBgets\fR or
347 \fBflush\fR is done on the socket before the connection attempt
348 succeeds or fails, the operation returns immediately and
349 \fBfblocked\fR on the socket returns 1. Synchronous client sockets may
350 be switched (after they have connected) to operating in asynchronous
354 \fBchan configure \fIchan \fB\-blocking 0\fR
357 See the \fBchan configure\fR command for more details.
359 The Tcl event loop should be running while an asynchronous connection
360 is in progress, because it may have to do several connection attempts
361 in the background. Running the event loop also allows you to set up a
362 writable channel event on the socket to get notified when the
363 asynchronous connection has succeeded or failed. See the \fBvwait\fR
364 and the \fBchan\fR commands for more details on the event loop and
367 The \fBchan configure\fR option \fB-connecting\fR may be used to check if the connect is still running. To verify a successful connect, the option \fB-error\fR may be checked when \fB-connecting\fR returned 0.
369 Operation without the event queue requires at the moment calls to \fBchan configure\fR to advance the internal state machine.
373 If the \fB\-server\fR option is specified then the new socket will be
374 a server that listens on the given \fIport\fR (either an integer or a
375 service name, where supported and understood by the host operating
376 system; if \fIport\fR is zero, the operating system will allocate a
377 free port to the server socket which may be discovered by using
378 \fBchan configure\fR to read the \fB\-sockname\fR option). If the host
379 supports both, IPv4 and IPv6, the socket will listen on both address
380 families. Tcl will automatically accept connections to the given port.
381 For each connection Tcl will create a new channel that may be used to
382 communicate with the client. Tcl then invokes \fIcommand\fR (properly
383 a command prefix list, see the \fBEXAMPLES\fR below) with three
384 additional arguments: the name of the new channel, the address, in
385 network address notation, of the client's host, and the client's port
388 The following additional option may also be specified before \fIport\fR:
390 \fB\-myaddr\fI addr\fR
392 \fIAddr\fR gives the domain-style name or numerical IP address of the
393 server-side network interface to use for the connection. This option
394 may be useful if the server machine has multiple network interfaces.
395 If the option is omitted then the server socket is bound to the
396 wildcard address so that it can accept connections from any
397 interface. If \fIaddr\fR is a domain name that resolves to multiple IP
398 addresses that are available on the local machine, the socket will
399 listen on all of them.
401 Server channels cannot be used for input or output; their sole use is to
402 accept new client connections. The channels created for each incoming
403 client connection are opened for input and output. Closing the server
404 channel shuts down the server so that no new connections will be
405 accepted; however, existing connections will be unaffected.
407 Server sockets depend on the Tcl event mechanism to find out when
408 new connections are opened. If the application does not enter the
409 event loop, for example by invoking the \fBvwait\fR command or
410 calling the C procedure \fBTcl_DoOneEvent\fR, then no connections
413 If \fIport\fR is specified as zero, the operating system will allocate
414 an unused port for use as a server socket. The port number actually
415 allocated may be retrieved from the created server socket using the
416 \fBchan configure\fR command to retrieve the \fB\-sockname\fR option as
418 .SH "CONFIGURATION OPTIONS"
420 The \fBchan configure\fR command can be used to query several readonly
421 configuration options for socket channels:
425 This option gets the current error status of the given socket. This
426 is useful when you need to determine if an asynchronous connect
427 operation succeeded. If there was an error, the error message is
428 returned. If there was no error, an empty string is returned.
431 Note that the error status is reset by the read operation; this mimics
432 the underlying getsockopt(SO_ERROR) call.
437 For client sockets (including the channels that get created when a
438 client connects to a server socket) this option returns a list of
439 three elements, the address, the host name and the port number for the
440 socket. If the host name cannot be computed, the second element is
441 identical to the address, the first element of the list.
444 For server sockets this option returns a list of a multiple of three
445 elements each group of which have the same meaning as described
446 above. The list contains more than one group when the server socket
447 was created without \fB\-myaddr\fR or with the argument to
448 \fB\-myaddr\fR being a domain name that resolves multiple IP addresses
449 that are local to the invoking host.
454 This option is not supported by server sockets. For client and accepted
455 sockets, this option returns a list of three elements; these are the
456 address, the host name and the port to which the peer socket is connected
457 or bound. If the host name cannot be computed, the second element of the
458 list is identical to the address, its first element.
462 This option is not supported by server sockets. For client sockets, this option returns 1 if an asyncroneous connect is still in progress, 0 otherwise.
466 Here is a very simple time server:
469 proc Server {startTime channel clientaddr clientport} {
470 puts "Connection from $clientaddr registered"
471 set now [clock seconds]
472 puts $channel [clock format $now]
473 puts $channel "[expr {$now - $startTime}] since start"
477 \fBsocket -server\fR [list Server [clock seconds]] 9900
481 And here is the corresponding client to talk to the server and extract
486 set sockChan [\fBsocket\fR $server 9900]
490 puts "The time on $server is $line1"
491 puts "That is [lindex $line2 0]s since the server started"
494 Support for IPv6 was added in Tcl 8.6.
496 chan(n), flush(n), open(n), read(n)
498 asynchronous I/O, bind, channel, connection, domain name, host, network address, socket, tcp
OSDN Git Service
