Subversion Repositories or1k

'\"

'\" 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.

'\"

'\" RCS: @(#) $Id: OpenTcp.3,v 1.1.1.1 2002-01-16 10:25:24 markom Exp $

.so man.macros

.TH Tcl_OpenTcpClient 3 8.0 Tcl "Tcl Library Procedures"

.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  \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_ChannelType newClientProcPtr in

.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 \fIinterp->result\fR.

.AP int port in

A port number to connect to as a client or to listen on as a server.

.AP 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 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.

.SH 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 \fIinterp->result\fR.

.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, stdout\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 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, stdout\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 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\fP argument specifies the network interface.

If \fImyaddr\fP 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:

.CS

typedef void Tcl_TcpAcceptProc(

        ClientData \fIclientData\fR,

        Tcl_Channel \fIchannel\fR,

        char *\fIhostName\fR,

        int \fIport\fP);

.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\fP

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 \fIinterp->result\fR is non-NULL, an error message

is left in \fIinterp->result\fR.

.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, stdout\fR or \fBstderr\fR was

previously closed, the act of creating the new channel also assigns it as a

replacement for the standard channel.

.VS

.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.  On the

Macintosh platform, the socket handle is a \fBStreamPtr\fR.

.VE

.SH "SEE ALSO"

Tcl_OpenFileChannel(3), Tcl_RegisterChannel(3), vwait(n)

.SH KEYWORDS

client, server, TCP