Go to main content

man pages section 1: User Commands

Exit Print View

Updated: Wednesday, February 10, 2021
 
 

socket (1t)

Name

socket - Open a TCP network connection

Synopsis

socket ?options? host port

socket -server command ?options? port

Description

socket(1t)                   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 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.


ATTRIBUTES
       See attributes(7) for descriptions of the following attributes:


       +---------------+------------------+
       |ATTRIBUTE TYPE | ATTRIBUTE VALUE  |
       +---------------+------------------+
       |Availability   | runtime/tcl-8    |
       +---------------+------------------+
       |Stability      | Uncommitted      |
       +---------------+------------------+
SEE ALSO
       chan(n), flush(n), open(n), read(n)

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



NOTES
       This     software     was    built    from    source    available    at
       https://github.com/oracle/solaris-userland.   The  original   community
       source was downloaded from  http://prdownloads.sourceforge.net/tcl/tcl-
       core8.6.7-src.tar.gz

       Further information about this software can be found on the open source
       community website at https://www.tcl.tk/.



Tcl                                   8.6                           socket(1t)