1socket(n) Tcl Built-In Commands socket(n)
2______________________________________________________________________________
6
8 socket - Open a TCP network connection
9
11 socket ?options? host port
12 socket -server command ?options? port
14______________________________________________________________________________
15
17 This command opens a network socket and returns a channel identifier
18 that may be used in future invocations of commands like read, puts and
19 flush. At present only the TCP network protocol is supported over IPv4
20 and IPv6; future releases may include support for additional protocols.
21 The socket command may be used to open either the client or server side
22 of a connection, depending on whether the -server switch is specified.
23 Note that the default encoding for all sockets is the system encoding,
25 as returned by encoding system. Most of the time, you will need to use
26 chan configure to alter this to something else, such as utf-8 (ideal
27 for communicating with other Tcl processes) or iso8859-1 (useful for
28 many network protocols, especially the older ones).
29
31 If the -server option is not specified, then the client side of a con‐
32 nection is opened and the command returns a channel identifier that can
33 be used for both reading and writing. Port and host specify a port to
34 connect to; there must be a server accepting connections on this port.
35 Port is an integer port number (or service name, where supported and
36 understood by the host operating system) and host is either a domain-
37 style name such as www.tcl.tk or a numerical IPv4 or IPv6 address such
38 as 127.0.0.1 or 2001:DB8::1. Use localhost to refer to the host on
39 which the command is invoked.
40 The following options may also be present before host to specify addi‐
42 tional information about the connection:
43 -myaddr addr
45 Addr gives the domain-style name or numerical IP address of the
46 client-side network interface to use for the connection. This
47 option may be useful if the client machine has multiple network
48 interfaces. If the option is omitted then the client-side
49 interface will be chosen by the system software.
50 -myport port
52 Port specifies an integer port number (or service name, where
53 supported and understood by the host operating system) to use
54 for the client's side of the connection. If this option is
55 omitted, the client's port number will be chosen at random by
56 the system software.
57 -async This option will cause the client socket to be connected asyn‐
59 chronously. This means that the socket will be created immedi‐
60 ately but may not yet be connected to the server, when the call
61 to socket returns.
62 When a gets or flush is done on the socket before the connection
64 attempt succeeds or fails, if the socket is in blocking mode,
65 the operation will wait until the connection is completed or
66 fails. If the socket is in nonblocking mode and a gets or flush
67 is done on the socket before the connection attempt succeeds or
68 fails, the operation returns immediately and fblocked on the
69 socket returns 1. Synchronous client sockets may be switched
70 (after they have connected) to operating in asynchronous mode
71 using:
72 chan configure chan -blocking 0
74 See the chan configure command for more details.
76 The Tcl event loop should be running while an asynchronous con‐
78 nection is in progress, because it may have to do several con‐
79 nection attempts in the background. Running the event loop also
80 allows you to set up a writable channel event on the socket to
81 get notified when the asynchronous connection has succeeded or
82 failed. See the vwait and the chan commands for more details on
83 the event loop and channel events.
84 The chan configure option -connecting may be used to check if
86 the connect is still running. To verify a successful connect,
87 the option -error may be checked when -connecting returned 0.
88 Operation without the event queue requires at the moment calls
90 to chan configure to advance the internal state machine.
91
93 If the -server option is specified then the new socket will be a server
94 that listens on the given port (either an integer or a service name,
95 where supported and understood by the host operating system; if port is
96 zero, the operating system will allocate a free port to the server
97 socket which may be discovered by using chan configure to read the
98 -sockname option). If the host supports both, IPv4 and IPv6, the socket
99 will listen on both address families. Tcl will automatically accept
100 connections to the given port. For each connection Tcl will create a
101 new channel that may be used to communicate with the client. Tcl then
102 invokes command (properly a command prefix list, see the EXAMPLES
103 below) with three additional arguments: the name of the new channel,
104 the address, in network address notation, of the client's host, and the
105 client's port number.
106 The following additional option may also be specified before port:
108 -myaddr addr
110 Addr gives the domain-style name or numerical IP address of the
111 server-side network interface to use for the connection. This
112 option may be useful if the server machine has multiple network
113 interfaces. If the option is omitted then the server socket is
114 bound to the wildcard address so that it can accept connections
115 from any interface. If addr is a domain name that resolves to
116 multiple IP addresses that are available on the local machine,
117 the socket will listen on all of them.
118 Server channels cannot be used for input or output; their sole use is
120 to accept new client connections. The channels created for each incom‐
121 ing client connection are opened for input and output. Closing the
122 server channel shuts down the server so that no new connections will be
123 accepted; however, existing connections will be unaffected.
124 Server sockets depend on the Tcl event mechanism to find out when new
126 connections are opened. If the application does not enter the event
127 loop, for example by invoking the vwait command or calling the C proce‐
128 dure Tcl_DoOneEvent, then no connections will be accepted.
129 If port is specified as zero, the operating system will allocate an
131 unused port for use as a server socket. The port number actually allo‐
132 cated may be retrieved from the created server socket using the chan
133 configure command to retrieve the -sockname option as described below.
134
136 The chan configure command can be used to query several readonly con‐
137 figuration options for socket channels:
138 -error This option gets the current error status of the given socket.
140 This is useful when you need to determine if an asynchronous
141 connect operation succeeded. If there was an error, the error
142 message is returned. If there was no error, an empty string is
143 returned.
144 Note that the error status is reset by the read operation; this
146 mimics the underlying getsockopt(SO_ERROR) call.
147 -sockname
149 For client sockets (including the channels that get created when
150 a client connects to a server socket) this option returns a list
151 of three elements, the address, the host name and the port num‐
152 ber for the socket. If the host name cannot be computed, the
153 second element is identical to the address, the first element of
154 the list.
155 For server sockets this option returns a list of a multiple of
157 three elements each group of which have the same meaning as
158 described above. The list contains more than one group when the
159 server socket was created without -myaddr or with the argument
160 to -myaddr being a domain name that resolves multiple IP
161 addresses that are local to the invoking host.
162 -peername
164 This option is not supported by server sockets. For client and
165 accepted sockets, this option returns a list of three elements;
166 these are the address, the host name and the port to which the
167 peer socket is connected or bound. If the host name cannot be
168 computed, the second element of the list is identical to the
169 address, its first element.
170 -connecting
172 This option is not supported by server sockets. For client sock‐
173 ets, this option returns 1 if an asyncroneous connect is still
174 in progress, 0 otherwise.
175
177 Here is a very simple time server:
178 proc Server {startTime channel clientaddr clientport} {
180 puts "Connection from $clientaddr registered"
181 set now [clock seconds]
182 puts $channel [clock format $now]
183 puts $channel "[expr {$now - $startTime}] since start"
184 close $channel
185 }
186 socket -server [list Server [clock seconds]] 9900
188 vwait forever
189 And here is the corresponding client to talk to the server and extract
191 some information:
192 set server localhost
194 set sockChan [socket $server 9900]
195 gets $sockChan line1
196 gets $sockChan line2
197 close $sockChan
198 puts "The time on $server is $line1"
199 puts "That is [lindex $line2 0]s since the server started"
200
202 Support for IPv6 was added in Tcl 8.6.
203
205 chan(n), flush(n), open(n), read(n)
206
208 asynchronous I/O, bind, channel, connection, domain name, host, network
209 address, socket, tcp
210Tcl 8.6 socket(n)