<!DOCTYPE html PUBLIC
"-//W3C//DTD HTML 4.0 Transitional//EN">
<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>
<div id='top-navigation-panel' xml:id='top-navigation-panel'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<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>
<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>
<!--End of Navigation Panel-->
<H1><A NAME=
"SECTION009200000000000000000">
7.2 <tt class=
"module">socket
</tt> --
Low-level networking interface
</A>
<A NAME=
"module-socket"></A>
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.
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"
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)
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
>Basic Socket Interface Extensions for IPv6
</em>.
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
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.
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>'
<broadcast
>'
</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
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
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>.
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>.
The module
<tt class=
"module">socket
</tt> exports the following constants and functions:
<dl><dt><b><span class=
"typelabel">exception
</span> <tt id='l2h-
2598' xml:id='l2h-
2598'
class=
"exception">error
</tt></b></dt>
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.
<dl><dt><b><span class=
"typelabel">exception
</span> <tt id='l2h-
2599' xml:id='l2h-
2599'
class=
"exception">herror
</tt></b></dt>
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>.
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.
<dl><dt><b><span class=
"typelabel">exception
</span> <tt id='l2h-
2600' xml:id='l2h-
2600'
class=
"exception">gaierror
</tt></b></dt>
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
<dl><dt><b><span class=
"typelabel">exception
</span> <tt id='l2h-
2601' xml:id='l2h-
2601'
class=
"exception">timeout
</tt></b></dt>
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
<span class=
"versionnote">New in version
2.3.
</span>
<dl><dt><b><tt id='l2h-
2602' xml:id='l2h-
2602'
>AF_UNIX
</tt></b></dt>
<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
<dl><dt><b><tt id='l2h-
2603' xml:id='l2h-
2603'
>SOCK_STREAM
</tt></b></dt>
<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.)
<dl><dt><b><tt id='l2h-
2604' xml:id='l2h-
2604'
>SO_*
</tt></b></dt>
<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.
<dl><dt><b><tt id='l2h-
2605' xml:id='l2h-
2605'
>has_ipv6
</tt></b></dt>
This constant contains a boolean value which indicates if IPv6 is
supported on this platform.
<span class=
"versionnote">New in version
2.3.
</span>
<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>
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>.
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
<code>(
<var>family
</var>,
<var>socktype
</var>,
<var>proto
</var>,
<var>canonname
</var>,
<var>sockaddr
</var>)
</code>
<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><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>
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><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>
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><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>
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><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>
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>
<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>
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><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>
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
<span class=
"versionnote">New in version
2.2.
</span>
<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>
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
<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>
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><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>
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><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>
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><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>
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.
<span class=
"warning"><b class=
"label">Warning:
</b>
This does not do any certificate verification!
</span>
<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>
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><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>
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><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>
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><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>
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><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>
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><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>
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><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>
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.
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>.
<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
<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>
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.
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
<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>
Convert an IP address from its family-specific string format to a packed,
<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>.
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>.
Availability:
<span class=
"Unix">Unix
</span> (maybe not all platforms).
<span class=
"versionnote">New in version
2.3.
</span>
<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>
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>.
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>.
Availability:
<span class=
"Unix">Unix
</span> (maybe not all platforms).
<span class=
"versionnote">New in version
2.3.
</span>
<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>
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><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>
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><dt><b><tt id='l2h-
2630' xml:id='l2h-
2630'
>SocketType
</tt></b></dt>
This is a Python type object that represents the socket object type.
It is the same as
<code>type(socket(...))
</code>.
<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.
<p><br /></p><hr class='online-navigation'
/>
<div class='online-navigation'
>
<!--Table of Child-Links-->
<A NAME=
"CHILD_LINKS"><STRONG>Subsections
</STRONG></a>
<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>
<!--End of Table of Child-Links-->
<div class='online-navigation'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<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>
<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>
<span class=
"release-info">Release
2.4.2, documentation updated on
28 September
2005.
</span>
<!--End of Navigation Panel-->
See
<i><a href=
"about.html">About this document...
</a></i> for information on suggesting changes.