2 '\" Copyright (c) 1996-7 Sun Microsystems, Inc.
4 '\" See the file "license.terms" for information on usage and redistribution
5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
7 .TH Tcl_OpenTcpClient 3 8.0 Tcl "Tcl Library Procedures"
8 .\" The -*- nroff -*- definitions below are for supplemental macros used
9 .\" in Tcl/Tk manual entries.
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)
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.
24 .\" Start box enclosure. From here until next .BE, everything will be
25 .\" enclosed in one large box.
28 .\" End of box enclosure.
31 .\" Begin code excerpt.
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.
44 .\" End of vertical sidebar.
47 .\" Begin an indented unfilled display.
50 .\" End of indented unfilled display.
53 .\" Start of list of standard options for a Tk widget. The manpage
54 .\" argument defines where to look up the standard options; if
55 .\" omitted, defaults to "options". The options follow on successive
56 .\" lines, in three columns separated by tabs.
59 .\" End of list of standard options for a Tk widget.
61 .\" .OP cmdName dbName dbClass
62 .\" Start of description of a specific option. cmdName gives the
63 .\" option's name as specified in the class command, dbName gives
64 .\" the option's name in the option database, and dbClass gives
65 .\" the option's class in the option database.
68 .\" Print arg1 underlined, then print arg2 normally.
71 .\" Print arg1 in quotes, then arg2 normally (for trailing punctuation).
74 .\" Print an open parenthesis, arg1 in quotes, then arg2 normally
75 .\" (for trailing punctuation) and then a closing parenthesis.
77 .\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
81 .\" # Start an argument description
85 . ie !"\\$2"" .TP \\n()Cu
90 \&\\$1 \\fI\\$2\\fP (\\$3)
103 .\" # define tabbing values for .AP
106 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
109 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
110 .nr )C \\n()Bu+\\w'(in/out)'u+2n
112 .AS Tcl_Interp Tcl_CreateInterp in/out
113 .\" # BS - start boxed text
114 .\" # ^y = starting y location
122 .if n \l'\\n(.lu\(ul'
125 .\" # BE - end boxed text (draw box now)
130 .ie n \l'\\n(^lu\(ul'
132 .\" Draw four-sided box normally, but don't draw top of
133 .\" box if the box started on an earlier page.
135 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
138 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
145 .\" # VS - start vertical sidebar
146 .\" # ^Y = starting y location
147 .\" # ^v = 1 (for troff; for nroff this doesn't matter)
151 .ie n 'mc \s12\(br\s0
154 .\" # VE - end of vertical sidebar
162 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
169 .\" # Special macro to handle page bottom: finish off current
170 .\" # box/sidebar if in box/sidebar mode, then invoked standard
171 .\" # page bottom macro.
178 .\" Draw three-sided box if this is the box's first page,
179 .\" draw two sides but no top otherwise.
180 .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
181 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
184 .nr ^x \\n(^tu+1v-\\n(^Yu
185 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
198 .\" # DS - begin display
204 .\" # DE - end display
210 .\" # SO - start of list of standard options
212 'ie '\\$1'' .ds So \\fBoptions\\fR
213 'el .ds So \\fB\\$1\\fR
214 .SH "STANDARD OPTIONS"
220 .\" # SE - end of list of standard options
225 See the \\*(So manual entry for details on the standard options.
227 .\" # OP - start of full description for a single option
232 Command-Line Name: \\fB\\$1\\fR
233 Database Name: \\fB\\$2\\fR
234 Database Class: \\fB\\$3\\fR
238 .\" # CS - begin code excerpt
244 .\" # CE - end code excerpt
249 .\" # UL - underline word
253 .\" # QW - apply quotation marks to word
255 .ie '\\*(lq'"' ``\\$1''\\$2
256 .\"" fix emacs highlighting
257 .el \\*(lq\\$1\\*(rq\\$2
259 .\" # PQ - apply parens and quotation marks to word
261 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
262 .\"" fix emacs highlighting
263 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
265 .\" # QR - quoted range
267 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
268 .\"" fix emacs highlighting
269 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
271 .\" # MT - "empty" string
276 '\" Note: do not modify the .SH NAME line immediately below!
278 Tcl_OpenTcpClient, Tcl_MakeTcpClientChannel, Tcl_OpenTcpServer \- procedures to open channels using TCP sockets
281 \fB#include <tcl.h> \fR
284 \fBTcl_OpenTcpClient\fR(\fIinterp, port, host, myaddr, myport, async\fR)
287 \fBTcl_MakeTcpClientChannel\fR(\fIsock\fR)
290 \fBTcl_OpenTcpServer\fR(\fIinterp, port, myaddr, proc, clientData\fR)
293 .AS Tcl_TcpAcceptProc clientData
294 .AP Tcl_Interp *interp in
295 Tcl interpreter to use for error reporting. If non-NULL and an
296 error occurs, an error message is left in the interpreter's result.
298 A port number to connect to as a client or to listen on as a server.
299 .AP "const char" *host in
300 A string specifying a host name or address for the remote end of the connection.
302 A port number for the client's end of the socket. If 0, a port number
303 is allocated at random.
304 .AP "const char" *myaddr in
305 A string specifying the host name or address for network interface to use
306 for the local end of the connection. If NULL, a default interface is
309 If nonzero, the client socket is connected asynchronously to the server.
310 .AP ClientData sock in
311 Platform-specific handle for client TCP socket.
312 .AP Tcl_TcpAcceptProc *proc in
313 Pointer to a procedure to invoke each time a new connection is
314 accepted via the socket.
315 .AP ClientData clientData in
316 Arbitrary one-word value to pass to \fIproc\fR.
320 These functions are convenience procedures for creating
321 channels that communicate over TCP sockets.
322 The operations on a channel
323 are described in the manual entry for \fBTcl_OpenFileChannel\fR.
324 .SS TCL_OPENTCPCLIENT
326 \fBTcl_OpenTcpClient\fR opens a client TCP socket connected to a \fIport\fR
327 on a specific \fIhost\fR, and returns a channel that can be used to
328 communicate with the server. The host to connect to can be specified either
329 as a domain name style name (e.g. \fBwww.sunlabs.com\fR), or as a string
330 containing the alphanumeric representation of its four-byte address (e.g.
331 \fB127.0.0.1\fR). Use the string \fBlocalhost\fR to connect to a TCP socket on
332 the host on which the function is invoked.
334 The \fImyaddr\fR and \fImyport\fR arguments allow a client to specify an
335 address for the local end of the connection. If \fImyaddr\fR is NULL, then
336 an interface is chosen automatically by the operating system.
337 If \fImyport\fR is 0, then a port number is chosen at random by
338 the operating system.
340 If \fIasync\fR is zero, the call to \fBTcl_OpenTcpClient\fR returns only
341 after the client socket has either successfully connected to the server, or
342 the attempted connection has failed.
343 If \fIasync\fR is nonzero the socket is connected asynchronously and the
344 returned channel may not yet be connected to the server when the call to
345 \fBTcl_OpenTcpClient\fR returns. If the channel is in blocking mode and an
346 input or output operation is done on the channel before the connection is
347 completed or fails, that operation will wait until the connection either
348 completes successfully or fails. If the channel is in nonblocking mode, the
349 input or output operation will return immediately and a subsequent call to
350 \fBTcl_InputBlocked\fR on the channel will return nonzero.
352 The returned channel is opened for reading and writing.
353 If an error occurs in opening the socket, \fBTcl_OpenTcpClient\fR returns
354 NULL and records a POSIX error code that can be retrieved
355 with \fBTcl_GetErrno\fR.
356 In addition, if \fIinterp\fR is non-NULL, an error message
357 is left in the interpreter's result.
359 The newly created channel is not registered in the supplied interpreter; to
360 register it, use \fBTcl_RegisterChannel\fR.
361 If one of the standard channels, \fBstdin\fR, \fBstdout\fR or \fBstderr\fR was
362 previously closed, the act of creating the new channel also assigns it as a
363 replacement for the standard channel.
364 .SS TCL_MAKETCPCLIENTCHANNEL
366 \fBTcl_MakeTcpClientChannel\fR creates a \fBTcl_Channel\fR around an
367 existing, platform specific, handle for a client TCP socket.
369 The newly created channel is not registered in the supplied interpreter; to
370 register it, use \fBTcl_RegisterChannel\fR.
371 If one of the standard channels, \fBstdin\fR, \fBstdout\fR or \fBstderr\fR was
372 previously closed, the act of creating the new channel also assigns it as a
373 replacement for the standard channel.
374 .SS TCL_OPENTCPSERVER
376 \fBTcl_OpenTcpServer\fR opens a TCP socket on the local host on a specified
377 \fIport\fR and uses the Tcl event mechanism to accept requests from clients
378 to connect to it. The \fImyaddr\fR argument specifies the network interface.
379 If \fImyaddr\fR is NULL the special address INADDR_ANY should be used to
380 allow connections from any network interface.
381 Each time a client connects to this socket, Tcl creates a channel
382 for the new connection and invokes \fIproc\fR with information about
383 the channel. \fIProc\fR must match the following prototype:
386 typedef void \fBTcl_TcpAcceptProc\fR(
387 ClientData \fIclientData\fR,
388 Tcl_Channel \fIchannel\fR,
389 char *\fIhostName\fR,
393 The \fIclientData\fR argument will be the same as the \fIclientData\fR
394 argument to \fBTcl_OpenTcpServer\fR, \fIchannel\fR will be the handle
395 for the new channel, \fIhostName\fR points to a string containing
396 the name of the client host making the connection, and \fIport\fR
397 will contain the client's port number.
399 is opened for both input and output.
400 If \fIproc\fR raises an error, the connection is closed automatically.
401 \fIProc\fR has no return value, but if it wishes to reject the
402 connection it can close \fIchannel\fR.
404 \fBTcl_OpenTcpServer\fR normally returns a pointer to a channel
405 representing the server socket.
406 If an error occurs, \fBTcl_OpenTcpServer\fR returns NULL and
407 records a POSIX error code that can be retrieved with \fBTcl_GetErrno\fR.
408 In addition, if the interpreter is non-NULL, an error message
409 is left in the interpreter's result.
411 The channel returned by \fBTcl_OpenTcpServer\fR cannot be used for
412 either input or output.
413 It is simply a handle for the socket used to accept connections.
414 The caller can close the channel to shut down the server and disallow
415 further connections from new clients.
417 TCP server channels operate correctly only in applications that dispatch
418 events through \fBTcl_DoOneEvent\fR or through Tcl commands such as
419 \fBvwait\fR; otherwise Tcl will never notice that a connection request from
420 a remote client is pending.
422 The newly created channel is not registered in the supplied interpreter; to
423 register it, use \fBTcl_RegisterChannel\fR.
424 If one of the standard channels, \fBstdin\fR, \fBstdout\fR or \fBstderr\fR was
425 previously closed, the act of creating the new channel also assigns it as a
426 replacement for the standard channel.
427 .SH "PLATFORM ISSUES"
429 On Unix platforms, the socket handle is a Unix file descriptor as
430 returned by the \fBsocket\fR system call. On the Windows platform, the
431 socket handle is a \fBSOCKET\fR as defined in the WinSock API.
433 Tcl_OpenFileChannel(3), Tcl_RegisterChannel(3), vwait(n)
435 channel, client, server, socket, TCP
OSDN Git Service
