manpagez: man pages & more
man socket(n)
Home | html | info | man
socket(n)                    Tcl Built-In Commands                   socket(n)



______________________________________________________________________________


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 commands like read, puts  and
       flush.  At present only the TCP network protocol is supported over IPv4
       and IPv6; future releases may include support for additional protocols.
       The socket command 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 system encoding,
       as returned by encoding system.  Most of the time, you will need to use
       chan  configure  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 con-
       nection 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 IPv4 or IPv6 address such
       as 127.0.0.1 or 2001:DB8::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 addi-
       tional 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 This option will cause the client socket to be  connected  asyn-
              chronously.  This  means that the socket will be created immedi-
              ately 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.  Synchronous  client sockets may be switched
              (after they have connected) to operating  in  asynchronous  mode
              using:

                     chan configure chan -blocking 0

              See the chan configure command for more details.

              The  Tcl event loop should be running while an asynchronous con-
              nection is in progress, because it may have to do  several  con-
              nection  attempts in the background. Running the event loop also
              allows you to set up a writable channel event on the  socket  to
              get  notified  when the asynchronous connection has succeeded or
              failed. See the vwait and the chan commands for more details  on
              the event loop and channel events.

              The  chan  configure  option -connecting may be used to check if
              the connect is still running. To verify  a  successful  connect,
              the option -error may be checked when -connecting returned 0.

              Operation  without  the event queue requires at the moment calls
              to chan configure to advance the internal state machine.


SERVER SOCKETS

       If the -server option is specified then the new socket will be a server
       that  listens  on  the given 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  chan  configure  to  read  the
       -sockname option). If the host supports both, IPv4 and IPv6, the socket
       will listen on both address families.  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  (properly  a  command  prefix  list, see the EXAMPLES
       below) 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 port:

       -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 wildcard address so that it can accept  connections
              from  any  interface.  If addr is a domain name that resolves to
              multiple IP addresses that are available on the  local  machine,
              the socket will listen on all of them.

       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 does not  enter  the  event
       loop, for example by invoking the vwait command or calling the C proce-
       dure 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 allo-
       cated may be retrieved from the created server socket  using  the  chan
       configure  command to retrieve the -sockname option as described below.


CONFIGURATION OPTIONS

       The chan configure command can be used to query several  readonly  con-
       figuration 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.

              Note  that the error status is reset by the read operation; this
              mimics the underlying getsockopt(SO_ERROR) call.

       -sockname
              For client sockets (including the channels that get created when
              a client connects to a server socket) this option returns a list
              of three elements, the address, the host name and the port  num-
              ber  for  the  socket.  If the host name cannot be computed, the
              second element is identical to the address, the first element of
              the list.

              For  server  sockets this option returns a list of a multiple of
              three elements each group of which  have  the  same  meaning  as
              described  above. The list contains more than one group when the
              server socket was created without -myaddr or with  the  argument
              to  -myaddr  being  a  domain  name  that  resolves  multiple IP
              addresses that are local to the invoking host.

       -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.

       -connecting
              This option is not supported by server sockets. For client sock-
              ets, this option returns 1 if an asyncroneous connect  is  still
              in progress, 0 otherwise.



EXAMPLES

       Here is a very simple time server:

              proc Server {startTime channel clientaddr clientport} {
                  puts "Connection from $clientaddr registered"
                  set now [clock seconds]
                  puts $channel [clock format $now]
                  puts $channel "[expr {$now - $startTime}] since start"
                  close $channel
              }

              socket -server [list Server [clock seconds]] 9900
              vwait forever

       And  here is the corresponding client to talk to the server and extract
       some information:

              set server localhost
              set sockChan [socket $server 9900]
              gets $sockChan line1
              gets $sockChan line2
              close $sockChan
              puts "The time on $server is $line1"
              puts "That is [lindex $line2 0]s since the server started"


HISTORY

       Support for IPv6 was added in Tcl 8.6.


SEE ALSO

       chan(n), flush(n), open(n), read(n)


KEYWORDS

       asynchronous I/O, bind, channel, connection, domain name, host, network
       address, socket, tcp



Tcl                                   8.6                            socket(n)

tcl 8.6.5 - Generated Fri Mar 4 15:51:49 CST 2016
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.