[OpenSPARC-T2-SAM] / sam-t2 / devtools / amd64 / html / python / lib / module-socket.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="module-select.html" />
<link rel="prev" href="module-signal.html" />
<link rel="parent" href="someos.html" />
<link rel="next" href="socket-objects.html" />
<meta name='aesop' content='information' />
<title>7.2 socket -- Low-level networking interface</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.1.1 Example"
  href="node373.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. Optional Operating System"
  href="someos.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.1 Socket Objects"
  href="socket-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="node373.html">7.1.1 Example</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="someos.html">7. Optional Operating System</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="socket-objects.html">7.2.1 Socket Objects</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H1><A NAME="SECTION009200000000000000000">
7.2 <tt class="module">socket</tt> --
         Low-level networking interface</A>
</H1>

<P>
<A NAME="module-socket"></A>

<P>
This module provides access to the BSD <em>socket</em> interface.
It is available on all modern <span class="Unix">Unix</span> systems, Windows, MacOS, BeOS,
OS/2, and probably additional platforms.

<P>
For an introduction to socket programming (in C), see the following
papers: <em class="citetitle"
 >An Introductory 4.3BSD Interprocess Communication
Tutorial</em>, by Stuart Sechrest and <em class="citetitle"
 >An Advanced 4.3BSD
Interprocess Communication Tutorial</em>, by Samuel J.  Leffler et al,
both in the <em class="citetitle"
 ><span class="Unix">Unix</span> Programmer's Manual, Supplementary Documents 1</em>
(sections PS1:7 and PS1:8).  The platform-specific reference material
for the various socket-related system calls are also a valuable source
of information on the details of socket semantics.  For <span class="Unix">Unix</span>, refer
to the manual pages; for Windows, see the WinSock (or Winsock 2)
specification.
For IPv6-ready APIs, readers may want to refer to <a class="rfc" id='rfcref-89145' xml:id='rfcref-89145'
href="http://www.faqs.org/rfcs/rfc2553.html">RFC 2553</a> titled
<em class="citetitle"
 >Basic Socket Interface Extensions for IPv6</em>.

<P>
The Python interface is a straightforward transliteration of the
<span class="Unix">Unix</span> system call and library interface for sockets to Python's
object-oriented style: the <tt class="function">socket()</tt> function returns a
<i class="dfn">socket object</i><a id='l2h-2597' xml:id='l2h-2597'></a> whose methods implement the
various socket system calls.  Parameter types are somewhat
higher-level than in the C interface: as with <tt class="method">read()</tt> and
<tt class="method">write()</tt> operations on Python files, buffer allocation on
receive operations is automatic, and buffer length is implicit on send
operations.

<P>
Socket addresses are represented as follows:
A single string is used for the <tt class="constant">AF_UNIX</tt> address family.
A pair <code>(<var>host</var>, <var>port</var>)</code> is used for the
<tt class="constant">AF_INET</tt> address family, where <var>host</var> is a string
representing either a hostname in Internet domain notation like
<code>'daring.cwi.nl'</code> or an IPv4 address like <code>'100.50.200.5'</code>,
and <var>port</var> is an integral port number.
For <tt class="constant">AF_INET6</tt> address family, a four-tuple
<code>(<var>host</var>, <var>port</var>, <var>flowinfo</var>, <var>scopeid</var>)</code> is
used, where <var>flowinfo</var> and <var>scopeid</var> represents
<code>sin6_flowinfo</code> and <code>sin6_scope_id</code> member in
<tt class="constant">struct sockaddr_in6</tt> in C.
For <tt class="module">socket</tt> module methods, <var>flowinfo</var> and <var>scopeid</var>
can be omitted just for backward compatibility. Note, however,
omission of <var>scopeid</var> can cause problems in manipulating scoped
IPv6 addresses. Other address families are currently not supported.
The address format required by a particular socket object is
automatically selected based on the address family specified when the
socket object was created.

<P>
For IPv4 addresses, two special forms are accepted instead of a host
address: the empty string represents <tt class="constant">INADDR_ANY</tt>, and the string
<code>'&lt;broadcast&gt;'</code> represents <tt class="constant">INADDR_BROADCAST</tt>.
The behavior is not available for IPv6 for backward compatibility,
therefore, you may want to avoid these if you intend to support IPv6 with
your Python programs.

<P>
If you use a hostname in the <var>host</var> portion of IPv4/v6 socket
address, the program may show a nondeterministic behavior, as Python
uses the first address returned from the DNS resolution.  The socket
address will be resolved differently into an actual IPv4/v6 address,
depending on the results from DNS resolution and/or the host
configuration.  For deterministic behavior use a numeric address in
<var>host</var> portion.

<P>
All errors raise exceptions.  The normal exceptions for invalid
argument types and out-of-memory conditions can be raised; errors
related to socket or address semantics raise the error
<tt class="exception">socket.error</tt>.

<P>
Non-blocking mode is supported through
<tt class="method">setblocking()</tt>.  A generalization of this based on timeouts
is supported through <tt class="method">settimeout()</tt>.

<P>
The module <tt class="module">socket</tt> exports the following constants and functions:

<P>
<dl><dt><b><span class="typelabel">exception</span>&nbsp;<tt id='l2h-2598' xml:id='l2h-2598' class="exception">error</tt></b></dt>
<dd>
This exception is raised for socket-related errors.
The accompanying value is either a string telling what went wrong or a
pair <code>(<var>errno</var>, <var>string</var>)</code>
representing an error returned by a system
call, similar to the value accompanying <tt class="exception">os.error</tt>.
See the module <tt class="module"><a href="module-errno.html">errno</a></tt><a id='l2h-2631' xml:id='l2h-2631'></a>, which contains
names for the error codes defined by the underlying operating system.
</dd></dl>

<P>
<dl><dt><b><span class="typelabel">exception</span>&nbsp;<tt id='l2h-2599' xml:id='l2h-2599' class="exception">herror</tt></b></dt>
<dd>
This exception is raised for address-related errors, i.e. for
functions that use <var>h_errno</var> in the C API, including
<tt class="function">gethostbyname_ex()</tt> and <tt class="function">gethostbyaddr()</tt>.

<P>
The accompanying value is a pair <code>(<var>h_errno</var>, <var>string</var>)</code>
representing an error returned by a library call. <var>string</var>
represents the description of <var>h_errno</var>, as returned by
the <tt class="cfunction">hstrerror()</tt> C function.
</dd></dl>

<P>
<dl><dt><b><span class="typelabel">exception</span>&nbsp;<tt id='l2h-2600' xml:id='l2h-2600' class="exception">gaierror</tt></b></dt>
<dd>
This exception is raised for address-related errors, for
<tt class="function">getaddrinfo()</tt> and <tt class="function">getnameinfo()</tt>.
The accompanying value is a pair <code>(<var>error</var>, <var>string</var>)</code>
representing an error returned by a library call.
<var>string</var> represents the description of <var>error</var>, as returned
by the <tt class="cfunction">gai_strerror()</tt> C function.
The <var>error</var> value will match one of the <tt class="constant">EAI_*</tt> constants
defined in this module.
</dd></dl>

<P>
<dl><dt><b><span class="typelabel">exception</span>&nbsp;<tt id='l2h-2601' xml:id='l2h-2601' class="exception">timeout</tt></b></dt>
<dd>
This exception is raised when a timeout occurs on a socket which has
had timeouts enabled via a prior call to <tt class="method">settimeout()</tt>.  The
accompanying value is a string whose value is currently always ``timed
out''.

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

</dd></dl>

<P>
<dl><dt><b><tt id='l2h-2602' xml:id='l2h-2602'>AF_UNIX</tt></b></dt>
<dd>
<dt><b><tt id='l2h-2632' xml:id='l2h-2632'>AF_INET</tt></b></dt><dd>
<dt><b><tt id='l2h-2633' xml:id='l2h-2633'>AF_INET6</tt></b></dt><dd>
These constants represent the address (and protocol) families,
used for the first argument to <tt class="function">socket()</tt>.  If the
<tt class="constant">AF_UNIX</tt> constant is not defined then this protocol is
unsupported.
</dd></dl>

<P>
<dl><dt><b><tt id='l2h-2603' xml:id='l2h-2603'>SOCK_STREAM</tt></b></dt>
<dd>
<dt><b><tt id='l2h-2634' xml:id='l2h-2634'>SOCK_DGRAM</tt></b></dt><dd>
<dt><b><tt id='l2h-2635' xml:id='l2h-2635'>SOCK_RAW</tt></b></dt><dd>
<dt><b><tt id='l2h-2636' xml:id='l2h-2636'>SOCK_RDM</tt></b></dt><dd>
<dt><b><tt id='l2h-2637' xml:id='l2h-2637'>SOCK_SEQPACKET</tt></b></dt><dd>
These constants represent the socket types,
used for the second argument to <tt class="function">socket()</tt>.
(Only <tt class="constant">SOCK_STREAM</tt> and
<tt class="constant">SOCK_DGRAM</tt> appear to be generally useful.)
</dd></dl>

<P>
<dl><dt><b><tt id='l2h-2604' xml:id='l2h-2604'>SO_*</tt></b></dt>
<dd>
<dt><b><tt id='l2h-2638' xml:id='l2h-2638'>SOMAXCONN</tt></b></dt><dd>
<dt><b><tt id='l2h-2639' xml:id='l2h-2639'>MSG_*</tt></b></dt><dd>
<dt><b><tt id='l2h-2640' xml:id='l2h-2640'>SOL_*</tt></b></dt><dd>
<dt><b><tt id='l2h-2641' xml:id='l2h-2641'>IPPROTO_*</tt></b></dt><dd>
<dt><b><tt id='l2h-2642' xml:id='l2h-2642'>IPPORT_*</tt></b></dt><dd>
<dt><b><tt id='l2h-2643' xml:id='l2h-2643'>INADDR_*</tt></b></dt><dd>
<dt><b><tt id='l2h-2644' xml:id='l2h-2644'>IP_*</tt></b></dt><dd>
<dt><b><tt id='l2h-2645' xml:id='l2h-2645'>IPV6_*</tt></b></dt><dd>
<dt><b><tt id='l2h-2646' xml:id='l2h-2646'>EAI_*</tt></b></dt><dd>
<dt><b><tt id='l2h-2647' xml:id='l2h-2647'>AI_*</tt></b></dt><dd>
<dt><b><tt id='l2h-2648' xml:id='l2h-2648'>NI_*</tt></b></dt><dd>
<dt><b><tt id='l2h-2649' xml:id='l2h-2649'>TCP_*</tt></b></dt><dd>
Many constants of these forms, documented in the <span class="Unix">Unix</span> documentation on
sockets and/or the IP protocol, are also defined in the socket module.
They are generally used in arguments to the <tt class="method">setsockopt()</tt> and
<tt class="method">getsockopt()</tt> methods of socket objects.  In most cases, only
those symbols that are defined in the <span class="Unix">Unix</span> header files are defined;
for a few symbols, default values are provided.
</dd></dl>

<P>
<dl><dt><b><tt id='l2h-2605' xml:id='l2h-2605'>has_ipv6</tt></b></dt>
<dd>
This constant contains a boolean value which indicates if IPv6 is
supported on this platform.

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

</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2606' xml:id='l2h-2606' class="function">getaddrinfo</tt></b>(</nobr></td>
  <td><var>host, port</var><big>[</big><var>, family</var><big>[</big><var>,
                              socktype</var><big>[</big><var>, proto</var><big>[</big><var>,
                              flags</var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Resolves the <var>host</var>/<var>port</var> argument, into a sequence of
5-tuples that contain all the necessary argument for the sockets
manipulation. <var>host</var> is a domain name, a string representation of
IPv4/v6 address or <code>None</code>.
<var>port</var> is a string service name (like <code>'http'</code>), a numeric
port number or <code>None</code>.

<P>
The rest of the arguments are optional and must be numeric if
specified.  For <var>host</var> and <var>port</var>, by passing either an empty
string or <code>None</code>, you can pass <code>NULL</code> to the C API.  The
<tt class="function">getaddrinfo()</tt> function returns a list of 5-tuples with
the following structure:

<P>
<code>(<var>family</var>, <var>socktype</var>, <var>proto</var>, <var>canonname</var>,
      <var>sockaddr</var>)</code>

<P>
<var>family</var>, <var>socktype</var>, <var>proto</var> are all integer and are meant to
be passed to the <tt class="function">socket()</tt> function.
<var>canonname</var> is a string representing the canonical name of the <var>host</var>.
It can be a numeric IPv4/v6 address when <tt class="constant">AI_CANONNAME</tt> is specified
for a numeric <var>host</var>.
<var>sockaddr</var> is a tuple describing a socket address, as described above.
See the source for the <tt class="module"><a href="module-httplib.html">httplib</a></tt> and other library modules
for a typical usage of the function.

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

</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2607' xml:id='l2h-2607' class="function">getfqdn</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>name</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Return a fully qualified domain name for <var>name</var>.
If <var>name</var> is omitted or empty, it is interpreted as the local
host.  To find the fully qualified name, the hostname returned by
<tt class="function">gethostbyaddr()</tt> is checked, then aliases for the host, if
available.  The first name which includes a period is selected.  In
case no fully qualified domain name is available, the hostname as
returned by <tt class="function">gethostname()</tt> is returned.

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

</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2608' xml:id='l2h-2608' class="function">gethostbyname</tt></b>(</nobr></td>
  <td><var>hostname</var>)</td></tr></table></dt>
<dd>
Translate a host name to IPv4 address format.  The IPv4 address is
returned as a string, such as  <code>'100.50.200.5'</code>.  If the host name
is an IPv4 address itself it is returned unchanged.  See
<tt class="function">gethostbyname_ex()</tt> for a more complete interface.
<tt class="function">gethostbyname()</tt> does not support IPv6 name resolution, and
<tt class="function">getaddrinfo()</tt> should be used instead for IPv4/v6 dual stack support.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2609' xml:id='l2h-2609' class="function">gethostbyname_ex</tt></b>(</nobr></td>
  <td><var>hostname</var>)</td></tr></table></dt>
<dd>
Translate a host name to IPv4 address format, extended interface.
Return a triple <code>(<var>hostname</var>, <var>aliaslist</var>,
<var>ipaddrlist</var>)</code> where
<var>hostname</var> is the primary host name responding to the given
<var>ip_address</var>, <var>aliaslist</var> is a (possibly empty) list of
alternative host names for the same address, and <var>ipaddrlist</var> is
a list of IPv4 addresses for the same interface on the same
host (often but not always a single address).
<tt class="function">gethostbyname_ex()</tt> does not support IPv6 name resolution, and
<tt class="function">getaddrinfo()</tt> should be used instead for IPv4/v6 dual stack support.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2610' xml:id='l2h-2610' class="function">gethostname</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Return a string containing the hostname of the machine where 
the Python interpreter is currently executing.
If you want to know the current machine's IP address, you may want to use
<code>gethostbyname(gethostname())</code>.
This operation assumes that there is a valid address-to-host mapping for
the host, and the assumption does not always hold.
Note: <tt class="function">gethostname()</tt> doesn't always return the fully qualified
domain name; use <code>gethostbyaddr(gethostname())</code>
(see below).
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2611' xml:id='l2h-2611' class="function">gethostbyaddr</tt></b>(</nobr></td>
  <td><var>ip_address</var>)</td></tr></table></dt>
<dd>
Return a triple <code>(<var>hostname</var>, <var>aliaslist</var>,
<var>ipaddrlist</var>)</code> where <var>hostname</var> is the primary host name
responding to the given <var>ip_address</var>, <var>aliaslist</var> is a
(possibly empty) list of alternative host names for the same address,
and <var>ipaddrlist</var> is a list of IPv4/v6 addresses for the same interface
on the same host (most likely containing only a single address).
To find the fully qualified domain name, use the function
<tt class="function">getfqdn()</tt>.
<tt class="function">gethostbyaddr</tt> supports both IPv4 and IPv6.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2612' xml:id='l2h-2612' class="function">getnameinfo</tt></b>(</nobr></td>
  <td><var>sockaddr, flags</var>)</td></tr></table></dt>
<dd>
Translate a socket address <var>sockaddr</var> into a 2-tuple
<code>(<var>host</var>, <var>port</var>)</code>.
Depending on the settings of <var>flags</var>, the result can contain a
fully-qualified domain name or numeric address representation in
<var>host</var>.  Similarly, <var>port</var> can contain a string port name or a
numeric port number.

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

</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2613' xml:id='l2h-2613' class="function">getprotobyname</tt></b>(</nobr></td>
  <td><var>protocolname</var>)</td></tr></table></dt>
<dd>
Translate an Internet protocol name (for example, <code>'icmp'</code>) to a constant
suitable for passing as the (optional) third argument to the
<tt class="function">socket()</tt> function.  This is usually only needed for sockets
opened in ``raw'' mode (<tt class="constant">SOCK_RAW</tt>); for the normal socket
modes, the correct protocol is chosen automatically if the protocol is
omitted or zero.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2614' xml:id='l2h-2614' class="function">getservbyname</tt></b>(</nobr></td>
  <td><var>servicename</var><big>[</big><var>, protocolname</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Translate an Internet service name and protocol name to a port number
for that service.  The optional protocol name, if given, should be
<code>'tcp'</code> or <code>'udp'</code>, otherwise any protocol will match.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2615' xml:id='l2h-2615' class="function">getservbyport</tt></b>(</nobr></td>
  <td><var>port</var><big>[</big><var>, protocolname</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Translate an Internet port number and protocol name to a service name
for that service.  The optional protocol name, if given, should be
<code>'tcp'</code> or <code>'udp'</code>, otherwise any protocol will match.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2616' xml:id='l2h-2616' class="function">socket</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>family</var><big>[</big><var>,
                         type</var><big>[</big><var>, proto</var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Create a new socket using the given address family, socket type and
protocol number.  The address family should be <tt class="constant">AF_INET</tt> (the
default), <tt class="constant">AF_INET6</tt> or <tt class="constant">AF_UNIX</tt>.  The socket type
should be <tt class="constant">SOCK_STREAM</tt> (the default), <tt class="constant">SOCK_DGRAM</tt>
or perhaps one of the other "<tt class="samp">SOCK_</tt>" constants.  The protocol
number is usually zero and may be omitted in that case.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2617' xml:id='l2h-2617' class="function">ssl</tt></b>(</nobr></td>
  <td><var>sock</var><big>[</big><var>, keyfile, certfile</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Initiate a SSL connection over the socket <var>sock</var>. <var>keyfile</var> is
the name of a PEM formatted file that contains your private
key. <var>certfile</var> is a PEM formatted certificate chain file. On
success, a new <tt class="class">SSLObject</tt> is returned.

<P>
<span class="warning"><b class="label">Warning:</b>
This does not do any certificate verification!</span>
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2618' xml:id='l2h-2618' class="function">socketpair</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>family</var><big>[</big><var>, type</var><big>[</big><var>, proto</var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Build a pair of connected socket objects using the given address
family, socket type, and protocol number.  Address family, socket type,
and protocol number are as for the <tt class="function">socket()</tt> function above.
The default family is <tt class="constant">AF_UNIX</tt> if defined on the platform;
otherwise, the default is <tt class="constant">AF_INET</tt>.
Availability: <span class="Unix">Unix</span>.  
<span class="versionnote">New in version 2.4.</span>

</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2619' xml:id='l2h-2619' class="function">fromfd</tt></b>(</nobr></td>
  <td><var>fd, family, type</var><big>[</big><var>, proto</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Build a socket object from an existing file descriptor (an integer as
returned by a file object's <tt class="method">fileno()</tt> method).  Address family,
socket type and protocol number are as for the <tt class="function">socket()</tt> function
above.  The file descriptor should refer to a socket, but this is not
checked -- subsequent operations on the object may fail if the file
descriptor is invalid.  This function is rarely needed, but can be
used to get or set socket options on a socket passed to a program as
standard input or output (such as a server started by the <span class="Unix">Unix</span> inet
daemon).  The socket is assumed to be in blocking mode.
Availability: <span class="Unix">Unix</span>.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2620' xml:id='l2h-2620' class="function">ntohl</tt></b>(</nobr></td>
  <td><var>x</var>)</td></tr></table></dt>
<dd>
Convert 32-bit integers from network to host byte order.  On machines
where the host byte order is the same as network byte order, this is a
no-op; otherwise, it performs a 4-byte swap operation.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2621' xml:id='l2h-2621' class="function">ntohs</tt></b>(</nobr></td>
  <td><var>x</var>)</td></tr></table></dt>
<dd>
Convert 16-bit integers from network to host byte order.  On machines
where the host byte order is the same as network byte order, this is a
no-op; otherwise, it performs a 2-byte swap operation.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2622' xml:id='l2h-2622' class="function">htonl</tt></b>(</nobr></td>
  <td><var>x</var>)</td></tr></table></dt>
<dd>
Convert 32-bit integers from host to network byte order.  On machines
where the host byte order is the same as network byte order, this is a
no-op; otherwise, it performs a 4-byte swap operation.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2623' xml:id='l2h-2623' class="function">htons</tt></b>(</nobr></td>
  <td><var>x</var>)</td></tr></table></dt>
<dd>
Convert 16-bit integers from host to network byte order.  On machines
where the host byte order is the same as network byte order, this is a
no-op; otherwise, it performs a 2-byte swap operation.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2624' xml:id='l2h-2624' class="function">inet_aton</tt></b>(</nobr></td>
  <td><var>ip_string</var>)</td></tr></table></dt>
<dd>
Convert an IPv4 address from dotted-quad string format (for example,
'123.45.67.89') to 32-bit packed binary format, as a string four
characters in length.  This is useful when conversing with a program
that uses the standard C library and needs objects of type
<tt class="ctype">struct in_addr</tt>, which is the C type for the 32-bit packed
binary this function returns.

<P>
If the IPv4 address string passed to this function is invalid,
<tt class="exception">socket.error</tt> will be raised. Note that exactly what is
valid depends on the underlying C implementation of
<tt class="cfunction">inet_aton()</tt>.

<P>
<tt class="function">inet_aton()</tt> does not support IPv6, and
<tt class="function">getnameinfo()</tt> should be used instead for IPv4/v6 dual stack
support.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2625' xml:id='l2h-2625' class="function">inet_ntoa</tt></b>(</nobr></td>
  <td><var>packed_ip</var>)</td></tr></table></dt>
<dd>
Convert a 32-bit packed IPv4 address (a string four characters in
length) to its standard dotted-quad string representation (for
example, '123.45.67.89').  This is useful when conversing with a
program that uses the standard C library and needs objects of type
<tt class="ctype">struct in_addr</tt>, which is the C type for the 32-bit packed
binary data this function takes as an argument.

<P>
If the string passed to this function is not exactly 4 bytes in
length, <tt class="exception">socket.error</tt> will be raised.
<tt class="function">inet_ntoa()</tt> does not support IPv6, and
<tt class="function">getnameinfo()</tt> should be used instead for IPv4/v6 dual stack
support.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2626' xml:id='l2h-2626' class="function">inet_pton</tt></b>(</nobr></td>
  <td><var>address_family, ip_string</var>)</td></tr></table></dt>
<dd>
Convert an IP address from its family-specific string format to a packed,
binary format.
<tt class="function">inet_pton()</tt> is useful when a library or network protocol calls for
an object of type <tt class="ctype">struct in_addr</tt> (similar to <tt class="function">inet_aton()</tt>)
or <tt class="ctype">struct in6_addr</tt>.

<P>
Supported values for <var>address_family</var> are currently
<tt class="constant">AF_INET</tt> and <tt class="constant">AF_INET6</tt>.
If the IP address string <var>ip_string</var> is invalid,
<tt class="exception">socket.error</tt> will be raised. Note that exactly what is valid
depends on both the value of <var>address_family</var> and the underlying
implementation of <tt class="cfunction">inet_pton()</tt>.

<P>
Availability: <span class="Unix">Unix</span> (maybe not all platforms).

<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-2627' xml:id='l2h-2627' class="function">inet_ntop</tt></b>(</nobr></td>
  <td><var>address_family, packed_ip</var>)</td></tr></table></dt>
<dd>
Convert a packed IP address (a string of some number of characters) to
its standard, family-specific string representation (for example,
<code>'7.10.0.5'</code> or <code>'5aef:2b::8'</code>)
<tt class="function">inet_ntop()</tt> is useful when a library or network protocol returns
an object of type <tt class="ctype">struct in_addr</tt> (similar to <tt class="function">inet_ntoa()</tt>)
or <tt class="ctype">struct in6_addr</tt>.

<P>
Supported values for <var>address_family</var> are currently
<tt class="constant">AF_INET</tt> and <tt class="constant">AF_INET6</tt>.
If the string <var>packed_ip</var> is not the correct length for the
specified address family, <tt class="exception">ValueError</tt> will be raised.  A
<tt class="exception">socket.error</tt> is raised for errors from the call to
<tt class="function">inet_ntop()</tt>.

<P>
Availability: <span class="Unix">Unix</span> (maybe not all platforms).

<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-2628' xml:id='l2h-2628' class="function">getdefaulttimeout</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Return the default timeout in floating seconds for new socket objects.
A value of <code>None</code> indicates that new socket objects have no timeout.
When the socket module is first imported, the default is <code>None</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-2629' xml:id='l2h-2629' class="function">setdefaulttimeout</tt></b>(</nobr></td>
  <td><var>timeout</var>)</td></tr></table></dt>
<dd>
Set the default timeout in floating seconds for new socket objects.
A value of <code>None</code> indicates that new socket objects have no timeout.
When the socket module is first imported, the default is <code>None</code>.

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

</dl>

<P>
<dl><dt><b><tt id='l2h-2630' xml:id='l2h-2630'>SocketType</tt></b></dt>
<dd>
This is a Python type object that represents the socket object type.
It is the same as <code>type(socket(...))</code>.
</dd></dl>

<P>
<div class="seealso">
  <p class="heading">See Also:</p>

  <dl compact="compact" class="seemodule">
    <dt>Module <b><tt class="module"><a href="module-SocketServer.html">SocketServer</a></tt>:</b>
    <dd>Classes that simplify writing network servers.
  </dl>
</div>

<P>

<p><br /></p><hr class='online-navigation' />
<div class='online-navigation'>
<!--Table of Child-Links-->
<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a>

<UL CLASS="ChildLinks">
<LI><A href="socket-objects.html">7.2.1 Socket Objects</a>
<LI><A href="ssl-objects.html">7.2.2 SSL Objects</a>
<LI><A href="socket-example.html">7.2.3 Example</a>
</ul>
<!--End of Table of Child-Links-->
</div>

<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.1.1 Example"
  href="node373.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. Optional Operating System"
  href="someos.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.1 Socket Objects"
  href="socket-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="node373.html">7.1.1 Example</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="someos.html">7. Optional Operating System</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="socket-objects.html">7.2.1 Socket 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>