1socket(n)                    Tcl Built-In Commands                   socket(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       socket - Open a TCP network connection
9

SYNOPSIS

11       socket ?options? host port
12
13       socket -server command ?options? port
14______________________________________________________________________________
15

DESCRIPTION

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
24       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

CLIENT SOCKETS

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
41       The following options may also be present before host to specify  addi‐
42       tional information about the connection:
43
44       -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
51       -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
58       -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
63              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
73                     chan configure chan -blocking 0
74
75              See the chan configure command for more details.
76
77              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
85              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
89              Operation without the event queue requires at the  moment  calls
90              to chan configure to advance the internal state machine.
91

SERVER SOCKETS

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
107       The following additional option may also be specified before port:
108
109       -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
119       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
125       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
130       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

CONFIGURATION OPTIONS

136       The chan configure command can be used to query several  readonly  con‐
137       figuration options for socket channels:
138
139       -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
145              Note  that the error status is reset by the read operation; this
146              mimics the underlying getsockopt(SO_ERROR) call.
147
148       -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
156              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
163       -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
171       -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

EXAMPLES

177       Here is a very simple time server:
178
179              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
187              socket -server [list Server [clock seconds]] 9900
188              vwait forever
189
190       And  here is the corresponding client to talk to the server and extract
191       some information:
192
193              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

HISTORY

202       Support for IPv6 was added in Tcl 8.6.
203

SEE ALSO

205       chan(n), flush(n), open(n), read(n)
206

KEYWORDS

208       asynchronous I/O, bind, channel, connection, domain name, host, network
209       address, socket, tcp
210
211
212
213Tcl                                   8.6                            socket(n)
Impressum