148 lines
7.8 KiB
HTML
148 lines
7.8 KiB
HTML
<HTML><HEAD><TITLE>Tcl Built-In Commands - socket manual page</TITLE></HEAD><BODY>
|
|
<DL>
|
|
<DD><A HREF="socket.htm#M2" NAME="L1080">NAME</A>
|
|
<DL><DD>socket - Open a TCP network connection</DL>
|
|
<DD><A HREF="socket.htm#M3" NAME="L1081">SYNOPSIS</A>
|
|
<DL>
|
|
<DD><B>socket </B>?<I>options</I>? <I>host port</I>
|
|
<DD><B>socket</B> <B>-server </B><I>command</I> ?<I>options</I>? <I>port</I>
|
|
</DL>
|
|
<DD><A HREF="socket.htm#M4" NAME="L1082">DESCRIPTION</A>
|
|
<DD><A HREF="socket.htm#M5" NAME="L1083">CLIENT SOCKETS</A>
|
|
<DL>
|
|
<DD><A HREF="socket.htm#M6" NAME="L1084"><B>-myaddr</B><I> addr</I></A>
|
|
<DD><A HREF="socket.htm#M7" NAME="L1085"><B>-myport</B><I> port</I></A>
|
|
<DD><A HREF="socket.htm#M8" NAME="L1086"><B>-async</B></A>
|
|
</DL>
|
|
<DD><A HREF="socket.htm#M9" NAME="L1087">SERVER SOCKETS</A>
|
|
<DL>
|
|
<DD><A HREF="socket.htm#M10" NAME="L1088"><B>-myaddr</B><I> addr</I></A>
|
|
</DL>
|
|
<DD><A HREF="socket.htm#M11" NAME="L1089">CONFIGURATION OPTIONS</A>
|
|
<DL>
|
|
<DD><A HREF="socket.htm#M12" NAME="L1090"><B>-error</B></A>
|
|
<DD><A HREF="socket.htm#M13" NAME="L1091"><B>-sockname</B></A>
|
|
<DD><A HREF="socket.htm#M14" NAME="L1092"><B>-peername</B></A>
|
|
</DL>
|
|
<DD><A HREF="socket.htm#M15" NAME="L1093">SEE ALSO</A>
|
|
<DD><A HREF="socket.htm#M16" NAME="L1094">KEYWORDS</A>
|
|
</DL><HR>
|
|
<H3><A NAME="M2">NAME</A></H3>
|
|
socket - Open a TCP network connection
|
|
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
|
<B>socket </B>?<I>options</I>? <I>host port</I><BR>
|
|
<B>socket</B> <B>-server </B><I>command</I> ?<I>options</I>? <I>port</I><BR>
|
|
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
|
This command opens a network socket and returns a channel
|
|
identifier that may be used in future invocations of commands like
|
|
<B><A HREF="../TkCmd/read.htm">read</A></B>, <B><A HREF="../TkCmd/puts.htm">puts</A></B> and <B><A HREF="../TkCmd/flush.htm">flush</A></B>.
|
|
At present only the TCP network protocol is supported; future
|
|
releases may include support for additional protocols.
|
|
The <B>socket</B> command may be used to open either the client or
|
|
server side of a connection, depending on whether the <B>-server</B>
|
|
switch is specified.
|
|
|
|
<H3><A NAME="M5">CLIENT SOCKETS</A></H3>
|
|
If the <B>-server</B> option is not specified, then the client side of a
|
|
connection is opened and the command returns a channel identifier
|
|
that can be used for both reading and writing.
|
|
<I>Port</I> and <I>host</I> specify a port
|
|
to connect to; there must be a server accepting connections on
|
|
this port. <I>Port</I> is an integer port number and <I>host</I>
|
|
is either a domain-style name such as <B>www.sunlabs.com</B> or
|
|
a numerical IP address such as <B>127.0.0.1</B>.
|
|
Use <I>localhost</I> to refer to the host on which the command is invoked.
|
|
<P>
|
|
The following options may also be present before <I>host</I>
|
|
to specify additional information about the connection:
|
|
<P>
|
|
<DL>
|
|
<P><DT><A NAME="M6"><B>-myaddr</B><I> addr</I></A><DD>
|
|
<I>Addr</I> gives the domain-style name or numerical IP address of
|
|
the client-side network interface to use for the connection.
|
|
This option may be useful if the client machine has multiple network
|
|
interfaces. If the option is omitted then the client-side interface
|
|
will be chosen by the system software.
|
|
<P><DT><A NAME="M7"><B>-myport</B><I> port</I></A><DD>
|
|
<I>Port</I> specifies an integer port number to use for the client's
|
|
side of the connection. If this option is omitted, the client's
|
|
port number will be chosen at random by the system software.
|
|
<P><DT><A NAME="M8"><B>-async</B></A><DD>
|
|
The <B>-async</B> option will cause the client socket to be connected
|
|
asynchronously. This means that the socket will be created immediately but
|
|
may not yet be connected to the server, when the call to <B>socket</B>
|
|
returns. When a <B><A HREF="../TkCmd/gets.htm">gets</A></B> or <B><A HREF="../TkCmd/flush.htm">flush</A></B> is done on the socket before the
|
|
connection attempt succeeds or fails, if the socket is in blocking mode, the
|
|
operation will wait until the connection is completed or fails. If the
|
|
socket is in nonblocking mode and a <B><A HREF="../TkCmd/gets.htm">gets</A></B> or <B><A HREF="../TkCmd/flush.htm">flush</A></B> is done on
|
|
the socket before the connection attempt succeeds or fails, the operation
|
|
returns immediately and <B><A HREF="../TkCmd/fblocked.htm">fblocked</A></B> on the socket returns 1.
|
|
|
|
<P></DL>
|
|
<H3><A NAME="M9">SERVER SOCKETS</A></H3>
|
|
If the <B>-server</B> option is specified then the new socket
|
|
will be a server for the port given by <I>port</I>.
|
|
Tcl will automatically accept connections to the given port.
|
|
For each connection Tcl will create a new channel that may be used to
|
|
communicate with the client. Tcl then invokes <I>command</I>
|
|
with three additional arguments: the name of the new channel, the
|
|
address, in network address notation, of the client's host, and
|
|
the client's port number.
|
|
<P>
|
|
The following additional option may also be specified before <I>host</I>:
|
|
<P>
|
|
<DL>
|
|
<P><DT><A NAME="M10"><B>-myaddr</B><I> addr</I></A><DD>
|
|
<I>Addr</I> gives the domain-style name or numerical IP address of
|
|
the server-side network interface to use for the connection.
|
|
This option may be useful if the server machine has multiple network
|
|
interfaces. If the option is omitted then the server socket is bound
|
|
to the special address INADDR_ANY so that it can accept connections from
|
|
any interface.
|
|
<P></DL>
|
|
<P>
|
|
Server channels cannot be used for input or output; their sole use is to
|
|
accept new client connections. The channels created for each incoming
|
|
client connection are opened for input and output. Closing the server
|
|
channel shuts down the server so that no new connections will be
|
|
accepted; however, existing connections will be unaffected.
|
|
<P>
|
|
Server sockets depend on the Tcl event mechanism to find out when
|
|
new connections are opened. If the application doesn't enter the
|
|
event loop, for example by invoking the <B><A HREF="../TkCmd/vwait.htm">vwait</A></B> command or
|
|
calling the C procedure <B><A HREF="../TkLib/DoOneEvent.htm">Tcl_DoOneEvent</A></B>, then no connections
|
|
will be accepted.
|
|
|
|
<H3><A NAME="M11">CONFIGURATION OPTIONS</A></H3>
|
|
The <B><A HREF="../TkCmd/fconfigure.htm">fconfigure</A></B> command can be used to query several readonly
|
|
configuration options for socket channels:
|
|
<P>
|
|
<DL>
|
|
<P><DT><A NAME="M12"><B>-error</B></A><DD>
|
|
This option gets the current error status of the given socket. This
|
|
is useful when you need to determine if an asynchronous connect
|
|
operation succeeded. If there was an error, the error message is
|
|
returned. If there was no error, an empty string is returned.
|
|
<P><DT><A NAME="M13"><B>-sockname</B></A><DD>
|
|
This option returns a list of three elements, the address, the host name
|
|
and the port number for the socket. If the host name cannot be computed,
|
|
the second element is identical to the address, the first element of the
|
|
list.
|
|
<P><DT><A NAME="M14"><B>-peername</B></A><DD>
|
|
This option is not supported by server sockets. For client and accepted
|
|
sockets, this option returns a list of three elements; these are the
|
|
address, the host name and the port to which the peer socket is connected
|
|
or bound. If the host name cannot be computed, the second element of the
|
|
list is identical to the address, its first element.
|
|
<P></DL>
|
|
<P>
|
|
<H3><A NAME="M15">SEE ALSO</A></H3>
|
|
<B><A HREF="../TkCmd/flush.htm">flush</A></B>, <B><A HREF="../TkCmd/open.htm">open</A></B>, <B><A HREF="../TkCmd/read.htm">read</A></B>
|
|
<H3><A NAME="M16">KEYWORDS</A></H3>
|
|
<A href="../Keywords/B.htm#bind">bind</A>, <A href="../Keywords/C.htm#channel">channel</A>, <A href="../Keywords/C.htm#connection">connection</A>, <A href="../Keywords/D.htm#domain name">domain name</A>, <A href="../Keywords/H.htm#host">host</A>, <A href="../Keywords/N.htm#network address">network address</A>, <A href="../Keywords/S.htm#socket">socket</A>, <A href="../Keywords/T.htm#tcp">tcp</A>
|
|
<HR><PRE>
|
|
<A HREF="../copyright.htm">Copyright</A> © 1996 Sun Microsystems, Inc.
|
|
<A HREF="../copyright.htm">Copyright</A> © 1998-1999 by Scriptics Corporation.
|
|
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
|
</BODY></HTML>
|