| 1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| 2 | <html> |
| 3 | <head> |
| 4 | <link rel="STYLESHEET" href="lib.css" type='text/css' /> |
| 5 | <link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" /> |
| 6 | <link rel='start' href='../index.html' title='Python Documentation Index' /> |
| 7 | <link rel="first" href="lib.html" title='Python Library Reference' /> |
| 8 | <link rel='contents' href='contents.html' title="Contents" /> |
| 9 | <link rel='index' href='genindex.html' title='Index' /> |
| 10 | <link rel='last' href='about.html' title='About this document...' /> |
| 11 | <link rel='help' href='about.html' title='About this document...' /> |
| 12 | <link rel="next" href="module-select.html" /> |
| 13 | <link rel="prev" href="module-signal.html" /> |
| 14 | <link rel="parent" href="someos.html" /> |
| 15 | <link rel="next" href="socket-objects.html" /> |
| 16 | <meta name='aesop' content='information' /> |
| 17 | <title>7.2 socket -- Low-level networking interface</title> |
| 18 | </head> |
| 19 | <body> |
| 20 | <DIV CLASS="navigation"> |
| 21 | <div id='top-navigation-panel' xml:id='top-navigation-panel'> |
| 22 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> |
| 23 | <tr> |
| 24 | <td class='online-navigation'><a rel="prev" title="7.1.1 Example" |
| 25 | href="node373.html"><img src='../icons/previous.png' |
| 26 | border='0' height='32' alt='Previous Page' width='32' /></A></td> |
| 27 | <td class='online-navigation'><a rel="parent" title="7. Optional Operating System" |
| 28 | href="someos.html"><img src='../icons/up.png' |
| 29 | border='0' height='32' alt='Up One Level' width='32' /></A></td> |
| 30 | <td class='online-navigation'><a rel="next" title="7.2.1 Socket Objects" |
| 31 | href="socket-objects.html"><img src='../icons/next.png' |
| 32 | border='0' height='32' alt='Next Page' width='32' /></A></td> |
| 33 | <td align="center" width="100%">Python Library Reference</td> |
| 34 | <td class='online-navigation'><a rel="contents" title="Table of Contents" |
| 35 | href="contents.html"><img src='../icons/contents.png' |
| 36 | border='0' height='32' alt='Contents' width='32' /></A></td> |
| 37 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' |
| 38 | border='0' height='32' alt='Module Index' width='32' /></a></td> |
| 39 | <td class='online-navigation'><a rel="index" title="Index" |
| 40 | href="genindex.html"><img src='../icons/index.png' |
| 41 | border='0' height='32' alt='Index' width='32' /></A></td> |
| 42 | </tr></table> |
| 43 | <div class='online-navigation'> |
| 44 | <b class="navlabel">Previous:</b> |
| 45 | <a class="sectref" rel="prev" href="node373.html">7.1.1 Example</A> |
| 46 | <b class="navlabel">Up:</b> |
| 47 | <a class="sectref" rel="parent" href="someos.html">7. Optional Operating System</A> |
| 48 | <b class="navlabel">Next:</b> |
| 49 | <a class="sectref" rel="next" href="socket-objects.html">7.2.1 Socket Objects</A> |
| 50 | </div> |
| 51 | <hr /></div> |
| 52 | </DIV> |
| 53 | <!--End of Navigation Panel--> |
| 54 | |
| 55 | <H1><A NAME="SECTION009200000000000000000"> |
| 56 | 7.2 <tt class="module">socket</tt> -- |
| 57 | Low-level networking interface</A> |
| 58 | </H1> |
| 59 | |
| 60 | <P> |
| 61 | <A NAME="module-socket"></A> |
| 62 | |
| 63 | <P> |
| 64 | This module provides access to the BSD <em>socket</em> interface. |
| 65 | It is available on all modern <span class="Unix">Unix</span> systems, Windows, MacOS, BeOS, |
| 66 | OS/2, and probably additional platforms. |
| 67 | |
| 68 | <P> |
| 69 | For an introduction to socket programming (in C), see the following |
| 70 | papers: <em class="citetitle" |
| 71 | >An Introductory 4.3BSD Interprocess Communication |
| 72 | Tutorial</em>, by Stuart Sechrest and <em class="citetitle" |
| 73 | >An Advanced 4.3BSD |
| 74 | Interprocess Communication Tutorial</em>, by Samuel J. Leffler et al, |
| 75 | both in the <em class="citetitle" |
| 76 | ><span class="Unix">Unix</span> Programmer's Manual, Supplementary Documents 1</em> |
| 77 | (sections PS1:7 and PS1:8). The platform-specific reference material |
| 78 | for the various socket-related system calls are also a valuable source |
| 79 | of information on the details of socket semantics. For <span class="Unix">Unix</span>, refer |
| 80 | to the manual pages; for Windows, see the WinSock (or Winsock 2) |
| 81 | specification. |
| 82 | For IPv6-ready APIs, readers may want to refer to <a class="rfc" id='rfcref-89145' xml:id='rfcref-89145' |
| 83 | href="http://www.faqs.org/rfcs/rfc2553.html">RFC 2553</a> titled |
| 84 | <em class="citetitle" |
| 85 | >Basic Socket Interface Extensions for IPv6</em>. |
| 86 | |
| 87 | <P> |
| 88 | The Python interface is a straightforward transliteration of the |
| 89 | <span class="Unix">Unix</span> system call and library interface for sockets to Python's |
| 90 | object-oriented style: the <tt class="function">socket()</tt> function returns a |
| 91 | <i class="dfn">socket object</i><a id='l2h-2597' xml:id='l2h-2597'></a> whose methods implement the |
| 92 | various socket system calls. Parameter types are somewhat |
| 93 | higher-level than in the C interface: as with <tt class="method">read()</tt> and |
| 94 | <tt class="method">write()</tt> operations on Python files, buffer allocation on |
| 95 | receive operations is automatic, and buffer length is implicit on send |
| 96 | operations. |
| 97 | |
| 98 | <P> |
| 99 | Socket addresses are represented as follows: |
| 100 | A single string is used for the <tt class="constant">AF_UNIX</tt> address family. |
| 101 | A pair <code>(<var>host</var>, <var>port</var>)</code> is used for the |
| 102 | <tt class="constant">AF_INET</tt> address family, where <var>host</var> is a string |
| 103 | representing either a hostname in Internet domain notation like |
| 104 | <code>'daring.cwi.nl'</code> or an IPv4 address like <code>'100.50.200.5'</code>, |
| 105 | and <var>port</var> is an integral port number. |
| 106 | For <tt class="constant">AF_INET6</tt> address family, a four-tuple |
| 107 | <code>(<var>host</var>, <var>port</var>, <var>flowinfo</var>, <var>scopeid</var>)</code> is |
| 108 | used, where <var>flowinfo</var> and <var>scopeid</var> represents |
| 109 | <code>sin6_flowinfo</code> and <code>sin6_scope_id</code> member in |
| 110 | <tt class="constant">struct sockaddr_in6</tt> in C. |
| 111 | For <tt class="module">socket</tt> module methods, <var>flowinfo</var> and <var>scopeid</var> |
| 112 | can be omitted just for backward compatibility. Note, however, |
| 113 | omission of <var>scopeid</var> can cause problems in manipulating scoped |
| 114 | IPv6 addresses. Other address families are currently not supported. |
| 115 | The address format required by a particular socket object is |
| 116 | automatically selected based on the address family specified when the |
| 117 | socket object was created. |
| 118 | |
| 119 | <P> |
| 120 | For IPv4 addresses, two special forms are accepted instead of a host |
| 121 | address: the empty string represents <tt class="constant">INADDR_ANY</tt>, and the string |
| 122 | <code>'<broadcast>'</code> represents <tt class="constant">INADDR_BROADCAST</tt>. |
| 123 | The behavior is not available for IPv6 for backward compatibility, |
| 124 | therefore, you may want to avoid these if you intend to support IPv6 with |
| 125 | your Python programs. |
| 126 | |
| 127 | <P> |
| 128 | If you use a hostname in the <var>host</var> portion of IPv4/v6 socket |
| 129 | address, the program may show a nondeterministic behavior, as Python |
| 130 | uses the first address returned from the DNS resolution. The socket |
| 131 | address will be resolved differently into an actual IPv4/v6 address, |
| 132 | depending on the results from DNS resolution and/or the host |
| 133 | configuration. For deterministic behavior use a numeric address in |
| 134 | <var>host</var> portion. |
| 135 | |
| 136 | <P> |
| 137 | All errors raise exceptions. The normal exceptions for invalid |
| 138 | argument types and out-of-memory conditions can be raised; errors |
| 139 | related to socket or address semantics raise the error |
| 140 | <tt class="exception">socket.error</tt>. |
| 141 | |
| 142 | <P> |
| 143 | Non-blocking mode is supported through |
| 144 | <tt class="method">setblocking()</tt>. A generalization of this based on timeouts |
| 145 | is supported through <tt class="method">settimeout()</tt>. |
| 146 | |
| 147 | <P> |
| 148 | The module <tt class="module">socket</tt> exports the following constants and functions: |
| 149 | |
| 150 | <P> |
| 151 | <dl><dt><b><span class="typelabel">exception</span> <tt id='l2h-2598' xml:id='l2h-2598' class="exception">error</tt></b></dt> |
| 152 | <dd> |
| 153 | This exception is raised for socket-related errors. |
| 154 | The accompanying value is either a string telling what went wrong or a |
| 155 | pair <code>(<var>errno</var>, <var>string</var>)</code> |
| 156 | representing an error returned by a system |
| 157 | call, similar to the value accompanying <tt class="exception">os.error</tt>. |
| 158 | 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 |
| 159 | names for the error codes defined by the underlying operating system. |
| 160 | </dd></dl> |
| 161 | |
| 162 | <P> |
| 163 | <dl><dt><b><span class="typelabel">exception</span> <tt id='l2h-2599' xml:id='l2h-2599' class="exception">herror</tt></b></dt> |
| 164 | <dd> |
| 165 | This exception is raised for address-related errors, i.e. for |
| 166 | functions that use <var>h_errno</var> in the C API, including |
| 167 | <tt class="function">gethostbyname_ex()</tt> and <tt class="function">gethostbyaddr()</tt>. |
| 168 | |
| 169 | <P> |
| 170 | The accompanying value is a pair <code>(<var>h_errno</var>, <var>string</var>)</code> |
| 171 | representing an error returned by a library call. <var>string</var> |
| 172 | represents the description of <var>h_errno</var>, as returned by |
| 173 | the <tt class="cfunction">hstrerror()</tt> C function. |
| 174 | </dd></dl> |
| 175 | |
| 176 | <P> |
| 177 | <dl><dt><b><span class="typelabel">exception</span> <tt id='l2h-2600' xml:id='l2h-2600' class="exception">gaierror</tt></b></dt> |
| 178 | <dd> |
| 179 | This exception is raised for address-related errors, for |
| 180 | <tt class="function">getaddrinfo()</tt> and <tt class="function">getnameinfo()</tt>. |
| 181 | The accompanying value is a pair <code>(<var>error</var>, <var>string</var>)</code> |
| 182 | representing an error returned by a library call. |
| 183 | <var>string</var> represents the description of <var>error</var>, as returned |
| 184 | by the <tt class="cfunction">gai_strerror()</tt> C function. |
| 185 | The <var>error</var> value will match one of the <tt class="constant">EAI_*</tt> constants |
| 186 | defined in this module. |
| 187 | </dd></dl> |
| 188 | |
| 189 | <P> |
| 190 | <dl><dt><b><span class="typelabel">exception</span> <tt id='l2h-2601' xml:id='l2h-2601' class="exception">timeout</tt></b></dt> |
| 191 | <dd> |
| 192 | This exception is raised when a timeout occurs on a socket which has |
| 193 | had timeouts enabled via a prior call to <tt class="method">settimeout()</tt>. The |
| 194 | accompanying value is a string whose value is currently always ``timed |
| 195 | out''. |
| 196 | |
| 197 | <span class="versionnote">New in version 2.3.</span> |
| 198 | |
| 199 | </dd></dl> |
| 200 | |
| 201 | <P> |
| 202 | <dl><dt><b><tt id='l2h-2602' xml:id='l2h-2602'>AF_UNIX</tt></b></dt> |
| 203 | <dd> |
| 204 | <dt><b><tt id='l2h-2632' xml:id='l2h-2632'>AF_INET</tt></b></dt><dd> |
| 205 | <dt><b><tt id='l2h-2633' xml:id='l2h-2633'>AF_INET6</tt></b></dt><dd> |
| 206 | These constants represent the address (and protocol) families, |
| 207 | used for the first argument to <tt class="function">socket()</tt>. If the |
| 208 | <tt class="constant">AF_UNIX</tt> constant is not defined then this protocol is |
| 209 | unsupported. |
| 210 | </dd></dl> |
| 211 | |
| 212 | <P> |
| 213 | <dl><dt><b><tt id='l2h-2603' xml:id='l2h-2603'>SOCK_STREAM</tt></b></dt> |
| 214 | <dd> |
| 215 | <dt><b><tt id='l2h-2634' xml:id='l2h-2634'>SOCK_DGRAM</tt></b></dt><dd> |
| 216 | <dt><b><tt id='l2h-2635' xml:id='l2h-2635'>SOCK_RAW</tt></b></dt><dd> |
| 217 | <dt><b><tt id='l2h-2636' xml:id='l2h-2636'>SOCK_RDM</tt></b></dt><dd> |
| 218 | <dt><b><tt id='l2h-2637' xml:id='l2h-2637'>SOCK_SEQPACKET</tt></b></dt><dd> |
| 219 | These constants represent the socket types, |
| 220 | used for the second argument to <tt class="function">socket()</tt>. |
| 221 | (Only <tt class="constant">SOCK_STREAM</tt> and |
| 222 | <tt class="constant">SOCK_DGRAM</tt> appear to be generally useful.) |
| 223 | </dd></dl> |
| 224 | |
| 225 | <P> |
| 226 | <dl><dt><b><tt id='l2h-2604' xml:id='l2h-2604'>SO_*</tt></b></dt> |
| 227 | <dd> |
| 228 | <dt><b><tt id='l2h-2638' xml:id='l2h-2638'>SOMAXCONN</tt></b></dt><dd> |
| 229 | <dt><b><tt id='l2h-2639' xml:id='l2h-2639'>MSG_*</tt></b></dt><dd> |
| 230 | <dt><b><tt id='l2h-2640' xml:id='l2h-2640'>SOL_*</tt></b></dt><dd> |
| 231 | <dt><b><tt id='l2h-2641' xml:id='l2h-2641'>IPPROTO_*</tt></b></dt><dd> |
| 232 | <dt><b><tt id='l2h-2642' xml:id='l2h-2642'>IPPORT_*</tt></b></dt><dd> |
| 233 | <dt><b><tt id='l2h-2643' xml:id='l2h-2643'>INADDR_*</tt></b></dt><dd> |
| 234 | <dt><b><tt id='l2h-2644' xml:id='l2h-2644'>IP_*</tt></b></dt><dd> |
| 235 | <dt><b><tt id='l2h-2645' xml:id='l2h-2645'>IPV6_*</tt></b></dt><dd> |
| 236 | <dt><b><tt id='l2h-2646' xml:id='l2h-2646'>EAI_*</tt></b></dt><dd> |
| 237 | <dt><b><tt id='l2h-2647' xml:id='l2h-2647'>AI_*</tt></b></dt><dd> |
| 238 | <dt><b><tt id='l2h-2648' xml:id='l2h-2648'>NI_*</tt></b></dt><dd> |
| 239 | <dt><b><tt id='l2h-2649' xml:id='l2h-2649'>TCP_*</tt></b></dt><dd> |
| 240 | Many constants of these forms, documented in the <span class="Unix">Unix</span> documentation on |
| 241 | sockets and/or the IP protocol, are also defined in the socket module. |
| 242 | They are generally used in arguments to the <tt class="method">setsockopt()</tt> and |
| 243 | <tt class="method">getsockopt()</tt> methods of socket objects. In most cases, only |
| 244 | those symbols that are defined in the <span class="Unix">Unix</span> header files are defined; |
| 245 | for a few symbols, default values are provided. |
| 246 | </dd></dl> |
| 247 | |
| 248 | <P> |
| 249 | <dl><dt><b><tt id='l2h-2605' xml:id='l2h-2605'>has_ipv6</tt></b></dt> |
| 250 | <dd> |
| 251 | This constant contains a boolean value which indicates if IPv6 is |
| 252 | supported on this platform. |
| 253 | |
| 254 | <span class="versionnote">New in version 2.3.</span> |
| 255 | |
| 256 | </dd></dl> |
| 257 | |
| 258 | <P> |
| 259 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 260 | <td><nobr><b><tt id='l2h-2606' xml:id='l2h-2606' class="function">getaddrinfo</tt></b>(</nobr></td> |
| 261 | <td><var>host, port</var><big>[</big><var>, family</var><big>[</big><var>, |
| 262 | socktype</var><big>[</big><var>, proto</var><big>[</big><var>, |
| 263 | flags</var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt> |
| 264 | <dd> |
| 265 | Resolves the <var>host</var>/<var>port</var> argument, into a sequence of |
| 266 | 5-tuples that contain all the necessary argument for the sockets |
| 267 | manipulation. <var>host</var> is a domain name, a string representation of |
| 268 | IPv4/v6 address or <code>None</code>. |
| 269 | <var>port</var> is a string service name (like <code>'http'</code>), a numeric |
| 270 | port number or <code>None</code>. |
| 271 | |
| 272 | <P> |
| 273 | The rest of the arguments are optional and must be numeric if |
| 274 | specified. For <var>host</var> and <var>port</var>, by passing either an empty |
| 275 | string or <code>None</code>, you can pass <code>NULL</code> to the C API. The |
| 276 | <tt class="function">getaddrinfo()</tt> function returns a list of 5-tuples with |
| 277 | the following structure: |
| 278 | |
| 279 | <P> |
| 280 | <code>(<var>family</var>, <var>socktype</var>, <var>proto</var>, <var>canonname</var>, |
| 281 | <var>sockaddr</var>)</code> |
| 282 | |
| 283 | <P> |
| 284 | <var>family</var>, <var>socktype</var>, <var>proto</var> are all integer and are meant to |
| 285 | be passed to the <tt class="function">socket()</tt> function. |
| 286 | <var>canonname</var> is a string representing the canonical name of the <var>host</var>. |
| 287 | It can be a numeric IPv4/v6 address when <tt class="constant">AI_CANONNAME</tt> is specified |
| 288 | for a numeric <var>host</var>. |
| 289 | <var>sockaddr</var> is a tuple describing a socket address, as described above. |
| 290 | See the source for the <tt class="module"><a href="module-httplib.html">httplib</a></tt> and other library modules |
| 291 | for a typical usage of the function. |
| 292 | |
| 293 | <span class="versionnote">New in version 2.2.</span> |
| 294 | |
| 295 | </dl> |
| 296 | |
| 297 | <P> |
| 298 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 299 | <td><nobr><b><tt id='l2h-2607' xml:id='l2h-2607' class="function">getfqdn</tt></b>(</nobr></td> |
| 300 | <td><var></var><big>[</big><var>name</var><big>]</big><var></var>)</td></tr></table></dt> |
| 301 | <dd> |
| 302 | Return a fully qualified domain name for <var>name</var>. |
| 303 | If <var>name</var> is omitted or empty, it is interpreted as the local |
| 304 | host. To find the fully qualified name, the hostname returned by |
| 305 | <tt class="function">gethostbyaddr()</tt> is checked, then aliases for the host, if |
| 306 | available. The first name which includes a period is selected. In |
| 307 | case no fully qualified domain name is available, the hostname as |
| 308 | returned by <tt class="function">gethostname()</tt> is returned. |
| 309 | |
| 310 | <span class="versionnote">New in version 2.0.</span> |
| 311 | |
| 312 | </dl> |
| 313 | |
| 314 | <P> |
| 315 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 316 | <td><nobr><b><tt id='l2h-2608' xml:id='l2h-2608' class="function">gethostbyname</tt></b>(</nobr></td> |
| 317 | <td><var>hostname</var>)</td></tr></table></dt> |
| 318 | <dd> |
| 319 | Translate a host name to IPv4 address format. The IPv4 address is |
| 320 | returned as a string, such as <code>'100.50.200.5'</code>. If the host name |
| 321 | is an IPv4 address itself it is returned unchanged. See |
| 322 | <tt class="function">gethostbyname_ex()</tt> for a more complete interface. |
| 323 | <tt class="function">gethostbyname()</tt> does not support IPv6 name resolution, and |
| 324 | <tt class="function">getaddrinfo()</tt> should be used instead for IPv4/v6 dual stack support. |
| 325 | </dl> |
| 326 | |
| 327 | <P> |
| 328 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 329 | <td><nobr><b><tt id='l2h-2609' xml:id='l2h-2609' class="function">gethostbyname_ex</tt></b>(</nobr></td> |
| 330 | <td><var>hostname</var>)</td></tr></table></dt> |
| 331 | <dd> |
| 332 | Translate a host name to IPv4 address format, extended interface. |
| 333 | Return a triple <code>(<var>hostname</var>, <var>aliaslist</var>, |
| 334 | <var>ipaddrlist</var>)</code> where |
| 335 | <var>hostname</var> is the primary host name responding to the given |
| 336 | <var>ip_address</var>, <var>aliaslist</var> is a (possibly empty) list of |
| 337 | alternative host names for the same address, and <var>ipaddrlist</var> is |
| 338 | a list of IPv4 addresses for the same interface on the same |
| 339 | host (often but not always a single address). |
| 340 | <tt class="function">gethostbyname_ex()</tt> does not support IPv6 name resolution, and |
| 341 | <tt class="function">getaddrinfo()</tt> should be used instead for IPv4/v6 dual stack support. |
| 342 | </dl> |
| 343 | |
| 344 | <P> |
| 345 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 346 | <td><nobr><b><tt id='l2h-2610' xml:id='l2h-2610' class="function">gethostname</tt></b>(</nobr></td> |
| 347 | <td><var></var>)</td></tr></table></dt> |
| 348 | <dd> |
| 349 | Return a string containing the hostname of the machine where |
| 350 | the Python interpreter is currently executing. |
| 351 | If you want to know the current machine's IP address, you may want to use |
| 352 | <code>gethostbyname(gethostname())</code>. |
| 353 | This operation assumes that there is a valid address-to-host mapping for |
| 354 | the host, and the assumption does not always hold. |
| 355 | Note: <tt class="function">gethostname()</tt> doesn't always return the fully qualified |
| 356 | domain name; use <code>gethostbyaddr(gethostname())</code> |
| 357 | (see below). |
| 358 | </dl> |
| 359 | |
| 360 | <P> |
| 361 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 362 | <td><nobr><b><tt id='l2h-2611' xml:id='l2h-2611' class="function">gethostbyaddr</tt></b>(</nobr></td> |
| 363 | <td><var>ip_address</var>)</td></tr></table></dt> |
| 364 | <dd> |
| 365 | Return a triple <code>(<var>hostname</var>, <var>aliaslist</var>, |
| 366 | <var>ipaddrlist</var>)</code> where <var>hostname</var> is the primary host name |
| 367 | responding to the given <var>ip_address</var>, <var>aliaslist</var> is a |
| 368 | (possibly empty) list of alternative host names for the same address, |
| 369 | and <var>ipaddrlist</var> is a list of IPv4/v6 addresses for the same interface |
| 370 | on the same host (most likely containing only a single address). |
| 371 | To find the fully qualified domain name, use the function |
| 372 | <tt class="function">getfqdn()</tt>. |
| 373 | <tt class="function">gethostbyaddr</tt> supports both IPv4 and IPv6. |
| 374 | </dl> |
| 375 | |
| 376 | <P> |
| 377 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 378 | <td><nobr><b><tt id='l2h-2612' xml:id='l2h-2612' class="function">getnameinfo</tt></b>(</nobr></td> |
| 379 | <td><var>sockaddr, flags</var>)</td></tr></table></dt> |
| 380 | <dd> |
| 381 | Translate a socket address <var>sockaddr</var> into a 2-tuple |
| 382 | <code>(<var>host</var>, <var>port</var>)</code>. |
| 383 | Depending on the settings of <var>flags</var>, the result can contain a |
| 384 | fully-qualified domain name or numeric address representation in |
| 385 | <var>host</var>. Similarly, <var>port</var> can contain a string port name or a |
| 386 | numeric port number. |
| 387 | |
| 388 | <span class="versionnote">New in version 2.2.</span> |
| 389 | |
| 390 | </dl> |
| 391 | |
| 392 | <P> |
| 393 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 394 | <td><nobr><b><tt id='l2h-2613' xml:id='l2h-2613' class="function">getprotobyname</tt></b>(</nobr></td> |
| 395 | <td><var>protocolname</var>)</td></tr></table></dt> |
| 396 | <dd> |
| 397 | Translate an Internet protocol name (for example, <code>'icmp'</code>) to a constant |
| 398 | suitable for passing as the (optional) third argument to the |
| 399 | <tt class="function">socket()</tt> function. This is usually only needed for sockets |
| 400 | opened in ``raw'' mode (<tt class="constant">SOCK_RAW</tt>); for the normal socket |
| 401 | modes, the correct protocol is chosen automatically if the protocol is |
| 402 | omitted or zero. |
| 403 | </dl> |
| 404 | |
| 405 | <P> |
| 406 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 407 | <td><nobr><b><tt id='l2h-2614' xml:id='l2h-2614' class="function">getservbyname</tt></b>(</nobr></td> |
| 408 | <td><var>servicename</var><big>[</big><var>, protocolname</var><big>]</big><var></var>)</td></tr></table></dt> |
| 409 | <dd> |
| 410 | Translate an Internet service name and protocol name to a port number |
| 411 | for that service. The optional protocol name, if given, should be |
| 412 | <code>'tcp'</code> or <code>'udp'</code>, otherwise any protocol will match. |
| 413 | </dl> |
| 414 | |
| 415 | <P> |
| 416 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 417 | <td><nobr><b><tt id='l2h-2615' xml:id='l2h-2615' class="function">getservbyport</tt></b>(</nobr></td> |
| 418 | <td><var>port</var><big>[</big><var>, protocolname</var><big>]</big><var></var>)</td></tr></table></dt> |
| 419 | <dd> |
| 420 | Translate an Internet port number and protocol name to a service name |
| 421 | for that service. The optional protocol name, if given, should be |
| 422 | <code>'tcp'</code> or <code>'udp'</code>, otherwise any protocol will match. |
| 423 | </dl> |
| 424 | |
| 425 | <P> |
| 426 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 427 | <td><nobr><b><tt id='l2h-2616' xml:id='l2h-2616' class="function">socket</tt></b>(</nobr></td> |
| 428 | <td><var></var><big>[</big><var>family</var><big>[</big><var>, |
| 429 | type</var><big>[</big><var>, proto</var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt> |
| 430 | <dd> |
| 431 | Create a new socket using the given address family, socket type and |
| 432 | protocol number. The address family should be <tt class="constant">AF_INET</tt> (the |
| 433 | default), <tt class="constant">AF_INET6</tt> or <tt class="constant">AF_UNIX</tt>. The socket type |
| 434 | should be <tt class="constant">SOCK_STREAM</tt> (the default), <tt class="constant">SOCK_DGRAM</tt> |
| 435 | or perhaps one of the other "<tt class="samp">SOCK_</tt>" constants. The protocol |
| 436 | number is usually zero and may be omitted in that case. |
| 437 | </dl> |
| 438 | |
| 439 | <P> |
| 440 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 441 | <td><nobr><b><tt id='l2h-2617' xml:id='l2h-2617' class="function">ssl</tt></b>(</nobr></td> |
| 442 | <td><var>sock</var><big>[</big><var>, keyfile, certfile</var><big>]</big><var></var>)</td></tr></table></dt> |
| 443 | <dd> |
| 444 | Initiate a SSL connection over the socket <var>sock</var>. <var>keyfile</var> is |
| 445 | the name of a PEM formatted file that contains your private |
| 446 | key. <var>certfile</var> is a PEM formatted certificate chain file. On |
| 447 | success, a new <tt class="class">SSLObject</tt> is returned. |
| 448 | |
| 449 | <P> |
| 450 | <span class="warning"><b class="label">Warning:</b> |
| 451 | This does not do any certificate verification!</span> |
| 452 | </dl> |
| 453 | |
| 454 | <P> |
| 455 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 456 | <td><nobr><b><tt id='l2h-2618' xml:id='l2h-2618' class="function">socketpair</tt></b>(</nobr></td> |
| 457 | <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> |
| 458 | <dd> |
| 459 | Build a pair of connected socket objects using the given address |
| 460 | family, socket type, and protocol number. Address family, socket type, |
| 461 | and protocol number are as for the <tt class="function">socket()</tt> function above. |
| 462 | The default family is <tt class="constant">AF_UNIX</tt> if defined on the platform; |
| 463 | otherwise, the default is <tt class="constant">AF_INET</tt>. |
| 464 | Availability: <span class="Unix">Unix</span>. |
| 465 | <span class="versionnote">New in version 2.4.</span> |
| 466 | |
| 467 | </dl> |
| 468 | |
| 469 | <P> |
| 470 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 471 | <td><nobr><b><tt id='l2h-2619' xml:id='l2h-2619' class="function">fromfd</tt></b>(</nobr></td> |
| 472 | <td><var>fd, family, type</var><big>[</big><var>, proto</var><big>]</big><var></var>)</td></tr></table></dt> |
| 473 | <dd> |
| 474 | Build a socket object from an existing file descriptor (an integer as |
| 475 | returned by a file object's <tt class="method">fileno()</tt> method). Address family, |
| 476 | socket type and protocol number are as for the <tt class="function">socket()</tt> function |
| 477 | above. The file descriptor should refer to a socket, but this is not |
| 478 | checked -- subsequent operations on the object may fail if the file |
| 479 | descriptor is invalid. This function is rarely needed, but can be |
| 480 | used to get or set socket options on a socket passed to a program as |
| 481 | standard input or output (such as a server started by the <span class="Unix">Unix</span> inet |
| 482 | daemon). The socket is assumed to be in blocking mode. |
| 483 | Availability: <span class="Unix">Unix</span>. |
| 484 | </dl> |
| 485 | |
| 486 | <P> |
| 487 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 488 | <td><nobr><b><tt id='l2h-2620' xml:id='l2h-2620' class="function">ntohl</tt></b>(</nobr></td> |
| 489 | <td><var>x</var>)</td></tr></table></dt> |
| 490 | <dd> |
| 491 | Convert 32-bit integers from network to host byte order. On machines |
| 492 | where the host byte order is the same as network byte order, this is a |
| 493 | no-op; otherwise, it performs a 4-byte swap operation. |
| 494 | </dl> |
| 495 | |
| 496 | <P> |
| 497 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 498 | <td><nobr><b><tt id='l2h-2621' xml:id='l2h-2621' class="function">ntohs</tt></b>(</nobr></td> |
| 499 | <td><var>x</var>)</td></tr></table></dt> |
| 500 | <dd> |
| 501 | Convert 16-bit integers from network to host byte order. On machines |
| 502 | where the host byte order is the same as network byte order, this is a |
| 503 | no-op; otherwise, it performs a 2-byte swap operation. |
| 504 | </dl> |
| 505 | |
| 506 | <P> |
| 507 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 508 | <td><nobr><b><tt id='l2h-2622' xml:id='l2h-2622' class="function">htonl</tt></b>(</nobr></td> |
| 509 | <td><var>x</var>)</td></tr></table></dt> |
| 510 | <dd> |
| 511 | Convert 32-bit integers from host to network byte order. On machines |
| 512 | where the host byte order is the same as network byte order, this is a |
| 513 | no-op; otherwise, it performs a 4-byte swap operation. |
| 514 | </dl> |
| 515 | |
| 516 | <P> |
| 517 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 518 | <td><nobr><b><tt id='l2h-2623' xml:id='l2h-2623' class="function">htons</tt></b>(</nobr></td> |
| 519 | <td><var>x</var>)</td></tr></table></dt> |
| 520 | <dd> |
| 521 | Convert 16-bit integers from host to network byte order. On machines |
| 522 | where the host byte order is the same as network byte order, this is a |
| 523 | no-op; otherwise, it performs a 2-byte swap operation. |
| 524 | </dl> |
| 525 | |
| 526 | <P> |
| 527 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 528 | <td><nobr><b><tt id='l2h-2624' xml:id='l2h-2624' class="function">inet_aton</tt></b>(</nobr></td> |
| 529 | <td><var>ip_string</var>)</td></tr></table></dt> |
| 530 | <dd> |
| 531 | Convert an IPv4 address from dotted-quad string format (for example, |
| 532 | '123.45.67.89') to 32-bit packed binary format, as a string four |
| 533 | characters in length. This is useful when conversing with a program |
| 534 | that uses the standard C library and needs objects of type |
| 535 | <tt class="ctype">struct in_addr</tt>, which is the C type for the 32-bit packed |
| 536 | binary this function returns. |
| 537 | |
| 538 | <P> |
| 539 | If the IPv4 address string passed to this function is invalid, |
| 540 | <tt class="exception">socket.error</tt> will be raised. Note that exactly what is |
| 541 | valid depends on the underlying C implementation of |
| 542 | <tt class="cfunction">inet_aton()</tt>. |
| 543 | |
| 544 | <P> |
| 545 | <tt class="function">inet_aton()</tt> does not support IPv6, and |
| 546 | <tt class="function">getnameinfo()</tt> should be used instead for IPv4/v6 dual stack |
| 547 | support. |
| 548 | </dl> |
| 549 | |
| 550 | <P> |
| 551 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 552 | <td><nobr><b><tt id='l2h-2625' xml:id='l2h-2625' class="function">inet_ntoa</tt></b>(</nobr></td> |
| 553 | <td><var>packed_ip</var>)</td></tr></table></dt> |
| 554 | <dd> |
| 555 | Convert a 32-bit packed IPv4 address (a string four characters in |
| 556 | length) to its standard dotted-quad string representation (for |
| 557 | example, '123.45.67.89'). This is useful when conversing with a |
| 558 | program that uses the standard C library and needs objects of type |
| 559 | <tt class="ctype">struct in_addr</tt>, which is the C type for the 32-bit packed |
| 560 | binary data this function takes as an argument. |
| 561 | |
| 562 | <P> |
| 563 | If the string passed to this function is not exactly 4 bytes in |
| 564 | length, <tt class="exception">socket.error</tt> will be raised. |
| 565 | <tt class="function">inet_ntoa()</tt> does not support IPv6, and |
| 566 | <tt class="function">getnameinfo()</tt> should be used instead for IPv4/v6 dual stack |
| 567 | support. |
| 568 | </dl> |
| 569 | |
| 570 | <P> |
| 571 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 572 | <td><nobr><b><tt id='l2h-2626' xml:id='l2h-2626' class="function">inet_pton</tt></b>(</nobr></td> |
| 573 | <td><var>address_family, ip_string</var>)</td></tr></table></dt> |
| 574 | <dd> |
| 575 | Convert an IP address from its family-specific string format to a packed, |
| 576 | binary format. |
| 577 | <tt class="function">inet_pton()</tt> is useful when a library or network protocol calls for |
| 578 | an object of type <tt class="ctype">struct in_addr</tt> (similar to <tt class="function">inet_aton()</tt>) |
| 579 | or <tt class="ctype">struct in6_addr</tt>. |
| 580 | |
| 581 | <P> |
| 582 | Supported values for <var>address_family</var> are currently |
| 583 | <tt class="constant">AF_INET</tt> and <tt class="constant">AF_INET6</tt>. |
| 584 | If the IP address string <var>ip_string</var> is invalid, |
| 585 | <tt class="exception">socket.error</tt> will be raised. Note that exactly what is valid |
| 586 | depends on both the value of <var>address_family</var> and the underlying |
| 587 | implementation of <tt class="cfunction">inet_pton()</tt>. |
| 588 | |
| 589 | <P> |
| 590 | Availability: <span class="Unix">Unix</span> (maybe not all platforms). |
| 591 | |
| 592 | <span class="versionnote">New in version 2.3.</span> |
| 593 | |
| 594 | </dl> |
| 595 | |
| 596 | <P> |
| 597 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 598 | <td><nobr><b><tt id='l2h-2627' xml:id='l2h-2627' class="function">inet_ntop</tt></b>(</nobr></td> |
| 599 | <td><var>address_family, packed_ip</var>)</td></tr></table></dt> |
| 600 | <dd> |
| 601 | Convert a packed IP address (a string of some number of characters) to |
| 602 | its standard, family-specific string representation (for example, |
| 603 | <code>'7.10.0.5'</code> or <code>'5aef:2b::8'</code>) |
| 604 | <tt class="function">inet_ntop()</tt> is useful when a library or network protocol returns |
| 605 | an object of type <tt class="ctype">struct in_addr</tt> (similar to <tt class="function">inet_ntoa()</tt>) |
| 606 | or <tt class="ctype">struct in6_addr</tt>. |
| 607 | |
| 608 | <P> |
| 609 | Supported values for <var>address_family</var> are currently |
| 610 | <tt class="constant">AF_INET</tt> and <tt class="constant">AF_INET6</tt>. |
| 611 | If the string <var>packed_ip</var> is not the correct length for the |
| 612 | specified address family, <tt class="exception">ValueError</tt> will be raised. A |
| 613 | <tt class="exception">socket.error</tt> is raised for errors from the call to |
| 614 | <tt class="function">inet_ntop()</tt>. |
| 615 | |
| 616 | <P> |
| 617 | Availability: <span class="Unix">Unix</span> (maybe not all platforms). |
| 618 | |
| 619 | <span class="versionnote">New in version 2.3.</span> |
| 620 | |
| 621 | </dl> |
| 622 | |
| 623 | <P> |
| 624 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 625 | <td><nobr><b><tt id='l2h-2628' xml:id='l2h-2628' class="function">getdefaulttimeout</tt></b>(</nobr></td> |
| 626 | <td><var></var>)</td></tr></table></dt> |
| 627 | <dd> |
| 628 | Return the default timeout in floating seconds for new socket objects. |
| 629 | A value of <code>None</code> indicates that new socket objects have no timeout. |
| 630 | When the socket module is first imported, the default is <code>None</code>. |
| 631 | |
| 632 | <span class="versionnote">New in version 2.3.</span> |
| 633 | |
| 634 | </dl> |
| 635 | |
| 636 | <P> |
| 637 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 638 | <td><nobr><b><tt id='l2h-2629' xml:id='l2h-2629' class="function">setdefaulttimeout</tt></b>(</nobr></td> |
| 639 | <td><var>timeout</var>)</td></tr></table></dt> |
| 640 | <dd> |
| 641 | Set the default timeout in floating seconds for new socket objects. |
| 642 | A value of <code>None</code> indicates that new socket objects have no timeout. |
| 643 | When the socket module is first imported, the default is <code>None</code>. |
| 644 | |
| 645 | <span class="versionnote">New in version 2.3.</span> |
| 646 | |
| 647 | </dl> |
| 648 | |
| 649 | <P> |
| 650 | <dl><dt><b><tt id='l2h-2630' xml:id='l2h-2630'>SocketType</tt></b></dt> |
| 651 | <dd> |
| 652 | This is a Python type object that represents the socket object type. |
| 653 | It is the same as <code>type(socket(...))</code>. |
| 654 | </dd></dl> |
| 655 | |
| 656 | <P> |
| 657 | <div class="seealso"> |
| 658 | <p class="heading">See Also:</p> |
| 659 | |
| 660 | <dl compact="compact" class="seemodule"> |
| 661 | <dt>Module <b><tt class="module"><a href="module-SocketServer.html">SocketServer</a></tt>:</b> |
| 662 | <dd>Classes that simplify writing network servers. |
| 663 | </dl> |
| 664 | </div> |
| 665 | |
| 666 | <P> |
| 667 | |
| 668 | <p><br /></p><hr class='online-navigation' /> |
| 669 | <div class='online-navigation'> |
| 670 | <!--Table of Child-Links--> |
| 671 | <A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a> |
| 672 | |
| 673 | <UL CLASS="ChildLinks"> |
| 674 | <LI><A href="socket-objects.html">7.2.1 Socket Objects</a> |
| 675 | <LI><A href="ssl-objects.html">7.2.2 SSL Objects</a> |
| 676 | <LI><A href="socket-example.html">7.2.3 Example</a> |
| 677 | </ul> |
| 678 | <!--End of Table of Child-Links--> |
| 679 | </div> |
| 680 | |
| 681 | <DIV CLASS="navigation"> |
| 682 | <div class='online-navigation'> |
| 683 | <p></p><hr /> |
| 684 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> |
| 685 | <tr> |
| 686 | <td class='online-navigation'><a rel="prev" title="7.1.1 Example" |
| 687 | href="node373.html"><img src='../icons/previous.png' |
| 688 | border='0' height='32' alt='Previous Page' width='32' /></A></td> |
| 689 | <td class='online-navigation'><a rel="parent" title="7. Optional Operating System" |
| 690 | href="someos.html"><img src='../icons/up.png' |
| 691 | border='0' height='32' alt='Up One Level' width='32' /></A></td> |
| 692 | <td class='online-navigation'><a rel="next" title="7.2.1 Socket Objects" |
| 693 | href="socket-objects.html"><img src='../icons/next.png' |
| 694 | border='0' height='32' alt='Next Page' width='32' /></A></td> |
| 695 | <td align="center" width="100%">Python Library Reference</td> |
| 696 | <td class='online-navigation'><a rel="contents" title="Table of Contents" |
| 697 | href="contents.html"><img src='../icons/contents.png' |
| 698 | border='0' height='32' alt='Contents' width='32' /></A></td> |
| 699 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' |
| 700 | border='0' height='32' alt='Module Index' width='32' /></a></td> |
| 701 | <td class='online-navigation'><a rel="index" title="Index" |
| 702 | href="genindex.html"><img src='../icons/index.png' |
| 703 | border='0' height='32' alt='Index' width='32' /></A></td> |
| 704 | </tr></table> |
| 705 | <div class='online-navigation'> |
| 706 | <b class="navlabel">Previous:</b> |
| 707 | <a class="sectref" rel="prev" href="node373.html">7.1.1 Example</A> |
| 708 | <b class="navlabel">Up:</b> |
| 709 | <a class="sectref" rel="parent" href="someos.html">7. Optional Operating System</A> |
| 710 | <b class="navlabel">Next:</b> |
| 711 | <a class="sectref" rel="next" href="socket-objects.html">7.2.1 Socket Objects</A> |
| 712 | </div> |
| 713 | </div> |
| 714 | <hr /> |
| 715 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> |
| 716 | </DIV> |
| 717 | <!--End of Navigation Panel--> |
| 718 | <ADDRESS> |
| 719 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. |
| 720 | </ADDRESS> |
| 721 | </BODY> |
| 722 | </HTML> |