NAME
       socket - Open a TCP network connection

SYNOPSIS
       socket ?options? host port

       socket -server command ?options? port


DESCRIPTION
       This  command opens a network socket and returns a channel
       identifier that may be used in future invocations of  com-
       mands  like read, puts and flush.  At present only the TCP
       network  protocol  is  supported;   future  releases   may
       include support for additional protocols.  The socket com-
       mand may be used to open either the client or server  side
       of  a  connection, depending on whether the -server switch
       is specified.


CLIENT SOCKETS
       If the -server option is not specified,  then  the  client
       side  of  a connection is opened and the command returns a
       channel identifier that can be used for both  reading  and
       writing.   Port  and  host  specify  a port to connect to;
       there must be a server accepting connections on this port.
       Port  is  an  integer  port  number  and  host is either a
       domain-style name such as www.sunlabs.com or  a  numerical
       IP  address  such as 127.0.0.1.  Use localhost to refer to
       the host on which the command is invoked.

       The following options may also be present before  host  to
       specify additional information about the connection:

       -myaddr addr
              Addr  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.

       -myport port
              Port 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.

       -async The  -async  option will cause the client socket to
              be connected asynchronously. This  means  that  the
              socket  will be created immediately but may not yet
              be connected to the server, when the call to socket
              returns. When a gets or flush is 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  nonblocking mode and a gets or
              flush is done on the socket before  the  connection
              attempt  succeeds  or  fails, the operation returns
              immediately and fblocked on the socket returns 1.


SERVER SOCKETS
       If the -server option is specified  then  the  new  socket
       will  be  a  server  for the port given by port.  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
       command  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 host:

       -myaddr addr
              Addr 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 incoming 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
       vwait command or calling the C  procedure  Tcl_DoOneEvent,
       then no connections will be accepted.


CONFIGURATION OPTIONS
       The  fconfigure command can be used to query several read-
       only configuration options for socket channels:

       -error This option gets the current error  status  of  the
              given  socket.   This  is  useful  when you need to
              determine if an asynchronous connect operation suc-
              ceeded.   If  there was an error, the error message
              is returned.  If  there  was  no  error,  an  empty
              string is returned.
       -sockname
              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.

       -peername
              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 com-
              puted, the second element of the list is  identical
              to the address, its first element.



SEE ALSO
       flush(n), open(n), read(n)


KEYWORDS
       bind,  channel,  connection,  domain  name,  host, network
       address, socket, tcp
