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
16

DESCRIPTION

18       This  command  opens  a network socket and returns a channel identifier
19       that may be used in future invocations of commands like read, puts  and
20       flush.   At present only the TCP network protocol is supported;  future
21       releases may include support for additional protocols.  The socket com‐
22       mand  may be used to open either the client or server side of a connec‐
23       tion, depending on whether the -server switch is specified.
24
25       Note that the default encoding for all sockets is the system  encoding,
26       as returned by encoding system.  Most of the time, you will need to use
27       fconfigure to alter this to something else, such as  utf-8  (ideal  for
28       communicating  with  other Tcl processes) or iso8859-1 (useful for many
29       network protocols, especially the older ones).
30

CLIENT SOCKETS

32       If the -server option is not specified, then the client side of a  con‐
33       nection is opened and the command returns a channel identifier that can
34       be used for both reading and writing.  Port and host specify a port  to
35       connect to;  there must be a server accepting connections on this port.
36       Port is an integer port number (or service name,  where  supported  and
37       understood  by  the host operating system) and host is either a domain-
38       style name such as  www.tcl.tk  or  a  numerical  IP  address  such  as
39       127.0.0.1.   Use localhost to refer to the host on which the command is
40       invoked.
41
42       The following options may also be present before host to specify  addi‐
43       tional information about the connection:
44
45       -myaddr addr
46              Addr  gives the domain-style name or numerical IP address of the
47              client-side network interface to use for the  connection.   This
48              option  may be useful if the client machine has multiple network
49              interfaces.  If the  option  is  omitted  then  the  client-side
50              interface will be chosen by the system software.
51
52       -myport port
53              Port  specifies  an  integer port number (or service name, where
54              supported and understood by the host operating  system)  to  use
55              for  the  client's  side  of  the connection.  If this option is
56              omitted, the client's port number will be chosen  at  random  by
57              the system software.
58
59       -async The  -async  option will cause the client socket to be connected
60              asynchronously. This means that the socket will be created imme‐
61              diately  but  may  not  yet be connected to the server, when the
62              call to socket returns. When a gets or  flush  is  done  on  the
63              socket  before  the connection attempt succeeds or fails, if the
64              socket is in blocking mode, the operation will  wait  until  the
65              connection  is completed or fails. If the socket is in nonblock‐
66              ing mode and a gets or flush is done on the  socket  before  the
67              connection  attempt  succeeds  or  fails,  the operation returns
68              immediately and fblocked on the socket  returns  1.  Synchronous
69              client  sockets  may  be switched (after they have connected) to
70              operating in asynchronous mode using:
71                     fconfigure chan -blocking 0
72
73              See the fconfigure command for more details.
74

SERVER SOCKETS

76       If the -server option is specified then the new socket will be a server
77       for  the port given by port (either an integer or a service name, where
78       supported and understood by the host operating system; if port is zero,
79       the  operating  system  will  allocate a free port to the server socket
80       which may be discovered by  using  fconfigure  to  read  the  -sockname
81       option).   Tcl will automatically accept connections to the given port.
82       For each connection Tcl will create a new channel that may be  used  to
83       communicate with the client.  Tcl then invokes command with three addi‐
84       tional arguments: the name of the new channel, the address, in  network
85       address notation, of the client's host, and the client's port number.
86
87       The following additional option may also be specified before host:
88
89       -myaddr addr
90              Addr  gives the domain-style name or numerical IP address of the
91              server-side network interface to use for the  connection.   This
92              option  may be useful if the server machine has multiple network
93              interfaces.  If the option is omitted then the server socket  is
94              bound  to  the  special address INADDR_ANY so that it can accept
95              connections from any interface.
96
97       Server channels cannot be used for input or output; their sole  use  is
98       to  accept new client connections. The channels created for each incom‐
99       ing client connection are opened for  input  and  output.  Closing  the
100       server channel shuts down the server so that no new connections will be
101       accepted;  however, existing connections will be unaffected.
102
103       Server sockets depend on the Tcl event mechanism to find out  when  new
104       connections  are  opened.   If the application does not enter the event
105       loop, for example by invoking the vwait command or calling the C proce‐
106       dure Tcl_DoOneEvent, then no connections will be accepted.
107
108       If  port  is  specified  as zero, the operating system will allocate an
109       unused port for use as a server socket.  The port number actually allo‐
110       cated  may  be retrieved from the created server socket using the fcon‐
111       figure command to retrieve the -sockname option as described below.
112

CONFIGURATION OPTIONS

114       The fconfigure command can be used to query several readonly configura‐
115       tion options for socket channels:
116
117       -error This  option  gets the current error status of the given socket.
118              This is useful when you need to  determine  if  an  asynchronous
119              connect  operation  succeeded.  If there was an error, the error
120              message is returned.  If there was no error, an empty string  is
121              returned.
122
123       -sockname
124              This  option  returns a list of three elements, the address, the
125              host name and the port number for the socket. If the  host  name
126              cannot  be  computed,  the  second  element  is identical to the
127              address, the first element of the list.
128
129       -peername
130              This option is not supported by server sockets. For  client  and
131              accepted  sockets, this option returns a list of three elements;
132              these are the address, the host name and the port to  which  the
133              peer  socket  is  connected or bound. If the host name cannot be
134              computed, the second element of the list  is  identical  to  the
135              address, its first element.
136

EXAMPLES

138       Here is a very simple time server:
139              proc Server {channel clientaddr clientport} {
140                 puts "Connection from $clientaddr registered"
141                 puts $channel [clock format [clock seconds]]
142                 close $channel
143              }
144
145              socket -server Server 9900
146              vwait forever
147
148       And here is the corresponding client to talk to the server:
149              set server localhost
150              set sockChan [socket $server 9900]
151              gets $sockChan line
152              close $sockChan
153              puts "The time on $server is $line"
154
155

SEE ALSO

157       fconfigure(n), flush(n), open(n), read(n)
158
159

KEYWORDS

161       bind,  channel, connection, domain name, host, network address, socket,
162       tcp
163
164
165
166Tcl                                   8.0                            socket(n)
Impressum