Manual Pages for UNIX Operating System command usage for man socket

Tcl Built-In Commands                                  socket(1T)



_________________________________________________________________

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.

     Note that the default encoding for all sockets is the system
     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.tcl.tk 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



Tcl                     Last change: 8.0                        1






Tcl Built-In Commands                                  socket(1T)



          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  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 (either an integer or
     a service name, where supported and understood by  the  host
     operating system; if port is zero, the operating system will
     allocate a free port to  the  server  socket  which  may  be
     discovered   by  using  fconfigure  to  read  the  -sockname
     option).  Tcl will automatically accept connections  to  the
     given port.  For each connection Tcl will create a new chan-
     nel 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;



Tcl                     Last change: 8.0                        2






Tcl Built-In Commands                                  socket(1T)



     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 com-
     mand or calling the C procedure Tcl_DoOneEvent, then no con-
     nections 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 may  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 readonly
     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 succeeded.  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 computed, the  second
          element  of  the  list is identical to the address, its
          first element.

EXAMPLES
     Here is a very simple time server:
          proc Server {channel clientaddr clientport} {
             puts "Connection from $clientaddr registered"
             puts $channel [clock format [clock seconds]]
             close $channel
          }

          socket -server Server 9900
          vwait forever




Tcl                     Last change: 8.0                        3






Tcl Built-In Commands                                  socket(1T)



     And here is the corresponding client to talk to the server:
          set server localhost
          set sockChan [socket $server 9900]
          gets $sockChan line
          close $sockChan
          puts "The time on $server is $line"


SEE ALSO
     fconfigure(1T), flush(1T), open(1T), read(1T)


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

ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:

     _______________________________________
    |   ATTRIBUTE TYPE   |  ATTRIBUTE VALUE|
    |____________________|__________________|_
    | Availability       |  runtime/tcl-8  |
    |____________________|__________________|_
    | Interface Stability|  Uncommitted    |
    |____________________|_________________|

NOTES
     Source for Tcl is available on http://opensolaris.org.

























Tcl                     Last change: 8.0                        4