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.

       Note that the default encoding for all sockets is the sys-
       tem encoding, as returned by encoding system.  Most of the
       time, you will need to use fconfigure  to  alter  this  to
       something  else,  such  as  utf-8 (ideal for communicating
       with other Tcl processes) or iso8859-1  (useful  for  many
       network protocols, especially the older ones).


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  (or  service  name,  where
       supported and understood by the host operating system) 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 local-
       host 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 (or service
              name, where supported and understood  by  the  host
              operating  system)  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  (either  an
       integer  or a service name, where supported and understood
       by the host operating  system).   Tcl  will  automatically
       accept connections to the given port.  For each connection
       Tcl will create a new channel that may be used to communi-
       cate 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.

       If port is specified as zero, the  operating  system  will
       allocate  an  unused port for use as a server socket.  The
       port number actually allocated my be  retrieved  from  the
       created  server  socket  using  the  fconfigure command to
       retrieve the -sockname option as described below.


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
       fconfigure(n), flush(n), open(n), read(n)


KEYWORDS
       bind, channel,  connection,  domain  name,  host,  network
