OSDN Git Service

FIRST REPOSITORY
[eos/hostdependOTHERS.git] / SGI / util / SGI / man / man3 / Tcl_OpenTcpClient.3
1 '\"
2 '\" Copyright (c) 1996-7 Sun Microsystems, Inc.
3 '\"
4 '\" See the file "license.terms" for information on usage and redistribution
5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
6 '\"
7 '\" SCCS: @(#) OpenTcp.3 1.19 97/06/25 14:44:00
8 '\" The definitions below are for supplemental macros used in Tcl/Tk
9 '\" manual entries.
10 '\"
11 '\" .AP type name in/out ?indent?
12 '\"     Start paragraph describing an argument to a library procedure.
13 '\"     type is type of argument (int, etc.), in/out is either "in", "out",
14 '\"     or "in/out" to describe whether procedure reads or modifies arg,
15 '\"     and indent is equivalent to second arg of .IP (shouldn't ever be
16 '\"     needed;  use .AS below instead)
17 '\"
18 '\" .AS ?type? ?name?
19 '\"     Give maximum sizes of arguments for setting tab stops.  Type and
20 '\"     name are examples of largest possible arguments that will be passed
21 '\"     to .AP later.  If args are omitted, default tab stops are used.
22 '\"
23 '\" .BS
24 '\"     Start box enclosure.  From here until next .BE, everything will be
25 '\"     enclosed in one large box.
26 '\"
27 '\" .BE
28 '\"     End of box enclosure.
29 '\"
30 '\" .CS
31 '\"     Begin code excerpt.
32 '\"
33 '\" .CE
34 '\"     End code excerpt.
35 '\"
36 '\" .VS ?version? ?br?
37 '\"     Begin vertical sidebar, for use in marking newly-changed parts
38 '\"     of man pages.  The first argument is ignored and used for recording
39 '\"     the version when the .VS was added, so that the sidebars can be
40 '\"     found and removed when they reach a certain age.  If another argument
41 '\"     is present, then a line break is forced before starting the sidebar.
42 '\"
43 '\" .VE
44 '\"     End of vertical sidebar.
45 '\"
46 '\" .DS
47 '\"     Begin an indented unfilled display.
48 '\"
49 '\" .DE
50 '\"     End of indented unfilled display.
51 '\"
52 '\" .SO
53 '\"     Start of list of standard options for a Tk widget.  The
54 '\"     options follow on successive lines, in four columns separated
55 '\"     by tabs.
56 '\"
57 '\" .SE
58 '\"     End of list of standard options for a Tk widget.
59 '\"
60 '\" .OP cmdName dbName dbClass
61 '\"     Start of description of a specific option.  cmdName gives the
62 '\"     option's name as specified in the class command, dbName gives
63 '\"     the option's name in the option database, and dbClass gives
64 '\"     the option's class in the option database.
65 '\"
66 '\" .UL arg1 arg2
67 '\"     Print arg1 underlined, then print arg2 normally.
68 '\"
69 '\" SCCS: @(#) man.macros 1.9 97/08/22 18:50:59
70 '\"
71 '\"     # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
72 .if t .wh -1.3i ^B
73 .nr ^l \n(.l
74 .ad b
75 '\"     # Start an argument description
76 .de AP
77 .ie !"\\$4"" .TP \\$4
78 .el \{\
79 .   ie !"\\$2"" .TP \\n()Cu
80 .   el          .TP 15
81 .\}
82 .ie !"\\$3"" \{\
83 .ta \\n()Au \\n()Bu
84 \&\\$1  \\fI\\$2\\fP    (\\$3)
85 .\".b
86 .\}
87 .el \{\
88 .br
89 .ie !"\\$2"" \{\
90 \&\\$1  \\fI\\$2\\fP
91 .\}
92 .el \{\
93 \&\\fI\\$1\\fP
94 .\}
95 .\}
96 ..
97 '\"     # define tabbing values for .AP
98 .de AS
99 .nr )A 10n
100 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
101 .nr )B \\n()Au+15n
102 .\"
103 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
104 .nr )C \\n()Bu+\\w'(in/out)'u+2n
105 ..
106 .AS Tcl_Interp Tcl_CreateInterp in/out
107 '\"     # BS - start boxed text
108 '\"     # ^y = starting y location
109 '\"     # ^b = 1
110 .de BS
111 .br
112 .mk ^y
113 .nr ^b 1u
114 .if n .nf
115 .if n .ti 0
116 .if n \l'\\n(.lu\(ul'
117 .if n .fi
118 ..
119 '\"     # BE - end boxed text (draw box now)
120 .de BE
121 .nf
122 .ti 0
123 .mk ^t
124 .ie n \l'\\n(^lu\(ul'
125 .el \{\
126 .\"     Draw four-sided box normally, but don't draw top of
127 .\"     box if the box started on an earlier page.
128 .ie !\\n(^b-1 \{\
129 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
130 .\}
131 .el \}\
132 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
133 .\}
134 .\}
135 .fi
136 .br
137 .nr ^b 0
138 ..
139 '\"     # VS - start vertical sidebar
140 '\"     # ^Y = starting y location
141 '\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
142 .de VS
143 .if !"\\$2"" .br
144 .mk ^Y
145 .ie n 'mc \s12\(br\s0
146 .el .nr ^v 1u
147 ..
148 '\"     # VE - end of vertical sidebar
149 .de VE
150 .ie n 'mc
151 .el \{\
152 .ev 2
153 .nf
154 .ti 0
155 .mk ^t
156 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
157 .sp -1
158 .fi
159 .ev
160 .\}
161 .nr ^v 0
162 ..
163 '\"     # Special macro to handle page bottom:  finish off current
164 '\"     # box/sidebar if in box/sidebar mode, then invoked standard
165 '\"     # page bottom macro.
166 .de ^B
167 .ev 2
168 'ti 0
169 'nf
170 .mk ^t
171 .if \\n(^b \{\
172 .\"     Draw three-sided box if this is the box's first page,
173 .\"     draw two sides but no top otherwise.
174 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
175 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
176 .\}
177 .if \\n(^v \{\
178 .nr ^x \\n(^tu+1v-\\n(^Yu
179 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
180 .\}
181 .bp
182 'fi
183 .ev
184 .if \\n(^b \{\
185 .mk ^y
186 .nr ^b 2
187 .\}
188 .if \\n(^v \{\
189 .mk ^Y
190 .\}
191 ..
192 '\"     # DS - begin display
193 .de DS
194 .RS
195 .nf
196 .sp
197 ..
198 '\"     # DE - end display
199 .de DE
200 .fi
201 .RE
202 .sp
203 ..
204 '\"     # SO - start of list of standard options
205 .de SO
206 .SH "STANDARD OPTIONS"
207 .LP
208 .nf
209 .ta 4c 8c 12c
210 .ft B
211 ..
212 '\"     # SE - end of list of standard options
213 .de SE
214 .fi
215 .ft R
216 .LP
217 See the \\fBoptions\\fR manual entry for details on the standard options.
218 ..
219 '\"     # OP - start of full description for a single option
220 .de OP
221 .LP
222 .nf
223 .ta 4c
224 Command-Line Name:      \\fB\\$1\\fR
225 Database Name:  \\fB\\$2\\fR
226 Database Class: \\fB\\$3\\fR
227 .fi
228 .IP
229 ..
230 '\"     # CS - begin code excerpt
231 .de CS
232 .RS
233 .nf
234 .ta .25i .5i .75i 1i
235 ..
236 '\"     # CE - end code excerpt
237 .de CE
238 .fi
239 .RE
240 ..
241 .de UL
242 \\$1\l'|0\(ul'\\$2
243 ..
244 .TH Tcl_OpenTcpClient 3 8.0 Tcl "Tcl Library Procedures"
245 .BS
246 '\" Note:  do not modify the .SH NAME line immediately below!
247 .SH NAME
248 Tcl_OpenTcpClient, Tcl_MakeTcpClientChannel, Tcl_OpenTcpServer \- procedures to open channels using TCP sockets
249 .SH SYNOPSIS
250 .nf
251 \fB#include <tcl.h> \fR
252 .sp
253 Tcl_Channel
254 \fBTcl_OpenTcpClient\fR(\fIinterp, port, host, myaddr, myport, async\fR)
255 .sp
256 Tcl_Channel
257 \fBTcl_MakeTcpClientChannel\fR(\fIsock\fR)
258 .sp
259 Tcl_Channel
260 \fBTcl_OpenTcpServer\fR(\fIinterp, port, myaddr, proc, clientData\fR)
261 .sp
262 .SH ARGUMENTS
263 .AS Tcl_ChannelType newClientProcPtr in
264 .AP Tcl_Interp *interp in
265 Tcl interpreter to use for error reporting.  If non-NULL and an
266 error occurs, an error message is left in \fIinterp->result\fR.
267 .AP int port in
268 A port number to connect to as a client or to listen on as a server.
269 .AP char *host in
270 A string specifying a host name or address for the remote end of the connection.
271 .AP int myport in
272 A port number for the client's end of the socket.  If 0, a port number
273 is allocated at random.
274 .AP char *myaddr in
275 A string specifying the host name or address for network interface to use
276 for the local end of the connection.  If NULL, a default interface is
277 chosen.
278 .AP int async in
279 If nonzero, the client socket is connected asynchronously to the server.
280 .AP ClientData sock in
281 Platform-specific handle for client TCP socket.
282 .AP Tcl_TcpAcceptProc *proc in
283 Pointer to a procedure to invoke each time a new connection is
284 accepted via the socket.
285 .AP ClientData clientData in
286 Arbitrary one-word value to pass to \fIproc\fR.
287 .BE
288
289 .SH DESCRIPTION
290 .PP
291 These functions are convenience procedures for creating
292 channels that communicate over TCP sockets.
293 The operations on a channel
294 are described in the manual entry for \fBTcl_OpenFileChannel\fR.
295
296 .SH TCL_OPENTCPCLIENT
297 .PP
298 \fBTcl_OpenTcpClient\fR opens a client TCP socket connected to a \fIport\fR
299 on a specific \fIhost\fR, and returns a channel that can be used to
300 communicate with the server. The host to connect to can be specified either
301 as a domain name style name (e.g. \fBwww.sunlabs.com\fR), or as a string
302 containing the alphanumeric representation of its four-byte address (e.g.
303 \fB127.0.0.1\fR). Use the string \fBlocalhost\fR to connect to a TCP socket on
304 the host on which the function is invoked.
305 .PP
306 The \fImyaddr\fR and \fImyport\fR arguments allow a client to specify an
307 address for the local end of the connection.  If \fImyaddr\fR is NULL, then
308 an interface is chosen automatically by the operating system.
309 If \fImyport\fR is 0, then a port number is chosen at random by
310 the operating system.
311 .PP
312 If \fIasync\fR is zero, the call to \fBTcl_OpenTcpClient\fR returns only
313 after the client socket has either successfully connected to the server, or
314 the attempted connection has failed.
315 If \fIasync\fR is nonzero the socket is connected asynchronously and the
316 returned channel may not yet be connected to the server when the call to
317 \fBTcl_OpenTcpClient\fR returns. If the channel is in blocking mode and an
318 input or output operation is done on the channel before the connection is
319 completed or fails, that operation will wait until the connection either
320 completes successfully or fails. If the channel is in nonblocking mode, the
321 input or output operation will return immediately and a subsequent call to
322 \fBTcl_InputBlocked\fR on the channel will return nonzero.
323 .PP
324 The returned channel is opened for reading and writing.
325 If an error occurs in opening the socket, \fBTcl_OpenTcpClient\fR returns
326 NULL and records a POSIX error code that can be retrieved
327 with \fBTcl_GetErrno\fR.
328 In addition, if \fIinterp\fR is non-NULL, an error message
329 is left in \fIinterp->result\fR.
330 .PP
331 The newly created channel is not registered in the supplied interpreter; to
332 register it, use \fBTcl_RegisterChannel\fR.
333 If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
334 previously closed, the act of creating the new channel also assigns it as a
335 replacement for the standard channel.
336
337 .SH TCL_MAKETCPCLIENTCHANNEL
338 .PP
339 \fBTcl_MakeTcpClientChannel\fR creates a \fBTcl_Channel\fR around an
340 existing, platform specific, handle for a client TCP socket.
341 .PP
342 The newly created channel is not registered in the supplied interpreter; to
343 register it, use \fBTcl_RegisterChannel\fR.
344 If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
345 previously closed, the act of creating the new channel also assigns it as a
346 replacement for the standard channel.
347
348 .SH TCL_OPENTCPSERVER
349 .PP
350 \fBTcl_OpenTcpServer\fR opens a TCP socket on the local host on a specified
351 \fIport\fR and uses the Tcl event mechanism to accept requests from clients
352 to connect to it.  The \fImyaddr\fP argument specifies the network interface.
353 If \fImyaddr\fP is NULL the special address INADDR_ANY should be used to
354 allow connections from any network interface.
355 Each time a client connects to this socket, Tcl creates a channel
356 for the new connection and invokes \fIproc\fR with information about
357 the channel.  \fIProc\fR must match the following prototype:
358 .CS
359 typedef void Tcl_TcpAcceptProc(
360         ClientData \fIclientData\fR,
361         Tcl_Channel \fIchannel\fR,
362         char *\fIhostName\fR,
363         int \fIport\fP);
364 .CE
365 .PP
366 The \fIclientData\fR argument will be the same as the \fIclientData\fR
367 argument to \fBTcl_OpenTcpServer\fR, \fIchannel\fR will be the handle
368 for the new channel, \fIhostName\fR points to a string containing
369 the name of the client host making the connection, and \fIport\fP
370 will contain the client's port number.
371 The new channel
372 is opened for both input and output. 
373 If \fIproc\fR raises an error, the connection is closed automatically.
374 \fIProc\fR has no return value, but if it wishes to reject the
375 connection it can close \fIchannel\fR.
376 .PP
377 \fBTcl_OpenTcpServer\fR normally returns a pointer to a channel
378 representing the server socket.
379 If an error occurs, \fBTcl_OpenTcpServer\fR returns NULL and
380 records a POSIX error code that can be retrieved with \fBTcl_GetErrno\fR.
381 In addition, if \fIinterp->result\fR is non-NULL, an error message
382 is left in \fIinterp->result\fR.
383 .PP
384 The channel returned by \fBTcl_OpenTcpServer\fR cannot be used for
385 either input or output.
386 It is simply a handle for the socket used to accept connections.
387 The caller can close the channel to shut down the server and disallow
388 further connections from new clients.
389 .PP
390 TCP server channels operate correctly only in applications that dispatch
391 events through \fBTcl_DoOneEvent\fR or through Tcl commands such as
392 \fBvwait\fR; otherwise Tcl will never notice that a connection request from
393 a remote client is pending.
394 .PP
395 The newly created channel is not registered in the supplied interpreter; to
396 register it, use \fBTcl_RegisterChannel\fR.
397 If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
398 previously closed, the act of creating the new channel also assigns it as a
399 replacement for the standard channel.
400
401 .VS
402 .SH "PLATFORM ISSUES"
403 .PP
404 On Unix platforms, the socket handle is a Unix file descriptor as
405 returned by the \fBsocket\fR system call.  On the Windows platform, the
406 socket handle is a \fBSOCKET\fR as defined in the WinSock API.  On the
407 Macintosh platform, the socket handle is a \fBStreamPtr\fR.
408 .VE
409
410 .SH "SEE ALSO"
411 Tcl_OpenFileChannel(3), Tcl_RegisterChannel(3), vwait(n)
412
413 .SH KEYWORDS
414 client, server, TCP