Seth Woolley's Man Viewer

Manual for socket - man n socket

([section] manual, -k keyword, -K [section] search, -f whatis)
man plain no title

socket(2,7,n)(n)                    Tcl Built-In Commands                   socket(2,7,n)(n)



NAME
       socket(2,7,n) - Open a TCP network connection

SYNOPSIS
       socket(2,7,n) ?options? host(1,5) port

       socket(2,7,n) -server command ?options? port


DESCRIPTION
       This  command  opens  a network socket(2,7,n) and returns a channel identifier
       that may be used in(1,8) future invocations of commands like read(2,n,1 builtins), puts(3,n)  and
       flush(8,n).   At present only the TCP network protocol is supported;  future
       releases may include support for additional protocols.  The socket(2,7,n) com-
       mand  may be used to open(2,3,n) either the client or server side of a connec-
       tion, depending on whether the -server switch(1,n) is specified.

       Note that the default encoding(3,n) for all sockets is the system  encoding(3,n),
       as returned by encoding(3,n) system.  Most of the time(1,2,n), 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  con-
       nection is opened and the command returns a channel identifier that can
       be used for both reading and writing.  Port and host(1,5) 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(1,5) operating system) and host(1,5) 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(1,5) on which the command is
       invoked.

       The following options may also be present before host(1,5) 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(3,n) 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(1,5) 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(3,4,6)  by
              the system software.

       -async The  -async  option will cause the client socket(2,7,n) to be connected
              asynchronously. This means that the socket(2,7,n) will be created imme-
              diately  but  may  not  yet be connected to the server, when the
              call to socket(2,7,n) returns. When a gets(3,n) or  flush(8,n)  is  done  on  the
              socket(2,7,n)  before  the connection attempt succeeds or fails, if(3,n) the
              socket(2,7,n) is in(1,8) blocking mode, the operation will  wait  until  the
              connection  is completed or fails. If the socket(2,7,n) is in(1,8) nonblock-
              ing mode and a gets(3,n) or flush(8,n) is done on the  socket(2,7,n)  before  the
              connection  attempt  succeeds  or  fails,  the operation returns
              immediately and fblocked on the socket(2,7,n) returns 1.


SERVER SOCKETS
       If the -server option is specified then the new socket(2,7,n) will be a server
       for  the port given by port (either an integer or a service name, where
       supported and understood by the host(1,5) operating system).  Tcl will auto-
       matically  accept(2,8)  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 with three additional arguments: the
       name of the new channel, the address, in(1,8) network address  notation,  of
       the client's host(1,5), and the client's port number.

       The following additional option may also be specified before host(1,5):

       -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(3,n) the server machine has multiple network
              interfaces.  If the option is omitted then the server socket(2,7,n)  is
              bound  to  the  special address INADDR_ANY so that it can accept(2,8)
              connections from any interface.

       Server channels cannot be used for input or output; their sole  use  is
       to  accept(2,8) 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 doesn't 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 my be retrieved from the created server socket(2,7,n) using the fconfig-
       ure command to retrieve the -sockname option as described below.


CONFIGURATION OPTIONS
       The fconfigure command can be used to query several readonly configura-
       tion options for socket(2,7,n) channels:

       -error This  option  gets(3,n) the current error(8,n) status of the given socket.
              This is useful when you need to  determine  if(3,n)  an  asynchronous
              connect  operation  succeeded.  If there was an error(8,n), the error(8,n)
              message is returned.  If there was no error(8,n), an empty string(3,n)  is
              returned.

       -sockname
              This  option  returns a list of three elements, the address, the
              host(1,5) name and the port number for the socket. If the  host(1,5)  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(1,5) name and the port to  which  the
              peer  socket(2,7,n)  is  connected or bound. If the host(1,5) name cannot be
              computed, the second element of the list  is  identical  to  the
              address, its first element.



SEE ALSO
       fconfigure(n), flush(8,n)(n), open(2,3,n)(n), read(2,n,1 builtins)(n)


KEYWORDS
       bind(2,n,1 builtins),  channel, connection, domain name, host(1,5), network address, socket(2,7,n),
       tcp



Tcl                                   8.0                            socket(2,7,n)(n)

References for this manual (incoming links)