Unix/Linux Go Back    


OpenDarwin 7.2.1 - man page for tcl_maketcpclientchannel (opendarwin section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


Tcl_OpenTcpClient(3)		      Tcl Library Procedures		     Tcl_OpenTcpClient(3)

_________________________________________________________________________________________________

NAME
       Tcl_OpenTcpClient,  Tcl_MakeTcpClientChannel, Tcl_OpenTcpServer - procedures to open chan-
       nels 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 remote end of the connection.

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

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

       int		 async		    (in)      If nonzero, the client socket is	connected
						      asynchronously 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  connection  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 described in the manual entry for Tcl_Open-
       FileChannel.

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
       containing 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 interface is chosen automatically by the oper-
       ating  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 connected 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  out-
       put  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 interpreter's result.

       The  newly  created channel is not registered in the supplied interpreter; to register it,
       use Tcl_RegisterChannel.  If one of the standard 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, han-
       dle for a client TCP socket.

       The  newly  created channel is not registered in the supplied interpreter; to register it,
       use Tcl_RegisterChannel.  If one of the standard 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 allow connections from any network interface.  Each time a client connects to
       this socket, Tcl creates a channel for the new connection and invokes proc  with  informa-
       tion 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 making 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 input 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 dispatch 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 interpreter; to register it,
       use Tcl_RegisterChannel.  If one of the standard 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 returned by  the  socket |
       system  call.   On  the	Windows platform, the socket handle is a SOCKET as defined in the |
       WinSock API.  On the Macintosh platform, the socket handle is a StreamPtr.

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

KEYWORDS
       client, server, TCP

Tcl					       8.0			     Tcl_OpenTcpClient(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 03:38 PM.