tcl7.6 User Commands - socket






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 command may be
     used  to  open either the client or server side of a connec-
     tion, 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  con-
          nected  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 automati-
     cally accept connections to the given port.  For  each  con-
     nection  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;   how-
     ever, 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 com-
     mand or calling the C procedure Tcl_DoOneEvent, then no con-
     nections will be accepted.



CONFIGURATION OPTIONS

     The fconfigure command can be used to query several readonly
     configuration options for socket channels:
     -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 computed, 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