170 lines
7.3 KiB
Groff
170 lines
7.3 KiB
Groff
|
'\"
|
||
|
|
'\" Copyright (c) 1996-7 Sun Microsystems, Inc.
|
||
|
|
'\"
|
||
|
|
'\" See the file "license.terms" for information on usage and redistribution
|
||
|
|
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||
|
|
'\"
|
||
|
|
.TH Tcl_OpenTcpClient 3 8.0 Tcl "Tcl Library Procedures"
|
||
|
|
.so man.macros
|
||
|
|
.BS
|
||
|
|
'\" Note: do not modify the .SH NAME line immediately below!
|
||
|
|
.SH NAME
|
||
|
|
Tcl_OpenTcpClient, Tcl_MakeTcpClientChannel, Tcl_OpenTcpServer \- procedures to open channels using TCP sockets
|
||
|
|
.SH SYNOPSIS
|
||
|
|
.nf
|
||
|
|
\fB#include <tcl.h> \fR
|
||
|
|
.sp
|
||
|
|
Tcl_Channel
|
||
|
|
\fBTcl_OpenTcpClient\fR(\fIinterp, port, host, myaddr, myport, async\fR)
|
||
|
|
.sp
|
||
|
|
Tcl_Channel
|
||
|
|
\fBTcl_MakeTcpClientChannel\fR(\fIsock\fR)
|
||
|
|
.sp
|
||
|
|
Tcl_Channel
|
||
|
|
\fBTcl_OpenTcpServer\fR(\fIinterp, port, myaddr, proc, clientData\fR)
|
||
|
|
.sp
|
||
|
|
.SH ARGUMENTS
|
||
|
|
.AS Tcl_TcpAcceptProc clientData
|
||
|
|
.AP Tcl_Interp *interp in
|
||
|
|
Tcl interpreter to use for error reporting. If non-NULL and an
|
||
|
|
error occurs, an error message is left in the interpreter's result.
|
||
|
|
.AP int port in
|
||
|
|
A port number to connect to as a client or to listen on as a server.
|
||
|
|
.AP "const char" *host in
|
||
|
|
A string specifying a host name or address for the remote end of the connection.
|
||
|
|
.AP int myport in
|
||
|
|
A port number for the client's end of the socket. If 0, a port number
|
||
|
|
is allocated at random.
|
||
|
|
.AP "const char" *myaddr in
|
||
|
|
A string specifying the host name or address for network interface to use
|
||
|
|
for the local end of the connection. If NULL, a default interface is
|
||
|
|
chosen.
|
||
|
|
.AP int async in
|
||
|
|
If nonzero, the client socket is connected asynchronously to the server.
|
||
|
|
.AP ClientData sock in
|
||
|
|
Platform-specific handle for client TCP socket.
|
||
|
|
.AP Tcl_TcpAcceptProc *proc in
|
||
|
|
Pointer to a procedure to invoke each time a new connection is
|
||
|
|
accepted via the socket.
|
||
|
|
.AP ClientData clientData in
|
||
|
|
Arbitrary one-word value to pass to \fIproc\fR.
|
||
|
|
.BE
|
||
|
|
.SH DESCRIPTION
|
||
|
|
.PP
|
||
|
|
These functions are convenience procedures for creating
|
||
|
|
channels that communicate over TCP sockets.
|
||
|
|
The operations on a channel
|
||
|
|
are described in the manual entry for \fBTcl_OpenFileChannel\fR.
|
||
|
|
.SS TCL_OPENTCPCLIENT
|
||
|
|
.PP
|
||
|
|
\fBTcl_OpenTcpClient\fR opens a client TCP socket connected to a \fIport\fR
|
||
|
|
on a specific \fIhost\fR, and returns a channel that can be used to
|
||
|
|
communicate with the server. The host to connect to can be specified either
|
||
|
|
as a domain name style name (e.g. \fBwww.sunlabs.com\fR), or as a string
|
||
|
|
containing the alphanumeric representation of its four-byte address (e.g.
|
||
|
|
\fB127.0.0.1\fR). Use the string \fBlocalhost\fR to connect to a TCP socket on
|
||
|
|
the host on which the function is invoked.
|
||
|
|
.PP
|
||
|
|
The \fImyaddr\fR and \fImyport\fR arguments allow a client to specify an
|
||
|
|
address for the local end of the connection. If \fImyaddr\fR is NULL, then
|
||
|
|
an interface is chosen automatically by the operating system.
|
||
|
|
If \fImyport\fR is 0, then a port number is chosen at random by
|
||
|
|
the operating system.
|
||
|
|
.PP
|
||
|
|
If \fIasync\fR is zero, the call to \fBTcl_OpenTcpClient\fR returns only
|
||
|
|
after the client socket has either successfully connected to the server, or
|
||
|
|
the attempted connection has failed.
|
||
|
|
If \fIasync\fR is nonzero the socket is connected asynchronously and the
|
||
|
|
returned channel may not yet be connected to the server when the call to
|
||
|
|
\fBTcl_OpenTcpClient\fR returns. If the channel is in blocking mode and an
|
||
|
|
input or output operation is done on the channel before the connection is
|
||
|
|
completed or fails, that operation will wait until the connection either
|
||
|
|
completes successfully or fails. If the channel is in nonblocking mode, the
|
||
|
|
input or output operation will return immediately and a subsequent call to
|
||
|
|
\fBTcl_InputBlocked\fR on the channel will return nonzero.
|
||
|
|
.PP
|
||
|
|
The returned channel is opened for reading and writing.
|
||
|
|
If an error occurs in opening the socket, \fBTcl_OpenTcpClient\fR returns
|
||
|
|
NULL and records a POSIX error code that can be retrieved
|
||
|
|
with \fBTcl_GetErrno\fR.
|
||
|
|
In addition, if \fIinterp\fR is non-NULL, an error message
|
||
|
|
is left in the interpreter's result.
|
||
|
|
.PP
|
||
|
|
The newly created channel is not registered in the supplied interpreter; to
|
||
|
|
register it, use \fBTcl_RegisterChannel\fR.
|
||
|
|
If one of the standard channels, \fBstdin\fR, \fBstdout\fR or \fBstderr\fR was
|
||
|
|
previously closed, the act of creating the new channel also assigns it as a
|
||
|
|
replacement for the standard channel.
|
||
|
|
.SS TCL_MAKETCPCLIENTCHANNEL
|
||
|
|
.PP
|
||
|
|
\fBTcl_MakeTcpClientChannel\fR creates a \fBTcl_Channel\fR around an
|
||
|
|
existing, platform specific, handle for a client TCP socket.
|
||
|
|
.PP
|
||
|
|
The newly created channel is not registered in the supplied interpreter; to
|
||
|
|
register it, use \fBTcl_RegisterChannel\fR.
|
||
|
|
If one of the standard channels, \fBstdin\fR, \fBstdout\fR or \fBstderr\fR was
|
||
|
|
previously closed, the act of creating the new channel also assigns it as a
|
||
|
|
replacement for the standard channel.
|
||
|
|
.SS TCL_OPENTCPSERVER
|
||
|
|
.PP
|
||
|
|
\fBTcl_OpenTcpServer\fR opens a TCP socket on the local host on a specified
|
||
|
|
\fIport\fR and uses the Tcl event mechanism to accept requests from clients
|
||
|
|
to connect to it. The \fImyaddr\fR argument specifies the network interface.
|
||
|
|
If \fImyaddr\fR is NULL the special address INADDR_ANY should be used to
|
||
|
|
allow connections from any network interface.
|
||
|
|
Each time a client connects to this socket, Tcl creates a channel
|
||
|
|
for the new connection and invokes \fIproc\fR with information about
|
||
|
|
the channel. \fIProc\fR must match the following prototype:
|
||
|
|
.PP
|
||
|
|
.CS
|
||
|
|
typedef void \fBTcl_TcpAcceptProc\fR(
|
||
|
|
ClientData \fIclientData\fR,
|
||
|
|
Tcl_Channel \fIchannel\fR,
|
||
|
|
char *\fIhostName\fR,
|
||
|
|
int \fIport\fR);
|
||
|
|
.CE
|
||
|
|
.PP
|
||
|
|
The \fIclientData\fR argument will be the same as the \fIclientData\fR
|
||
|
|
argument to \fBTcl_OpenTcpServer\fR, \fIchannel\fR will be the handle
|
||
|
|
for the new channel, \fIhostName\fR points to a string containing
|
||
|
|
the name of the client host making the connection, and \fIport\fR
|
||
|
|
will contain the client's port number.
|
||
|
|
The new channel
|
||
|
|
is opened for both input and output.
|
||
|
|
If \fIproc\fR raises an error, the connection is closed automatically.
|
||
|
|
\fIProc\fR has no return value, but if it wishes to reject the
|
||
|
|
connection it can close \fIchannel\fR.
|
||
|
|
.PP
|
||
|
|
\fBTcl_OpenTcpServer\fR normally returns a pointer to a channel
|
||
|
|
representing the server socket.
|
||
|
|
If an error occurs, \fBTcl_OpenTcpServer\fR returns NULL and
|
||
|
|
records a POSIX error code that can be retrieved with \fBTcl_GetErrno\fR.
|
||
|
|
In addition, if the interpreter is non-NULL, an error message
|
||
|
|
is left in the interpreter's result.
|
||
|
|
.PP
|
||
|
|
The channel returned by \fBTcl_OpenTcpServer\fR cannot be used for
|
||
|
|
either input or output.
|
||
|
|
It is simply a handle for the socket used to accept connections.
|
||
|
|
The caller can close the channel to shut down the server and disallow
|
||
|
|
further connections from new clients.
|
||
|
|
.PP
|
||
|
|
TCP server channels operate correctly only in applications that dispatch
|
||
|
|
events through \fBTcl_DoOneEvent\fR or through Tcl commands such as
|
||
|
|
\fBvwait\fR; otherwise Tcl will never notice that a connection request from
|
||
|
|
a remote client is pending.
|
||
|
|
.PP
|
||
|
|
The newly created channel is not registered in the supplied interpreter; to
|
||
|
|
register it, use \fBTcl_RegisterChannel\fR.
|
||
|
|
If one of the standard channels, \fBstdin\fR, \fBstdout\fR or \fBstderr\fR was
|
||
|
|
previously closed, the act of creating the new channel also assigns it as a
|
||
|
|
replacement for the standard channel.
|
||
|
|
.SH "PLATFORM ISSUES"
|
||
|
|
.PP
|
||
|
|
On Unix platforms, the socket handle is a Unix file descriptor as
|
||
|
|
returned by the \fBsocket\fR system call. On the Windows platform, the
|
||
|
|
socket handle is a \fBSOCKET\fR as defined in the WinSock API.
|
||
|
|
.SH "SEE ALSO"
|
||
|
|
Tcl_OpenFileChannel(3), Tcl_RegisterChannel(3), vwait(n)
|
||
|
|
.SH KEYWORDS
|
||
|
|
channel, client, server, socket, TCP
|