tcl7.6 C API - OpenTcp






NAME

     Tcl_OpenTcpClient, Tcl_OpenTcpServer -  procedures  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    inter-
                                                    preter to use
                                                    for     error
                                                    reporting.
                                                    If   non-NULL
                                                    and  an error
                                                    occurs,    an
                                                    error message
                                                    is  left   in
                                                    interp-
                                                    >result.

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

     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.

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

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

     ClientData        sock               (in)      Platform-
                                                    specific han-
                                                    dle       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_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 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
     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 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  com-
     pletes successfully or fails. If the channel is in nonblock-
     ing mode, the input or output operation will return  immedi-
     ately and a subsequent call to Tcl_InputBlocked on the chan-
     nel 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 interp->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, handle 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 spe-
     cial 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 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 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 interp->result is non-NULL, an error message is  left  in
     interp->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 connec-
     tions 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.



SEE ALSO

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



KEYWORDS

     client, server, TCP