Initial release
This commit is contained in:
unknown
147
hlp/en/tcl/socket.htm
Normal file
147
hlp/en/tcl/socket.htm
Normal file
@@ -0,0 +1,147 @@
|
||||
<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>
|
||||
Reference in New Issue
Block a user