[OpenSPARC-T2-DV] / tools / src / nas,5.n2.os.2 / lib / python / html / python / lib / socket-objects.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index' />
<link rel="first" href="lib.html" title='Python Library Reference' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="ssl-objects.html" />
<link rel="prev" href="module-socket.html" />
<link rel="parent" href="module-socket.html" />
<link rel="next" href="ssl-objects.html" />
<meta name='aesop' content='information' />
<title>7.2.1 Socket Objects </title>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="7.2 socket  "
  href="module-socket.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="7.2 socket  "
  href="module-socket.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="7.2.2 SSL Objects"
  href="ssl-objects.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="module-socket.html">7.2 socket  </A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-socket.html">7.2 socket  </A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="ssl-objects.html">7.2.2 SSL Objects</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H2><A NAME="SECTION009210000000000000000"></A><A NAME="socket-objects"></A>
<BR>
7.2.1 Socket Objects 
</H2>

<P>
Socket objects have the following methods.  Except for
<tt class="method">makefile()</tt> these correspond to <span class="Unix">Unix</span> system calls
applicable to sockets.

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2650' xml:id='l2h-2650' class="method">accept</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Accept a connection.
The socket must be bound to an address and listening for connections.
The return value is a pair <code>(<var>conn</var>, <var>address</var>)</code>
where <var>conn</var> is a <em>new</em> socket object usable to send and
receive data on the connection, and <var>address</var> is the address bound
to the socket on the other end of the connection.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2651' xml:id='l2h-2651' class="method">bind</tt></b>(</nobr></td>
  <td><var>address</var>)</td></tr></table></dt>
<dd>
Bind the socket to <var>address</var>.  The socket must not already be bound.
(The format of <var>address</var> depends on the address family -- see
above.)  <span class="note"><b class="label">Note:</b>
This method has historically accepted a pair
of parameters for <tt class="constant">AF_INET</tt> addresses instead of only a
tuple.  This was never intentional and is no longer available in
Python 2.0 and later.</span>
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2652' xml:id='l2h-2652' class="method">close</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Close the socket.  All future operations on the socket object will fail.
The remote end will receive no more data (after queued data is flushed).
Sockets are automatically closed when they are garbage-collected.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2653' xml:id='l2h-2653' class="method">connect</tt></b>(</nobr></td>
  <td><var>address</var>)</td></tr></table></dt>
<dd>
Connect to a remote socket at <var>address</var>.
(The format of <var>address</var> depends on the address family -- see
above.)  <span class="note"><b class="label">Note:</b>
This method has historically accepted a pair
of parameters for <tt class="constant">AF_INET</tt> addresses instead of only a
tuple.  This was never intentional and is no longer available in
Python 2.0 and later.</span>
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2654' xml:id='l2h-2654' class="method">connect_ex</tt></b>(</nobr></td>
  <td><var>address</var>)</td></tr></table></dt>
<dd>
Like <code>connect(<var>address</var>)</code>, but return an error indicator
instead of raising an exception for errors returned by the C-level
<tt class="cfunction">connect()</tt> call (other problems, such as ``host not found,''
can still raise exceptions).  The error indicator is <code>0</code> if the
operation succeeded, otherwise the value of the <tt class="cdata">errno</tt>
variable.  This is useful to support, for example, asynchronous connects.
<span class="note"><b class="label">Note:</b>
This method has historically accepted a pair of
parameters for <tt class="constant">AF_INET</tt> addresses instead of only a tuple.
This was never intentional and is no longer available in Python
2.0 and later.</span>
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2655' xml:id='l2h-2655' class="method">fileno</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Return the socket's file descriptor (a small integer).  This is useful
with <tt class="function">select.select()</tt>.

<P>
Under Windows the small integer returned by this method cannot be used where
a file descriptor can be used (such as <tt class="function">os.fdopen()</tt>).  <span class="Unix">Unix</span> does
not have this limitation.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2656' xml:id='l2h-2656' class="method">getpeername</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Return the remote address to which the socket is connected.  This is
useful to find out the port number of a remote IPv4/v6 socket, for instance.
(The format of the address returned depends on the address family --
see above.)  On some systems this function is not supported.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2657' xml:id='l2h-2657' class="method">getsockname</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Return the socket's own address.  This is useful to find out the port
number of an IPv4/v6 socket, for instance.
(The format of the address returned depends on the address family --
see above.)
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2658' xml:id='l2h-2658' class="method">getsockopt</tt></b>(</nobr></td>
  <td><var>level, optname</var><big>[</big><var>, buflen</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Return the value of the given socket option (see the <span class="Unix">Unix</span> man page
<span class="manpage"><i>getsockopt</i>(2)</span>).  The needed symbolic constants
(<tt class="constant">SO_*</tt> etc.) are defined in this module.  If <var>buflen</var>
is absent, an integer option is assumed and its integer value
is returned by the function.  If <var>buflen</var> is present, it specifies
the maximum length of the buffer used to receive the option in, and
this buffer is returned as a string.  It is up to the caller to decode
the contents of the buffer (see the optional built-in module
<tt class="module"><a href="module-struct.html">struct</a></tt> for a way to decode C structures encoded as strings).
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2659' xml:id='l2h-2659' class="method">listen</tt></b>(</nobr></td>
  <td><var>backlog</var>)</td></tr></table></dt>
<dd>
Listen for connections made to the socket.  The <var>backlog</var> argument
specifies the maximum number of queued connections and should be at
least 1; the maximum value is system-dependent (usually 5).
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2660' xml:id='l2h-2660' class="method">makefile</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>mode</var><big>[</big><var>, bufsize</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Return a <i class="dfn">file object</i> associated with the socket.  (File objects
are described in <A href="bltin-file-objects.html#bltin-file-objects">2.3.9</A>, ``File Objects.'')
The file object references a <tt class="cfunction">dup()</tt>ped version of the
socket file descriptor, so the file object and socket object may be
closed or garbage-collected independently.
The socket should be in blocking mode.
<a id='l2h-2671' xml:id='l2h-2671'></a>The optional <var>mode</var>
and <var>bufsize</var> arguments are interpreted the same way as by the
built-in <tt class="function">file()</tt> function; see ``Built-in Functions''
(section <A href="built-in-funcs.html#built-in-funcs">2.1</A>) for more information.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2661' xml:id='l2h-2661' class="method">recv</tt></b>(</nobr></td>
  <td><var>bufsize</var><big>[</big><var>, flags</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Receive data from the socket.  The return value is a string representing
the data received.  The maximum amount of data to be received
at once is specified by <var>bufsize</var>.  See the <span class="Unix">Unix</span> manual page
<span class="manpage"><i>recv</i>(2)</span> for the meaning of the optional argument
<var>flags</var>; it defaults to zero.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2662' xml:id='l2h-2662' class="method">recvfrom</tt></b>(</nobr></td>
  <td><var>bufsize</var><big>[</big><var>, flags</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Receive data from the socket.  The return value is a pair
<code>(<var>string</var>, <var>address</var>)</code> where <var>string</var> is a string
representing the data received and <var>address</var> is the address of the
socket sending the data.  The optional <var>flags</var> argument has the
same meaning as for <tt class="method">recv()</tt> above.
(The format of <var>address</var> depends on the address family -- see above.)
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2663' xml:id='l2h-2663' class="method">send</tt></b>(</nobr></td>
  <td><var>string</var><big>[</big><var>, flags</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Send data to the socket.  The socket must be connected to a remote
socket.  The optional <var>flags</var> argument has the same meaning as for
<tt class="method">recv()</tt> above.  Returns the number of bytes sent.
Applications are responsible for checking that all data has been sent;
if only some of the data was transmitted, the application needs to
attempt delivery of the remaining data.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2664' xml:id='l2h-2664' class="method">sendall</tt></b>(</nobr></td>
  <td><var>string</var><big>[</big><var>, flags</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Send data to the socket.  The socket must be connected to a remote
socket.  The optional <var>flags</var> argument has the same meaning as for
<tt class="method">recv()</tt> above.  Unlike <tt class="method">send()</tt>, this method continues
to send data from <var>string</var> until either all data has been sent or
an error occurs.  <code>None</code> is returned on success.  On error, an
exception is raised, and there is no way to determine how much data,
if any, was successfully sent.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2665' xml:id='l2h-2665' class="method">sendto</tt></b>(</nobr></td>
  <td><var>string</var><big>[</big><var>, flags</var><big>]</big><var>, address</var>)</td></tr></table></dt>
<dd>
Send data to the socket.  The socket should not be connected to a
remote socket, since the destination socket is specified by
<var>address</var>.  The optional <var>flags</var> argument has the same
meaning as for <tt class="method">recv()</tt> above.  Return the number of bytes sent.
(The format of <var>address</var> depends on the address family -- see above.)
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2666' xml:id='l2h-2666' class="method">setblocking</tt></b>(</nobr></td>
  <td><var>flag</var>)</td></tr></table></dt>
<dd>
Set blocking or non-blocking mode of the socket: if <var>flag</var> is 0,
the socket is set to non-blocking, else to blocking mode.  Initially
all sockets are in blocking mode.  In non-blocking mode, if a
<tt class="method">recv()</tt> call doesn't find any data, or if a
<tt class="method">send()</tt> call can't immediately dispose of the data, a
<tt class="exception">error</tt> exception is raised; in blocking mode, the calls
block until they can proceed.
<code>s.setblocking(0)</code> is equivalent to <code>s.settimeout(0)</code>;
<code>s.setblocking(1)</code> is equivalent to <code>s.settimeout(None)</code>.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2667' xml:id='l2h-2667' class="method">settimeout</tt></b>(</nobr></td>
  <td><var>value</var>)</td></tr></table></dt>
<dd>
Set a timeout on blocking socket operations.  The <var>value</var> argument
can be a nonnegative float expressing seconds, or <code>None</code>.
If a float is
given, subsequent socket operations will raise an <tt class="exception">timeout</tt>
exception if the timeout period <var>value</var> has elapsed before the
operation has completed.  Setting a timeout of <code>None</code> disables
timeouts on socket operations.
<code>s.settimeout(0.0)</code> is equivalent to <code>s.setblocking(0)</code>;
<code>s.settimeout(None)</code> is equivalent to <code>s.setblocking(1)</code>.

<span class="versionnote">New in version 2.3.</span>

</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2668' xml:id='l2h-2668' class="method">gettimeout</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Returns the timeout in floating seconds associated with socket
operations, or <code>None</code> if no timeout is set.  This reflects
the last call to <tt class="method">setblocking()</tt> or <tt class="method">settimeout()</tt>.

<span class="versionnote">New in version 2.3.</span>

</dl>

<P>
Some notes on socket blocking and timeouts: A socket object can be in
one of three modes: blocking, non-blocking, or timeout.  Sockets are
always created in blocking mode.  In blocking mode, operations block
until complete.  In non-blocking mode, operations fail (with an error
that is unfortunately system-dependent) if they cannot be completed
immediately.  In timeout mode, operations fail if they cannot be
completed within the timeout specified for the socket.  The
<tt class="method">setblocking()</tt> method is simply a shorthand for certain
<tt class="method">settimeout()</tt> calls.

<P>
Timeout mode internally sets the socket in non-blocking mode.  The
blocking and timeout modes are shared between file descriptors and
socket objects that refer to the same network endpoint.  A consequence
of this is that file objects returned by the <tt class="method">makefile()</tt>
method should only be used when the socket is in blocking mode; in
timeout or non-blocking mode file operations that cannot be completed
immediately will fail.

<P>
Note that the <tt class="method">connect()</tt> operation is subject to the timeout
setting, and in general it is recommended to call
<tt class="method">settimeout()</tt> before calling <tt class="method">connect()</tt>.

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2669' xml:id='l2h-2669' class="method">setsockopt</tt></b>(</nobr></td>
  <td><var>level, optname, value</var>)</td></tr></table></dt>
<dd>
Set the value of the given socket option (see the <span class="Unix">Unix</span> manual page
<span class="manpage"><i>setsockopt</i>(2)</span>).  The needed symbolic constants are defined in
the <tt class="module">socket</tt> module (<tt class="constant">SO_*</tt> etc.).  The value can be an
integer or a string representing a buffer.  In the latter case it is
up to the caller to ensure that the string contains the proper bits
(see the optional built-in module
<tt class="module"><a href="module-struct.html">struct</a></tt><a id='l2h-2672' xml:id='l2h-2672'></a> for a way to encode C
structures as strings). 
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2670' xml:id='l2h-2670' class="method">shutdown</tt></b>(</nobr></td>
  <td><var>how</var>)</td></tr></table></dt>
<dd>
Shut down one or both halves of the connection.  If <var>how</var> is
<tt class="constant">SHUT_RD</tt>, further receives are disallowed.  If <var>how</var> is <tt class="constant">SHUT_WR</tt>,
further sends are disallowed.  If <var>how</var> is <tt class="constant">SHUT_RDWR</tt>, further sends
and receives are disallowed.
</dl>

<P>
Note that there are no methods <tt class="method">read()</tt> or <tt class="method">write()</tt>;
use <tt class="method">recv()</tt> and <tt class="method">send()</tt> without <var>flags</var> argument
instead.

<P>

<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="7.2 socket  "
  href="module-socket.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="7.2 socket  "
  href="module-socket.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="7.2.2 SSL Objects"
  href="ssl-objects.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="module-socket.html">7.2 socket  </A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-socket.html">7.2 socket  </A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="ssl-objects.html">7.2.2 SSL Objects</A>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>