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

FreeBSD Manual Pages

  
 
  

home | help
Tcl_OpenTcpClient(3)	    Tcl	Library	Procedures	  Tcl_OpenTcpClient(3)

______________________________________________________________________________

NAME
       Tcl_OpenTcpClient, Tcl_MakeTcpClientChannel, Tcl_OpenTcpServer -	proce-
       dures to	open channels using TCP	sockets

SYNOPSIS
       #include	<tcl.h>

       Tcl_Channel
       Tcl_OpenTcpClient(interp, port, host, myaddr, myport, async)

       Tcl_Channel
       Tcl_MakeTcpClientChannel(sock)

       Tcl_Channel
       Tcl_OpenTcpServer(interp, port, myaddr, proc, clientData)

ARGUMENTS
       Tcl_Interp *interp (in)			  Tcl interpreter to  use  for
						  error	 reporting.   If  non-
						  NULL and an error occurs, an
						  error	message	is left	in the
						  interpreter's	result.

       int port	(in)				  A port number	to connect  to
						  as  a	client or to listen on
						  as a server.

       const char *host	(in)			  A string specifying  a  host
						  name	or address for the re-
						  mote end of the connection.

       int myport (in)				  A  port   number   for   the
						  client's  end	of the socket.
						  If 0,	a port number is allo-
						  cated	at random.

       const char *myaddr (in)			  A string specifying the host
						  name or address for  network
						  interface to use for the lo-
						  cal end of  the  connection.
						  If NULL, a default interface
						  is chosen.

       int async (in)				  If   nonzero,	  the	client
						  socket  is  connected	 asyn-
						  chronously to	the server.

       ClientData sock (in)			  Platform-specific handle for
						  client TCP socket.

       Tcl_TcpAcceptProc *proc (in)		  Pointer  to  a  procedure to
						  invoke each time a new  con-
						  nection  is accepted via the
						  socket.

       ClientData clientData (in)		  Arbitrary one-word value  to
						  pass to proc.
______________________________________________________________________________

DESCRIPTION
       These  functions	 are convenience procedures for	creating channels that
       communicate over	TCP sockets.  The operations  on  a  channel  are  de-
       scribed in the manual entry for Tcl_OpenFileChannel.

TCL_OPENTCPCLIENT
       Tcl_OpenTcpClient  opens	 a  client TCP socket connected	to a port on a
       specific	host, and returns a channel that can be	 used  to  communicate
       with  the  server.  The host to connect to can be specified either as a
       domain name style name (e.g. www.sunlabs.com), or as a string  contain-
       ing  the	 alphanumeric  representation  of  its four-byte address (e.g.
       127.0.0.1). Use the string localhost to connect to a TCP	socket on  the
       host on which the function is invoked.

       The  myaddr  and	 myport	arguments allow	a client to specify an address
       for the local end of the	connection.  If	myaddr is NULL,	then an	inter-
       face  is	chosen automatically by	the operating system.  If myport is 0,
       then a port number is chosen at random by the operating system.

       If async	is zero, the call to Tcl_OpenTcpClient returns only after  the
       client  socket  has either successfully connected to the	server,	or the
       attempted connection has	failed.	 If async is  nonzero  the  socket  is
       connected  asynchronously  and the returned channel may not yet be con-
       nected to the server when the call to Tcl_OpenTcpClient returns.	If the
       channel is in blocking mode and an input	or output operation is done on
       the channel before the connection is completed or fails,	that operation
       will  wait until	the connection either completes	successfully or	fails.
       If the channel is in nonblocking	mode, the input	 or  output  operation
       will  return  immediately  and a	subsequent call	to Tcl_InputBlocked on
       the channel will	return nonzero.

       The returned channel is opened for reading and writing.	 If  an	 error
       occurs  in  opening  the	 socket,  Tcl_OpenTcpClient  returns  NULL and
       records a POSIX error code that can be retrieved	with Tcl_GetErrno.  In
       addition, if interp is non-NULL,	an error message is left in the	inter-
       preter's	result.

       The newly created channel is not	 registered  in	 the  supplied	inter-
       preter;	to  register it, use Tcl_RegisterChannel.  If one of the stan-
       dard channels, stdin, stdout or stderr was previously closed,  the  act
       of  creating  the  new channel also assigns it as a replacement for the
       standard	channel.

TCL_MAKETCPCLIENTCHANNEL
       Tcl_MakeTcpClientChannel	creates	 a  Tcl_Channel	 around	 an  existing,
       platform	specific, handle for a client TCP socket.

       The  newly  created  channel  is	 not registered	in the supplied	inter-
       preter; to register it, use Tcl_RegisterChannel.	 If one	of  the	 stan-
       dard  channels,	stdin, stdout or stderr	was previously closed, the act
       of creating the new channel also	assigns	it as a	 replacement  for  the
       standard	channel.

TCL_OPENTCPSERVER
       Tcl_OpenTcpServer  opens	 a TCP socket on the local host	on a specified
       port and	uses the Tcl event mechanism to	accept requests	 from  clients
       to  connect to it. The myaddr argument specifies	the network interface.
       If myaddr is NULL the special address INADDR_ANY	should be used to  al-
       low  connections	 from  any network interface.  Each time a client con-
       nects to	this socket, Tcl creates a channel for the new connection  and
       invokes	proc  with  information	about the channel. Proc	must match the
       following prototype:
	      typedef void Tcl_TcpAcceptProc(
		      ClientData clientData,
		      Tcl_Channel channel,
		      char *hostName,
		      int port);

       The clientData argument will be the same	as the clientData argument  to
       Tcl_OpenTcpServer,  channel  will  be  the  handle for the new channel,
       hostName	points to a string containing the name of the client host mak-
       ing  the	 connection,  and  port	will contain the client's port number.
       The new channel is opened for both input	and output.  If	proc raises an
       error,  the  connection	is  closed  automatically.  Proc has no	return
       value, but if it	wishes to reject the connection	it can close channel.

       Tcl_OpenTcpServer normally returns a pointer to a channel  representing
       the  server socket.  If an error	occurs,	Tcl_OpenTcpServer returns NULL
       and records a POSIX error code that can be retrieved with Tcl_GetErrno.
       In  addition,  if the interpreter is non-NULL, an error message is left
       in the interpreter's result.

       The channel returned by Tcl_OpenTcpServer cannot	be used	for either in-
       put  or	output.	  It  is simply	a handle for the socket	used to	accept
       connections.  The caller	can close the channel to shut down the	server
       and disallow further connections	from new clients.

       TCP  server  channels  operate correctly	only in	applications that dis-
       patch events through Tcl_DoOneEvent or through  Tcl  commands  such  as
       vwait; otherwise	Tcl will never notice that a connection	request	from a
       remote client is	pending.

       The newly created channel is not	 registered  in	 the  supplied	inter-
       preter;	to  register it, use Tcl_RegisterChannel.  If one of the stan-
       dard channels, stdin, stdout or stderr was previously closed,  the  act
       of  creating  the  new channel also assigns it as a replacement for the
       standard	channel.

PLATFORM ISSUES
       On Unix platforms, the socket handle is a Unix file descriptor  as  re-
       turned  by the socket system call.  On the Windows platform, the	socket
       handle is a SOCKET as defined in	the WinSock API.

SEE ALSO
       Tcl_OpenFileChannel(3), Tcl_RegisterChannel(3), vwait(n)

KEYWORDS
       client, server, TCP

Tcl				      8.0		  Tcl_OpenTcpClient(3)

NAME | SYNOPSIS | ARGUMENTS | DESCRIPTION | TCL_OPENTCPCLIENT | TCL_MAKETCPCLIENTCHANNEL | TCL_OPENTCPSERVER | PLATFORM ISSUES | SEE ALSO | KEYWORDS

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

home | help