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 | '\" RCS: @(#) $Id: OpenTcp.3,v 1.11 2006/11/15 09:23:01 dkf Exp $ |
---|
8 | .so man.macros |
---|
9 | .TH Tcl_OpenTcpClient 3 8.0 Tcl "Tcl Library Procedures" |
---|
10 | .BS |
---|
11 | '\" Note: do not modify the .SH NAME line immediately below! |
---|
12 | .SH NAME |
---|
13 | Tcl_OpenTcpClient, Tcl_MakeTcpClientChannel, Tcl_OpenTcpServer \- procedures to open channels using TCP sockets |
---|
14 | .SH SYNOPSIS |
---|
15 | .nf |
---|
16 | \fB#include <tcl.h> \fR |
---|
17 | .sp |
---|
18 | Tcl_Channel |
---|
19 | \fBTcl_OpenTcpClient\fR(\fIinterp, port, host, myaddr, myport, async\fR) |
---|
20 | .sp |
---|
21 | Tcl_Channel |
---|
22 | \fBTcl_MakeTcpClientChannel\fR(\fIsock\fR) |
---|
23 | .sp |
---|
24 | Tcl_Channel |
---|
25 | \fBTcl_OpenTcpServer\fR(\fIinterp, port, myaddr, proc, clientData\fR) |
---|
26 | .sp |
---|
27 | .SH ARGUMENTS |
---|
28 | .AS Tcl_TcpAcceptProc clientData |
---|
29 | .AP Tcl_Interp *interp in |
---|
30 | Tcl interpreter to use for error reporting. If non-NULL and an |
---|
31 | error occurs, an error message is left in the interpreter's result. |
---|
32 | .AP int port in |
---|
33 | A port number to connect to as a client or to listen on as a server. |
---|
34 | .AP "const char" *host in |
---|
35 | A string specifying a host name or address for the remote end of the connection. |
---|
36 | .AP int myport in |
---|
37 | A port number for the client's end of the socket. If 0, a port number |
---|
38 | is allocated at random. |
---|
39 | .AP "const char" *myaddr in |
---|
40 | A string specifying the host name or address for network interface to use |
---|
41 | for the local end of the connection. If NULL, a default interface is |
---|
42 | chosen. |
---|
43 | .AP int async in |
---|
44 | If nonzero, the client socket is connected asynchronously to the server. |
---|
45 | .AP ClientData sock in |
---|
46 | Platform-specific handle for client TCP socket. |
---|
47 | .AP Tcl_TcpAcceptProc *proc in |
---|
48 | Pointer to a procedure to invoke each time a new connection is |
---|
49 | accepted via the socket. |
---|
50 | .AP ClientData clientData in |
---|
51 | Arbitrary one-word value to pass to \fIproc\fR. |
---|
52 | .BE |
---|
53 | |
---|
54 | .SH DESCRIPTION |
---|
55 | .PP |
---|
56 | These functions are convenience procedures for creating |
---|
57 | channels that communicate over TCP sockets. |
---|
58 | The operations on a channel |
---|
59 | are described in the manual entry for \fBTcl_OpenFileChannel\fR. |
---|
60 | |
---|
61 | .SH TCL_OPENTCPCLIENT |
---|
62 | .PP |
---|
63 | \fBTcl_OpenTcpClient\fR opens a client TCP socket connected to a \fIport\fR |
---|
64 | on a specific \fIhost\fR, and returns a channel that can be used to |
---|
65 | communicate with the server. The host to connect to can be specified either |
---|
66 | as a domain name style name (e.g. \fBwww.sunlabs.com\fR), or as a string |
---|
67 | containing the alphanumeric representation of its four-byte address (e.g. |
---|
68 | \fB127.0.0.1\fR). Use the string \fBlocalhost\fR to connect to a TCP socket on |
---|
69 | the host on which the function is invoked. |
---|
70 | .PP |
---|
71 | The \fImyaddr\fR and \fImyport\fR arguments allow a client to specify an |
---|
72 | address for the local end of the connection. If \fImyaddr\fR is NULL, then |
---|
73 | an interface is chosen automatically by the operating system. |
---|
74 | If \fImyport\fR is 0, then a port number is chosen at random by |
---|
75 | the operating system. |
---|
76 | .PP |
---|
77 | If \fIasync\fR is zero, the call to \fBTcl_OpenTcpClient\fR returns only |
---|
78 | after the client socket has either successfully connected to the server, or |
---|
79 | the attempted connection has failed. |
---|
80 | If \fIasync\fR is nonzero the socket is connected asynchronously and the |
---|
81 | returned channel may not yet be connected to the server when the call to |
---|
82 | \fBTcl_OpenTcpClient\fR returns. If the channel is in blocking mode and an |
---|
83 | input or output operation is done on the channel before the connection is |
---|
84 | completed or fails, that operation will wait until the connection either |
---|
85 | completes successfully or fails. If the channel is in nonblocking mode, the |
---|
86 | input or output operation will return immediately and a subsequent call to |
---|
87 | \fBTcl_InputBlocked\fR on the channel will return nonzero. |
---|
88 | .PP |
---|
89 | The returned channel is opened for reading and writing. |
---|
90 | If an error occurs in opening the socket, \fBTcl_OpenTcpClient\fR returns |
---|
91 | NULL and records a POSIX error code that can be retrieved |
---|
92 | with \fBTcl_GetErrno\fR. |
---|
93 | In addition, if \fIinterp\fR is non-NULL, an error message |
---|
94 | is left in the interpreter's result. |
---|
95 | .PP |
---|
96 | The newly created channel is not registered in the supplied interpreter; to |
---|
97 | register it, use \fBTcl_RegisterChannel\fR. |
---|
98 | If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was |
---|
99 | previously closed, the act of creating the new channel also assigns it as a |
---|
100 | replacement for the standard channel. |
---|
101 | |
---|
102 | .SH TCL_MAKETCPCLIENTCHANNEL |
---|
103 | .PP |
---|
104 | \fBTcl_MakeTcpClientChannel\fR creates a \fBTcl_Channel\fR around an |
---|
105 | existing, platform specific, handle for a client TCP socket. |
---|
106 | .PP |
---|
107 | The newly created channel is not registered in the supplied interpreter; to |
---|
108 | register it, use \fBTcl_RegisterChannel\fR. |
---|
109 | If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was |
---|
110 | previously closed, the act of creating the new channel also assigns it as a |
---|
111 | replacement for the standard channel. |
---|
112 | |
---|
113 | .SH TCL_OPENTCPSERVER |
---|
114 | .PP |
---|
115 | \fBTcl_OpenTcpServer\fR opens a TCP socket on the local host on a specified |
---|
116 | \fIport\fR and uses the Tcl event mechanism to accept requests from clients |
---|
117 | to connect to it. The \fImyaddr\fR argument specifies the network interface. |
---|
118 | If \fImyaddr\fR is NULL the special address INADDR_ANY should be used to |
---|
119 | allow connections from any network interface. |
---|
120 | Each time a client connects to this socket, Tcl creates a channel |
---|
121 | for the new connection and invokes \fIproc\fR with information about |
---|
122 | the channel. \fIProc\fR must match the following prototype: |
---|
123 | .CS |
---|
124 | typedef void Tcl_TcpAcceptProc( |
---|
125 | ClientData \fIclientData\fR, |
---|
126 | Tcl_Channel \fIchannel\fR, |
---|
127 | char *\fIhostName\fR, |
---|
128 | int \fIport\fR); |
---|
129 | .CE |
---|
130 | .PP |
---|
131 | The \fIclientData\fR argument will be the same as the \fIclientData\fR |
---|
132 | argument to \fBTcl_OpenTcpServer\fR, \fIchannel\fR will be the handle |
---|
133 | for the new channel, \fIhostName\fR points to a string containing |
---|
134 | the name of the client host making the connection, and \fIport\fR |
---|
135 | will contain the client's port number. |
---|
136 | The new channel |
---|
137 | is opened for both input and output. |
---|
138 | If \fIproc\fR raises an error, the connection is closed automatically. |
---|
139 | \fIProc\fR has no return value, but if it wishes to reject the |
---|
140 | connection it can close \fIchannel\fR. |
---|
141 | .PP |
---|
142 | \fBTcl_OpenTcpServer\fR normally returns a pointer to a channel |
---|
143 | representing the server socket. |
---|
144 | If an error occurs, \fBTcl_OpenTcpServer\fR returns NULL and |
---|
145 | records a POSIX error code that can be retrieved with \fBTcl_GetErrno\fR. |
---|
146 | In addition, if the interpreter is non-NULL, an error message |
---|
147 | is left in the interpreter's result. |
---|
148 | .PP |
---|
149 | The channel returned by \fBTcl_OpenTcpServer\fR cannot be used for |
---|
150 | either input or output. |
---|
151 | It is simply a handle for the socket used to accept connections. |
---|
152 | The caller can close the channel to shut down the server and disallow |
---|
153 | further connections from new clients. |
---|
154 | .PP |
---|
155 | TCP server channels operate correctly only in applications that dispatch |
---|
156 | events through \fBTcl_DoOneEvent\fR or through Tcl commands such as |
---|
157 | \fBvwait\fR; otherwise Tcl will never notice that a connection request from |
---|
158 | a remote client is pending. |
---|
159 | .PP |
---|
160 | The newly created channel is not registered in the supplied interpreter; to |
---|
161 | register it, use \fBTcl_RegisterChannel\fR. |
---|
162 | If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was |
---|
163 | previously closed, the act of creating the new channel also assigns it as a |
---|
164 | replacement for the standard channel. |
---|
165 | |
---|
166 | .SH "PLATFORM ISSUES" |
---|
167 | .PP |
---|
168 | On Unix platforms, the socket handle is a Unix file descriptor as |
---|
169 | returned by the \fBsocket\fR system call. On the Windows platform, the |
---|
170 | socket handle is a \fBSOCKET\fR as defined in the WinSock API. |
---|
171 | |
---|
172 | .SH "SEE ALSO" |
---|
173 | Tcl_OpenFileChannel(3), Tcl_RegisterChannel(3), vwait(n) |
---|
174 | |
---|
175 | .SH KEYWORDS |
---|
176 | client, server, TCP |
---|