1mNAME0m
       socket - Open a TCP network connection

1mSYNOPSIS0m
       1msocket 22m?4moptions24m? 4mhost24m 4mport0m

       1msocket -server 4m22mcommand24m ?4moptions24m? 4mport0m


1mDESCRIPTION0m
       This  command  opens  a network socket and returns a channel identifier
       that may be used in future invocations of commands like 1mread22m, 1mputs  22mand
       1mflush22m.   At present only the TCP network protocol is supported;  future
       releases may include support for additional protocols.  The 1msocket 22mcom-
       mand  may be used to open either the client or server side of a connec-
       tion, depending on whether the 1m-server 22mswitch is specified.


1mCLIENT SOCKETS0m
       If the 1m-server 22moption is not specified, then the client side of a  con-
       nection is opened and the command returns a channel identifier that can
       be used for both reading and writing.  4mPort24m and 4mhost24m specify a port  to
       connect to;  there must be a server accepting connections on this port.
       4mPort24m is an integer port number and 4mhost24m is either a  domain-style  name
       such  as  1mwww.sunlabs.com  22mor a numerical IP address such as 1m127.0.0.122m.
       Use 4mlocalhost24m to refer to the host on which the command is invoked.

       The following options may also be present before 4mhost24m to specify  addi-
       tional information about the connection:

       1m-myaddr 4m22maddr0m
              4mAddr24m  gives the domain-style name or numerical IP address of the
              client-side network interface to use for the  connection.   This
              option  may be useful if the client machine has multiple network
              interfaces.  If the  option  is  omitted  then  the  client-side
              interface will be chosen by the system software.

       1m-myport 4m22mport0m
              4mPort24m  specifies  an  integer port number 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.

       1m-async 22mThe  1m-async  22moption will cause the client socket to be connected
              asynchronously. This means that the socket will be created imme-
              diately  but  may  not  yet be connected to the server, when the
              call to 1msocket 22mreturns. When a 1mgets 22mor  1mflush  22mis  done  on  the
              socket  before  the 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 nonblock-
              ing mode and a 1mgets 22mor 1mflush 22mis done on the  socket  before  the
              connection  attempt  succeeds  or  fails,  the operation returns
              immediately and 1mfblocked 22mon the socket returns 1.


1mSERVER SOCKETS0m
       If the 1m-server 22moption is specified then the new socket will be a server
       for  the port given by 4mport24m.  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 4mcom-0m
       4mmand24m 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.

       The following additional option may also be specified before 4mhost24m:

       1m-myaddr 4m22maddr0m
              4mAddr24m gives the domain-style name or numerical IP address of  the
              server-side  network  interface to use for the connection.  This
              option may be useful if the server machine has multiple  network
              interfaces.   If the option is omitted then the server socket is
              bound to the special address INADDR_ANY so that  it  can  accept
              connections from any interface.

       Server  channels  cannot be used for input or output; their sole use is
       to accept new client connections. The channels created for each  incom-
       ing  client  connection  are  opened  for input and output. Closing the
       server channel shuts down the server so that no new connections will be
       accepted;  however, existing connections will be unaffected.

       Server  sockets  depend on the Tcl event mechanism to find out when new
       connections are opened.  If the application  doesn't  enter  the  event
       loop, for example by invoking the 1mvwait 22mcommand or calling the C proce-
       dure 1mTcl_DoOneEvent22m, then no connections will be accepted.


1mCONFIGURATION OPTIONS0m
       The 1mfconfigure 22mcommand can be used to query several readonly configura-
       tion options for socket channels:

       1m-error 22mThis  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.

       1m-sockname0m
              This  option  returns a list of three elements, the address, the
              host name and the port number for the socket. If the  host  name
              cannot  be  computed,  the  second  element  is identical to the
              address, the first element of the list.

       1m-peername0m
              This option is not supported by server sockets. For  client  and
              accepted  sockets, this option returns a list of three elements;
              these are the 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.



1mSEE ALSO0m
       flush(n), open(n), read(n)


1mKEYWORDS0m
       bind,  channel, connection, domain name, host, network address, socket,
