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
68

DESCRIPTION

70       These functions are convenience procedures for creating  channels  that
71       communicate  over  TCP  sockets.   The  operations  on  a  channel  are
72       described in the manual entry for Tcl_OpenFileChannel.
73
74

TCL_OPENTCPCLIENT

76       Tcl_OpenTcpClient opens a client TCP socket connected to a  port  on  a
77       specific  host,  and  returns a channel that can be used to communicate
78       with the server. The host to connect to can be specified  either  as  a
79       domain  name style name (e.g. www.sunlabs.com), or as a string contain‐
80       ing the alphanumeric representation  of  its  four-byte  address  (e.g.
81       127.0.0.1).  Use the string localhost to connect to a TCP socket on the
82       host on which the function is invoked.
83
84       The myaddr and myport arguments allow a client to  specify  an  address
85       for the local end of the connection.  If myaddr is NULL, then an inter‐
86       face is chosen automatically by the operating system.  If myport is  0,
87       then a port number is chosen at random by the operating system.
88
89       If  async is zero, the call to Tcl_OpenTcpClient returns only after the
90       client socket has either successfully connected to the server,  or  the
91       attempted  connection  has  failed.   If async is nonzero the socket is
92       connected asynchronously and the returned channel may not yet  be  con‐
93       nected to the server when the call to Tcl_OpenTcpClient returns. If the
94       channel is in blocking mode and an input or output operation is done on
95       the channel before the connection is completed or fails, that operation
96       will wait until the connection either completes successfully or  fails.
97       If  the  channel  is in nonblocking mode, the input or output operation
98       will return immediately and a subsequent call  to  Tcl_InputBlocked  on
99       the channel will return nonzero.
100
101       The  returned  channel  is opened for reading and writing.  If an error
102       occurs in  opening  the  socket,  Tcl_OpenTcpClient  returns  NULL  and
103       records a POSIX error code that can be retrieved with Tcl_GetErrno.  In
104       addition, if interp is non-NULL, an error message is left in the inter‐
105       preter's result.
106
107       The  newly  created  channel  is  not registered in the supplied inter‐
108       preter; to register it, use Tcl_RegisterChannel.  If one of  the  stan‐
109       dard  channels,  stdin, stdout or stderr was previously closed, the act
110       of creating the new channel also assigns it as a  replacement  for  the
111       standard channel.
112
113

TCL_MAKETCPCLIENTCHANNEL

115       Tcl_MakeTcpClientChannel  creates  a  Tcl_Channel  around  an existing,
116       platform specific, handle for a client TCP socket.
117
118       The newly created channel is not  registered  in  the  supplied  inter‐
119       preter;  to  register it, use Tcl_RegisterChannel.  If one of the stan‐
120       dard channels, stdin, stdout or stderr was previously closed,  the  act
121       of  creating  the  new channel also assigns it as a replacement for the
122       standard channel.
123
124

TCL_OPENTCPSERVER

126       Tcl_OpenTcpServer opens a TCP socket on the local host on  a  specified
127       port  and  uses the Tcl event mechanism to accept requests from clients
128       to connect to it. The myaddr argument specifies the network  interface.
129       If  myaddr  is  NULL  the  special address INADDR_ANY should be used to
130       allow connections from any network interface.  Each time a client  con‐
131       nects  to this socket, Tcl creates a channel for the new connection and
132       invokes proc with information about the channel. Proc  must  match  the
133       following prototype:
134              typedef void Tcl_TcpAcceptProc(
135                      ClientData clientData,
136                      Tcl_Channel channel,
137                      char *hostName,
138                      int port);
139
140       The  clientData argument will be the same as the clientData argument to
141       Tcl_OpenTcpServer, channel will be the  handle  for  the  new  channel,
142       hostName points to a string containing the name of the client host mak‐
143       ing the connection, and port will contain  the  client's  port  number.
144       The new channel is opened for both input and output.  If proc raises an
145       error, the connection is closed  automatically.   Proc  has  no  return
146       value, but if it wishes to reject the connection it can close channel.
147
148       Tcl_OpenTcpServer  normally returns a pointer to a channel representing
149       the server socket.  If an error occurs, Tcl_OpenTcpServer returns  NULL
150       and records a POSIX error code that can be retrieved with Tcl_GetErrno.
151       In addition, if the interpreter is non-NULL, an error message  is  left
152       in the interpreter's result.
153
154       The  channel  returned  by  Tcl_OpenTcpServer cannot be used for either
155       input or output.  It is simply a handle for the socket used  to  accept
156       connections.   The caller can close the channel to shut down the server
157       and disallow further connections from new clients.
158
159       TCP server channels operate correctly only in  applications  that  dis‐
160       patch  events  through  Tcl_DoOneEvent  or through Tcl commands such as
161       vwait; otherwise Tcl will never notice that a connection request from a
162       remote client is pending.
163
164       The  newly  created  channel  is  not registered in the supplied inter‐
165       preter; to register it, use Tcl_RegisterChannel.  If one of  the  stan‐
166       dard  channels,  stdin, stdout or stderr was previously closed, the act
167       of creating the new channel also assigns it as a  replacement  for  the
168       standard channel.
169
170

PLATFORM ISSUES

172       On  Unix  platforms,  the  socket  handle  is a Unix file descriptor as
173       returned by the socket system  call.   On  the  Windows  platform,  the
174       socket handle is a SOCKET as defined in the WinSock API.
175
176

SEE ALSO

178       Tcl_OpenFileChannel(3), Tcl_RegisterChannel(3), vwait(n)
179
180

KEYWORDS

182       client, server, TCP
183
184
185
186Tcl                                   8.0                 Tcl_OpenTcpClient(3)
Impressum