Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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;	future
       releases	may include support for	additional protocols.  The socket com-
       mand  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  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	 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	 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  in-
	      terface 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 The  -async  option will cause the client	socket to be connected
	      asynchronously. This means that the socket will be created imme-
	      diately  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 nonblock-
	      ing mode and a gets or flush is done on the  socket  before  the
	      connection  attempt succeeds or fails, the operation returns im-
	      mediately	and fblocked on	 the  socket  returns  1.  Synchronous
	      client  sockets  may  be switched	(after they have connected) to
	      operating	in asynchronous	mode using:
		     fconfigure	chan -blocking 0

	      See the fconfigure command for more details.

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  op-
       tion).	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 with three addi-
       tional 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  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	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 un-
       used port for use as a server socket.  The port number  actually	 allo-
       cated  may  be retrieved	from the created server	socket using the fcon-
       figure 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 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
	      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  ad-
	      dress, 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 ad-
	      dress, 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

       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(n), flush(n),	open(n), read(n)

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

Tcl				      8.0			     socket(n)

NAME | SYNOPSIS | DESCRIPTION | CLIENT SOCKETS | SERVER SOCKETS | CONFIGURATION OPTIONS | EXAMPLES | SEE ALSO | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=socket.tcl85&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help