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
37                                                  remote end  of  the  connec‐
38                                                  tion.
39
40       int myport (in)                            A   port   number   for  the
41                                                  client's end of the  socket.
42                                                  If 0, a port number is allo‐
43                                                  cated at random.
44
45       const char *myaddr (in)                    A string specifying the host
46                                                  name  or address for network
47                                                  interface  to  use  for  the
48                                                  local end of the connection.
49                                                  If NULL, a default interface
50                                                  is chosen.
51
52       int async (in)                             If   nonzero,   the   client
53                                                  socket  is  connected  asyn‐
54                                                  chronously to the server.
55
56       ClientData sock (in)                       Platform-specific handle for
57                                                  client TCP socket.
58
59       Tcl_TcpAcceptProc *proc (in)               Pointer to  a  procedure  to
60                                                  invoke  each time a new con‐
61                                                  nection is accepted via  the
62                                                  socket.
63
64       ClientData clientData (in)                 Arbitrary  one-word value to
65                                                  pass to proc.
66______________________________________________________________________________
67

DESCRIPTION

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

PLATFORM ISSUES

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

SEE ALSO

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

KEYWORDS

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