1Tcl_OpenTcpClient(3)        Tcl Library Procedures        Tcl_OpenTcpClient(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tcl_OpenTcpClient, Tcl_MakeTcpClientChannel, Tcl_OpenTcpServer - proce‐
9       dures to open channels using TCP sockets
10

SYNOPSIS

12       #include <tcl.h>
13
14       Tcl_Channel
15       Tcl_OpenTcpClient(interp, port, host, myaddr, myport, async)
16
17       Tcl_Channel
18       Tcl_MakeTcpClientChannel(sock)
19
20       Tcl_Channel
21       Tcl_OpenTcpServer(interp, port, myaddr, proc, clientData)
22
23

ARGUMENTS

25       Tcl_Interp *interp (in)                    Tcl interpreter to  use  for
26                                                  error  reporting.   If  non-
27                                                  NULL and an error occurs, an
28                                                  error message is left in the
29                                                  interpreter's result.
30
31       int port (in)                              A port number to connect  to
32                                                  as  a client or to listen on
33                                                  as a server.
34
35       const char *host (in)                      A string specifying  a  host
36                                                  name  or address for the re‐
37                                                  mote end of the connection.
38
39       int myport (in)                            A  port   number   for   the
40                                                  client's  end of the socket.
41                                                  If 0, a port number is allo‐
42                                                  cated at random.
43
44       const char *myaddr (in)                    A string specifying the host
45                                                  name or address for  network
46                                                  interface to use for the lo‐
47                                                  cal end of  the  connection.
48                                                  If NULL, a default interface
49                                                  is chosen.
50
51       int async (in)                             If   nonzero,   the   client
52                                                  socket  is  connected  asyn‐
53                                                  chronously to the server.
54
55       ClientData sock (in)                       Platform-specific handle for
56                                                  client TCP socket.
57
58       Tcl_TcpAcceptProc *proc (in)               Pointer  to  a  procedure to
59                                                  invoke each time a new  con‐
60                                                  nection  is accepted via the
61                                                  socket.
62
63       ClientData clientData (in)                 Arbitrary one-word value  to
64                                                  pass to proc.
65______________________________________________________________________________
66

DESCRIPTION

68       These  functions  are convenience procedures for creating channels that
69       communicate over TCP sockets.  The operations  on  a  channel  are  de‐
70       scribed in the manual entry for Tcl_OpenFileChannel.
71
72   TCL_OPENTCPCLIENT
73       Tcl_OpenTcpClient  opens  a  client TCP socket connected to a port on a
74       specific host, and returns a channel that can be  used  to  communicate
75       with  the  server.  The host to connect to can be specified either as a
76       domain name style name (e.g. www.sunlabs.com), or as a string  contain‐
77       ing  the  alphanumeric  representation  of  its four-byte address (e.g.
78       127.0.0.1). Use the string localhost to connect to a TCP socket on  the
79       host on which the function is invoked.
80
81       The  myaddr  and  myport arguments allow a client to specify an address
82       for the local end of the connection.  If myaddr is NULL, then an inter‐
83       face  is chosen automatically by the operating system.  If myport is 0,
84       then a port number is chosen at random by the operating system.
85
86       If async is zero, the call to Tcl_OpenTcpClient returns only after  the
87       client  socket  has either successfully connected to the server, or the
88       attempted connection has failed.  If async is  nonzero  the  socket  is
89       connected  asynchronously  and the returned channel may not yet be con‐
90       nected to the server when the call to Tcl_OpenTcpClient returns. If the
91       channel is in blocking mode and an input or output operation is done on
92       the channel before the connection is completed or fails, that operation
93       will  wait until the connection either completes successfully or fails.
94       If the channel is in nonblocking mode, the input  or  output  operation
95       will  return  immediately  and a subsequent call to Tcl_InputBlocked on
96       the channel will return nonzero.
97
98       The returned channel is opened for reading and writing.   If  an  error
99       occurs  in  opening  the  socket,  Tcl_OpenTcpClient  returns  NULL and
100       records a POSIX error code that can be retrieved with Tcl_GetErrno.  In
101       addition, if interp is non-NULL, an error message is left in the inter‐
102       preter's result.
103
104       The newly created channel is not  registered  in  the  supplied  inter‐
105       preter;  to  register it, use Tcl_RegisterChannel.  If one of the stan‐
106       dard channels, stdin, stdout or stderr was previously closed,  the  act
107       of  creating  the  new channel also assigns it as a replacement for the
108       standard channel.
109
110   TCL_MAKETCPCLIENTCHANNEL
111       Tcl_MakeTcpClientChannel creates  a  Tcl_Channel  around  an  existing,
112       platform specific, handle for a client TCP socket.
113
114       The  newly  created  channel  is  not registered in the supplied inter‐
115       preter; to register it, use Tcl_RegisterChannel.  If one of  the  stan‐
116       dard  channels,  stdin, stdout or stderr was previously closed, the act
117       of creating the new channel also assigns it as a  replacement  for  the
118       standard channel.
119
120   TCL_OPENTCPSERVER
121       Tcl_OpenTcpServer  opens  a TCP socket on the local host on a specified
122       port and uses the Tcl event mechanism to accept requests  from  clients
123       to  connect to it. The myaddr argument specifies the network interface.
124       If myaddr is NULL the special address INADDR_ANY should be used to  al‐
125       low  connections  from  any network interface.  Each time a client con‐
126       nects to this socket, Tcl creates a channel for the new connection  and
127       invokes  proc  with  information about the channel. Proc must match the
128       following prototype:
129
130              typedef void Tcl_TcpAcceptProc(
131                      ClientData clientData,
132                      Tcl_Channel channel,
133                      char *hostName,
134                      int port);
135
136       The clientData argument will be the same as the clientData argument  to
137       Tcl_OpenTcpServer,  channel  will  be  the  handle for the new channel,
138       hostName points to a string containing the name of the client host mak‐
139       ing  the  connection,  and  port will contain the client's port number.
140       The new channel is opened for both input and output.  If proc raises an
141       error,  the  connection  is  closed  automatically.  Proc has no return
142       value, but if it wishes to reject the connection it can close channel.
143
144       Tcl_OpenTcpServer normally returns a pointer to a channel  representing
145       the  server socket.  If an error occurs, Tcl_OpenTcpServer returns NULL
146       and records a POSIX error code that can be retrieved with Tcl_GetErrno.
147       In  addition,  if the interpreter is non-NULL, an error message is left
148       in the interpreter's result.
149
150       The channel returned by Tcl_OpenTcpServer cannot be used for either in‐
151       put  or  output.   It  is simply a handle for the socket used to accept
152       connections.  The caller can close the channel to shut down the  server
153       and disallow further connections from new clients.
154
155       TCP  server  channels  operate correctly only in applications that dis‐
156       patch events through Tcl_DoOneEvent or through  Tcl  commands  such  as
157       vwait; otherwise Tcl will never notice that a connection request from a
158       remote client is pending.
159
160       The newly created channel is not  registered  in  the  supplied  inter‐
161       preter;  to  register it, use Tcl_RegisterChannel.  If one of the stan‐
162       dard channels, stdin, stdout or stderr was previously closed,  the  act
163       of  creating  the  new channel also assigns it as a replacement for the
164       standard channel.
165

PLATFORM ISSUES

167       On Unix platforms, the socket handle is a Unix file descriptor  as  re‐
168       turned  by the socket system call.  On the Windows platform, the socket
169       handle is a SOCKET as defined in the WinSock API.
170

SEE ALSO

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

KEYWORDS

175       channel, client, server, socket, TCP
176
177
178
179Tcl                                   8.0                 Tcl_OpenTcpClient(3)
Impressum