ReStructuredText | 1017 lines | 710 code | 307 blank | 0 comment | 0 complexity | 668e151389f8b5107cba8185cb103dd2 MD5 | raw file
Possible License(s): BSD-3-Clause
1:mod:`socket` --- Low-level networking interface 2================================================ 3 4.. module:: socket 5 :synopsis: Low-level networking interface. 6 7 8This module provides access to the BSD *socket* interface. It is available on 9all modern Unix systems, Windows, Mac OS X, BeOS, OS/2, and probably additional 10platforms. 11 12.. note:: 13 14 Some behavior may be platform dependent, since calls are made to the operating 15 system socket APIs. 16 17For an introduction to socket programming (in C), see the following papers: An 18Introductory 4.3BSD Interprocess Communication Tutorial, by Stuart Sechrest and 19An Advanced 4.3BSD Interprocess Communication Tutorial, by Samuel J. Leffler et 20al, both in the UNIX Programmer's Manual, Supplementary Documents 1 (sections 21PS1:7 and PS1:8). The platform-specific reference material for the various 22socket-related system calls are also a valuable source of information on the 23details of socket semantics. For Unix, refer to the manual pages; for Windows, 24see the WinSock (or Winsock 2) specification. For IPv6-ready APIs, readers may 25want to refer to :rfc:`3493` titled Basic Socket Interface Extensions for IPv6. 26 27.. index:: object: socket 28 29The Python interface is a straightforward transliteration of the Unix system 30call and library interface for sockets to Python's object-oriented style: the 31:func:`socket` function returns a :dfn:`socket object` whose methods implement 32the various socket system calls. Parameter types are somewhat higher-level than 33in the C interface: as with :meth:`read` and :meth:`write` operations on Python 34files, buffer allocation on receive operations is automatic, and buffer length 35is implicit on send operations. 36 37Socket addresses are represented as follows: A single string is used for the 38:const:`AF_UNIX` address family. A pair ``(host, port)`` is used for the 39:const:`AF_INET` address family, where *host* is a string representing either a 40hostname in Internet domain notation like ``'daring.cwi.nl'`` or an IPv4 address 41like ``'22.214.171.124'``, and *port* is an integral port number. For 42:const:`AF_INET6` address family, a four-tuple ``(host, port, flowinfo, 43scopeid)`` is used, where *flowinfo* and *scopeid* represents ``sin6_flowinfo`` 44and ``sin6_scope_id`` member in :const:`struct sockaddr_in6` in C. For 45:mod:`socket` module methods, *flowinfo* and *scopeid* can be omitted just for 46backward compatibility. Note, however, omission of *scopeid* can cause problems 47in manipulating scoped IPv6 addresses. Other address families are currently not 48supported. The address format required by a particular socket object is 49automatically selected based on the address family specified when the socket 50object was created. 51 52For IPv4 addresses, two special forms are accepted instead of a host address: 53the empty string represents :const:`INADDR_ANY`, and the string 54``'<broadcast>'`` represents :const:`INADDR_BROADCAST`. The behavior is not 55available for IPv6 for backward compatibility, therefore, you may want to avoid 56these if you intend to support IPv6 with your Python programs. 57 58If you use a hostname in the *host* portion of IPv4/v6 socket address, the 59program may show a nondeterministic behavior, as Python uses the first address 60returned from the DNS resolution. The socket address will be resolved 61differently into an actual IPv4/v6 address, depending on the results from DNS 62resolution and/or the host configuration. For deterministic behavior use a 63numeric address in *host* portion. 64 65.. versionadded:: 2.5 66 AF_NETLINK sockets are represented as pairs ``pid, groups``. 67 68.. versionadded:: 2.6 69 Linux-only support for TIPC is also available using the :const:`AF_TIPC` 70 address family. TIPC is an open, non-IP based networked protocol designed 71 for use in clustered computer environments. Addresses are represented by a 72 tuple, and the fields depend on the address type. The general tuple form is 73 ``(addr_type, v1, v2, v3 [, scope])``, where: 74 75 - *addr_type* is one of TIPC_ADDR_NAMESEQ, TIPC_ADDR_NAME, or 76 TIPC_ADDR_ID. 77 - *scope* is one of TIPC_ZONE_SCOPE, TIPC_CLUSTER_SCOPE, and 78 TIPC_NODE_SCOPE. 79 - If *addr_type* is TIPC_ADDR_NAME, then *v1* is the server type, *v2* is 80 the port identifier, and *v3* should be 0. 81 82 If *addr_type* is TIPC_ADDR_NAMESEQ, then *v1* is the server type, *v2* 83 is the lower port number, and *v3* is the upper port number. 84 85 If *addr_type* is TIPC_ADDR_ID, then *v1* is the node, *v2* is the 86 reference, and *v3* should be set to 0. 87 88 89All errors raise exceptions. The normal exceptions for invalid argument types 90and out-of-memory conditions can be raised; errors related to socket or address 91semantics raise the error :exc:`socket.error`. 92 93Non-blocking mode is supported through :meth:`~socket.setblocking`. A 94generalization of this based on timeouts is supported through 95:meth:`~socket.settimeout`. 96 97The module :mod:`socket` exports the following constants and functions: 98 99 100.. exception:: error 101 102 .. index:: module: errno 103 104 This exception is raised for socket-related errors. The accompanying value is 105 either a string telling what went wrong or a pair ``(errno, string)`` 106 representing an error returned by a system call, similar to the value 107 accompanying :exc:`os.error`. See the module :mod:`errno`, which contains names 108 for the error codes defined by the underlying operating system. 109 110 .. versionchanged:: 2.6 111 :exc:`socket.error` is now a child class of :exc:`IOError`. 112 113 114.. exception:: herror 115 116 This exception is raised for address-related errors, i.e. for functions that use 117 *h_errno* in the C API, including :func:`gethostbyname_ex` and 118 :func:`gethostbyaddr`. 119 120 The accompanying value is a pair ``(h_errno, string)`` representing an error 121 returned by a library call. *string* represents the description of *h_errno*, as 122 returned by the :c:func:`hstrerror` C function. 123 124 125.. exception:: gaierror 126 127 This exception is raised for address-related errors, for :func:`getaddrinfo` and 128 :func:`getnameinfo`. The accompanying value is a pair ``(error, string)`` 129 representing an error returned by a library call. *string* represents the 130 description of *error*, as returned by the :c:func:`gai_strerror` C function. The 131 *error* value will match one of the :const:`EAI_\*` constants defined in this 132 module. 133 134 135.. exception:: timeout 136 137 This exception is raised when a timeout occurs on a socket which has had 138 timeouts enabled via a prior call to :meth:`settimeout`. The accompanying value 139 is a string whose value is currently always "timed out". 140 141 .. versionadded:: 2.3 142 143 144.. data:: AF_UNIX 145 AF_INET 146 AF_INET6 147 148 These constants represent the address (and protocol) families, used for the 149 first argument to :func:`socket`. If the :const:`AF_UNIX` constant is not 150 defined then this protocol is unsupported. 151 152 153.. data:: SOCK_STREAM 154 SOCK_DGRAM 155 SOCK_RAW 156 SOCK_RDM 157 SOCK_SEQPACKET 158 159 These constants represent the socket types, used for the second argument to 160 :func:`socket`. (Only :const:`SOCK_STREAM` and :const:`SOCK_DGRAM` appear to be 161 generally useful.) 162 163 164.. data:: SO_* 165 SOMAXCONN 166 MSG_* 167 SOL_* 168 IPPROTO_* 169 IPPORT_* 170 INADDR_* 171 IP_* 172 IPV6_* 173 EAI_* 174 AI_* 175 NI_* 176 TCP_* 177 178 Many constants of these forms, documented in the Unix documentation on sockets 179 and/or the IP protocol, are also defined in the socket module. They are 180 generally used in arguments to the :meth:`setsockopt` and :meth:`getsockopt` 181 methods of socket objects. In most cases, only those symbols that are defined 182 in the Unix header files are defined; for a few symbols, default values are 183 provided. 184 185.. data:: SIO_* 186 RCVALL_* 187 188 Constants for Windows' WSAIoctl(). The constants are used as arguments to the 189 :meth:`ioctl` method of socket objects. 190 191 .. versionadded:: 2.6 192 193.. data:: TIPC_* 194 195 TIPC related constants, matching the ones exported by the C socket API. See 196 the TIPC documentation for more information. 197 198 .. versionadded:: 2.6 199 200.. data:: has_ipv6 201 202 This constant contains a boolean value which indicates if IPv6 is supported on 203 this platform. 204 205 .. versionadded:: 2.3 206 207 208.. function:: create_connection(address[, timeout[, source_address]]) 209 210 Connect to a TCP service listening on the Internet *address* (a 2-tuple 211 ``(host, port)``), and return the socket object. This is a higher-level 212 function than :meth:`socket.connect`: if *host* is a non-numeric hostname, 213 it will try to resolve it for both :data:`AF_INET` and :data:`AF_INET6`, 214 and then try to connect to all possible addresses in turn until a 215 connection succeeds. This makes it easy to write clients that are 216 compatible to both IPv4 and IPv6. 217 218 Passing the optional *timeout* parameter will set the timeout on the 219 socket instance before attempting to connect. If no *timeout* is 220 supplied, the global default timeout setting returned by 221 :func:`getdefaulttimeout` is used. 222 223 If supplied, *source_address* must be a 2-tuple ``(host, port)`` for the 224 socket to bind to as its source address before connecting. If host or port 225 are '' or 0 respectively the OS default behavior will be used. 226 227 .. versionadded:: 2.6 228 229 .. versionchanged:: 2.7 230 *source_address* was added. 231 232 233.. function:: getaddrinfo(host, port, family=0, socktype=0, proto=0, flags=0) 234 235 Translate the *host*/*port* argument into a sequence of 5-tuples that contain 236 all the necessary arguments for creating a socket connected to that service. 237 *host* is a domain name, a string representation of an IPv4/v6 address 238 or ``None``. *port* is a string service name such as ``'http'``, a numeric 239 port number or ``None``. By passing ``None`` as the value of *host* 240 and *port*, you can pass ``NULL`` to the underlying C API. 241 242 The *family*, *socktype* and *proto* arguments can be optionally specified 243 in order to narrow the list of addresses returned. Passing zero as a 244 value for each of these arguments selects the full range of results. 245 The *flags* argument can be one or several of the ``AI_*`` constants, 246 and will influence how results are computed and returned. 247 For example, :const:`AI_NUMERICHOST` will disable domain name resolution 248 and will raise an error if *host* is a domain name. 249 250 The function returns a list of 5-tuples with the following structure: 251 252 ``(family, socktype, proto, canonname, sockaddr)`` 253 254 In these tuples, *family*, *socktype*, *proto* are all integers and are 255 meant to be passed to the :func:`socket` function. *canonname* will be 256 a string representing the canonical name of the *host* if 257 :const:`AI_CANONNAME` is part of the *flags* argument; else *canonname* 258 will be empty. *sockaddr* is a tuple describing a socket address, whose 259 format depends on the returned *family* (a ``(address, port)`` 2-tuple for 260 :const:`AF_INET`, a ``(address, port, flow info, scope id)`` 4-tuple for 261 :const:`AF_INET6`), and is meant to be passed to the :meth:`socket.connect` 262 method. 263 264 The following example fetches address information for a hypothetical TCP 265 connection to ``www.python.org`` on port 80 (results may differ on your 266 system if IPv6 isn't enabled):: 267 268 >>> socket.getaddrinfo("www.python.org", 80, 0, 0, socket.SOL_TCP) 269 [(2, 1, 6, '', ('126.96.36.199', 80)), 270 (10, 1, 6, '', ('2001:888:2000:d::a2', 80, 0, 0))] 271 272 .. versionadded:: 2.2 273 274 275.. function:: getfqdn([name]) 276 277 Return a fully qualified domain name for *name*. If *name* is omitted or empty, 278 it is interpreted as the local host. To find the fully qualified name, the 279 hostname returned by :func:`gethostbyaddr` is checked, followed by aliases for the 280 host, if available. The first name which includes a period is selected. In 281 case no fully qualified domain name is available, the hostname as returned by 282 :func:`gethostname` is returned. 283 284 .. versionadded:: 2.0 285 286 287.. function:: gethostbyname(hostname) 288 289 Translate a host name to IPv4 address format. The IPv4 address is returned as a 290 string, such as ``'188.8.131.52'``. If the host name is an IPv4 address itself 291 it is returned unchanged. See :func:`gethostbyname_ex` for a more complete 292 interface. :func:`gethostbyname` does not support IPv6 name resolution, and 293 :func:`getaddrinfo` should be used instead for IPv4/v6 dual stack support. 294 295 296.. function:: gethostbyname_ex(hostname) 297 298 Translate a host name to IPv4 address format, extended interface. Return a 299 triple ``(hostname, aliaslist, ipaddrlist)`` where *hostname* is the primary 300 host name responding to the given *ip_address*, *aliaslist* is a (possibly 301 empty) list of alternative host names for the same address, and *ipaddrlist* is 302 a list of IPv4 addresses for the same interface on the same host (often but not 303 always a single address). :func:`gethostbyname_ex` does not support IPv6 name 304 resolution, and :func:`getaddrinfo` should be used instead for IPv4/v6 dual 305 stack support. 306 307 308.. function:: gethostname() 309 310 Return a string containing the hostname of the machine where the Python 311 interpreter is currently executing. 312 313 If you want to know the current machine's IP address, you may want to use 314 ``gethostbyname(gethostname())``. This operation assumes that there is a 315 valid address-to-host mapping for the host, and the assumption does not 316 always hold. 317 318 Note: :func:`gethostname` doesn't always return the fully qualified domain 319 name; use ``getfqdn()`` (see above). 320 321 322.. function:: gethostbyaddr(ip_address) 323 324 Return a triple ``(hostname, aliaslist, ipaddrlist)`` where *hostname* is the 325 primary host name responding to the given *ip_address*, *aliaslist* is a 326 (possibly empty) list of alternative host names for the same address, and 327 *ipaddrlist* is a list of IPv4/v6 addresses for the same interface on the same 328 host (most likely containing only a single address). To find the fully qualified 329 domain name, use the function :func:`getfqdn`. :func:`gethostbyaddr` supports 330 both IPv4 and IPv6. 331 332 333.. function:: getnameinfo(sockaddr, flags) 334 335 Translate a socket address *sockaddr* into a 2-tuple ``(host, port)``. Depending 336 on the settings of *flags*, the result can contain a fully-qualified domain name 337 or numeric address representation in *host*. Similarly, *port* can contain a 338 string port name or a numeric port number. 339 340 .. versionadded:: 2.2 341 342 343.. function:: getprotobyname(protocolname) 344 345 Translate an Internet protocol name (for example, ``'icmp'``) to a constant 346 suitable for passing as the (optional) third argument to the :func:`socket` 347 function. This is usually only needed for sockets opened in "raw" mode 348 (:const:`SOCK_RAW`); for the normal socket modes, the correct protocol is chosen 349 automatically if the protocol is omitted or zero. 350 351 352.. function:: getservbyname(servicename[, protocolname]) 353 354 Translate an Internet service name and protocol name to a port number for that 355 service. The optional protocol name, if given, should be ``'tcp'`` or 356 ``'udp'``, otherwise any protocol will match. 357 358 359.. function:: getservbyport(port[, protocolname]) 360 361 Translate an Internet port number and protocol name to a service name for that 362 service. The optional protocol name, if given, should be ``'tcp'`` or 363 ``'udp'``, otherwise any protocol will match. 364 365 366.. function:: socket([family[, type[, proto]]]) 367 368 Create a new socket using the given address family, socket type and protocol 369 number. The address family should be :const:`AF_INET` (the default), 370 :const:`AF_INET6` or :const:`AF_UNIX`. The socket type should be 371 :const:`SOCK_STREAM` (the default), :const:`SOCK_DGRAM` or perhaps one of the 372 other ``SOCK_`` constants. The protocol number is usually zero and may be 373 omitted in that case. 374 375 376.. function:: socketpair([family[, type[, proto]]]) 377 378 Build a pair of connected socket objects using the given address family, socket 379 type, and protocol number. Address family, socket type, and protocol number are 380 as for the :func:`socket` function above. The default family is :const:`AF_UNIX` 381 if defined on the platform; otherwise, the default is :const:`AF_INET`. 382 Availability: Unix. 383 384 .. versionadded:: 2.4 385 386 387.. function:: fromfd(fd, family, type[, proto]) 388 389 Duplicate the file descriptor *fd* (an integer as returned by a file object's 390 :meth:`fileno` method) and build a socket object from the result. Address 391 family, socket type and protocol number are as for the :func:`socket` function 392 above. The file descriptor should refer to a socket, but this is not checked --- 393 subsequent operations on the object may fail if the file descriptor is invalid. 394 This function is rarely needed, but can be used to get or set socket options on 395 a socket passed to a program as standard input or output (such as a server 396 started by the Unix inet daemon). The socket is assumed to be in blocking mode. 397 Availability: Unix. 398 399 400.. function:: ntohl(x) 401 402 Convert 32-bit positive integers from network to host byte order. On machines 403 where the host byte order is the same as network byte order, this is a no-op; 404 otherwise, it performs a 4-byte swap operation. 405 406 407.. function:: ntohs(x) 408 409 Convert 16-bit positive integers from network to host byte order. On machines 410 where the host byte order is the same as network byte order, this is a no-op; 411 otherwise, it performs a 2-byte swap operation. 412 413 414.. function:: htonl(x) 415 416 Convert 32-bit positive integers from host to network byte order. On machines 417 where the host byte order is the same as network byte order, this is a no-op; 418 otherwise, it performs a 4-byte swap operation. 419 420 421.. function:: htons(x) 422 423 Convert 16-bit positive integers from host to network byte order. On machines 424 where the host byte order is the same as network byte order, this is a no-op; 425 otherwise, it performs a 2-byte swap operation. 426 427 428.. function:: inet_aton(ip_string) 429 430 Convert an IPv4 address from dotted-quad string format (for example, 431 '184.108.40.206') to 32-bit packed binary format, as a string four characters in 432 length. This is useful when conversing with a program that uses the standard C 433 library and needs objects of type :c:type:`struct in_addr`, which is the C type 434 for the 32-bit packed binary this function returns. 435 436 :func:`inet_aton` also accepts strings with less than three dots; see the 437 Unix manual page :manpage:`inet(3)` for details. 438 439 If the IPv4 address string passed to this function is invalid, 440 :exc:`socket.error` will be raised. Note that exactly what is valid depends on 441 the underlying C implementation of :c:func:`inet_aton`. 442 443 :func:`inet_aton` does not support IPv6, and :func:`inet_pton` should be used 444 instead for IPv4/v6 dual stack support. 445 446 447.. function:: inet_ntoa(packed_ip) 448 449 Convert a 32-bit packed IPv4 address (a string four characters in length) to its 450 standard dotted-quad string representation (for example, '220.127.116.11'). This 451 is useful when conversing with a program that uses the standard C library and 452 needs objects of type :c:type:`struct in_addr`, which is the C type for the 453 32-bit packed binary data this function takes as an argument. 454 455 If the string passed to this function is not exactly 4 bytes in length, 456 :exc:`socket.error` will be raised. :func:`inet_ntoa` does not support IPv6, and 457 :func:`inet_ntop` should be used instead for IPv4/v6 dual stack support. 458 459 460.. function:: inet_pton(address_family, ip_string) 461 462 Convert an IP address from its family-specific string format to a packed, binary 463 format. :func:`inet_pton` is useful when a library or network protocol calls for 464 an object of type :c:type:`struct in_addr` (similar to :func:`inet_aton`) or 465 :c:type:`struct in6_addr`. 466 467 Supported values for *address_family* are currently :const:`AF_INET` and 468 :const:`AF_INET6`. If the IP address string *ip_string* is invalid, 469 :exc:`socket.error` will be raised. Note that exactly what is valid depends on 470 both the value of *address_family* and the underlying implementation of 471 :c:func:`inet_pton`. 472 473 Availability: Unix (maybe not all platforms). 474 475 .. versionadded:: 2.3 476 477 478.. function:: inet_ntop(address_family, packed_ip) 479 480 Convert a packed IP address (a string of some number of characters) to its 481 standard, family-specific string representation (for example, ``'18.104.22.168'`` or 482 ``'5aef:2b::8'``) :func:`inet_ntop` is useful when a library or network protocol 483 returns an object of type :c:type:`struct in_addr` (similar to :func:`inet_ntoa`) 484 or :c:type:`struct in6_addr`. 485 486 Supported values for *address_family* are currently :const:`AF_INET` and 487 :const:`AF_INET6`. If the string *packed_ip* is not the correct length for the 488 specified address family, :exc:`ValueError` will be raised. A 489 :exc:`socket.error` is raised for errors from the call to :func:`inet_ntop`. 490 491 Availability: Unix (maybe not all platforms). 492 493 .. versionadded:: 2.3 494 495 496.. function:: getdefaulttimeout() 497 498 Return the default timeout in seconds (float) for new socket objects. A value 499 of ``None`` indicates that new socket objects have no timeout. When the socket 500 module is first imported, the default is ``None``. 501 502 .. versionadded:: 2.3 503 504 505.. function:: setdefaulttimeout(timeout) 506 507 Set the default timeout in seconds (float) for new socket objects. A value of 508 ``None`` indicates that new socket objects have no timeout. When the socket 509 module is first imported, the default is ``None``. 510 511 .. versionadded:: 2.3 512 513 514.. data:: SocketType 515 516 This is a Python type object that represents the socket object type. It is the 517 same as ``type(socket(...))``. 518 519 520.. seealso:: 521 522 Module :mod:`SocketServer` 523 Classes that simplify writing network servers. 524 525 Module :mod:`ssl` 526 A TLS/SSL wrapper for socket objects. 527 528 529.. _socket-objects: 530 531Socket Objects 532-------------- 533 534Socket objects have the following methods. Except for :meth:`makefile` these 535correspond to Unix system calls applicable to sockets. 536 537 538.. method:: socket.accept() 539 540 Accept a connection. The socket must be bound to an address and listening for 541 connections. The return value is a pair ``(conn, address)`` where *conn* is a 542 *new* socket object usable to send and receive data on the connection, and 543 *address* is the address bound to the socket on the other end of the connection. 544 545 546.. method:: socket.bind(address) 547 548 Bind the socket to *address*. The socket must not already be bound. (The format 549 of *address* depends on the address family --- see above.) 550 551 .. note:: 552 553 This method has historically accepted a pair of parameters for :const:`AF_INET` 554 addresses instead of only a tuple. This was never intentional and is no longer 555 available in Python 2.0 and later. 556 557 558.. method:: socket.close() 559 560 Close the socket. All future operations on the socket object will fail. The 561 remote end will receive no more data (after queued data is flushed). Sockets are 562 automatically closed when they are garbage-collected. 563 564 .. note:: 565 :meth:`close()` releases the resource associated with a connection but 566 does not necessarily close the connection immediately. If you want 567 to close the connection in a timely fashion, call :meth:`shutdown()` 568 before :meth:`close()`. 569 570 571.. method:: socket.connect(address) 572 573 Connect to a remote socket at *address*. (The format of *address* depends on the 574 address family --- see above.) 575 576 .. note:: 577 578 This method has historically accepted a pair of parameters for :const:`AF_INET` 579 addresses instead of only a tuple. This was never intentional and is no longer 580 available in Python 2.0 and later. 581 582 583.. method:: socket.connect_ex(address) 584 585 Like ``connect(address)``, but return an error indicator instead of raising an 586 exception for errors returned by the C-level :c:func:`connect` call (other 587 problems, such as "host not found," can still raise exceptions). The error 588 indicator is ``0`` if the operation succeeded, otherwise the value of the 589 :c:data:`errno` variable. This is useful to support, for example, asynchronous 590 connects. 591 592 .. note:: 593 594 This method has historically accepted a pair of parameters for :const:`AF_INET` 595 addresses instead of only a tuple. This was never intentional and is no longer 596 available in Python 2.0 and later. 597 598 599.. method:: socket.fileno() 600 601 Return the socket's file descriptor (a small integer). This is useful with 602 :func:`select.select`. 603 604 Under Windows the small integer returned by this method cannot be used where a 605 file descriptor can be used (such as :func:`os.fdopen`). Unix does not have 606 this limitation. 607 608 609.. method:: socket.getpeername() 610 611 Return the remote address to which the socket is connected. This is useful to 612 find out the port number of a remote IPv4/v6 socket, for instance. (The format 613 of the address returned depends on the address family --- see above.) On some 614 systems this function is not supported. 615 616 617.. method:: socket.getsockname() 618 619 Return the socket's own address. This is useful to find out the port number of 620 an IPv4/v6 socket, for instance. (The format of the address returned depends on 621 the address family --- see above.) 622 623 624.. method:: socket.getsockopt(level, optname[, buflen]) 625 626 Return the value of the given socket option (see the Unix man page 627 :manpage:`getsockopt(2)`). The needed symbolic constants (:const:`SO_\*` etc.) 628 are defined in this module. If *buflen* is absent, an integer option is assumed 629 and its integer value is returned by the function. If *buflen* is present, it 630 specifies the maximum length of the buffer used to receive the option in, and 631 this buffer is returned as a string. It is up to the caller to decode the 632 contents of the buffer (see the optional built-in module :mod:`struct` for a way 633 to decode C structures encoded as strings). 634 635 636.. method:: socket.ioctl(control, option) 637 638 :platform: Windows 639 640 The :meth:`ioctl` method is a limited interface to the WSAIoctl system 641 interface. Please refer to the `Win32 documentation 642 <http://msdn.microsoft.com/en-us/library/ms741621%28VS.85%29.aspx>`_ for more 643 information. 644 645 On other platforms, the generic :func:`fcntl.fcntl` and :func:`fcntl.ioctl` 646 functions may be used; they accept a socket object as their first argument. 647 648 .. versionadded:: 2.6 649 650 651.. method:: socket.listen(backlog) 652 653 Listen for connections made to the socket. The *backlog* argument specifies the 654 maximum number of queued connections and should be at least 0; the maximum value 655 is system-dependent (usually 5), the minimum value is forced to 0. 656 657 658.. method:: socket.makefile([mode[, bufsize]]) 659 660 .. index:: single: I/O control; buffering 661 662 Return a :dfn:`file object` associated with the socket. (File objects are 663 described in :ref:`bltin-file-objects`.) The file object 664 references a :c:func:`dup`\ ped version of the socket file descriptor, so the 665 file object and socket object may be closed or garbage-collected independently. 666 The socket must be in blocking mode (it can not have a timeout). The optional 667 *mode* and *bufsize* arguments are interpreted the same way as by the built-in 668 :func:`file` function. 669 670 .. note:: 671 672 On Windows, the file-like object created by :meth:`makefile` cannot be 673 used where a file object with a file descriptor is expected, such as the 674 stream arguments of :meth:`subprocess.Popen`. 675 676 677.. method:: socket.recv(bufsize[, flags]) 678 679 Receive data from the socket. The return value is a string representing the 680 data received. The maximum amount of data to be received at once is specified 681 by *bufsize*. See the Unix manual page :manpage:`recv(2)` for the meaning of 682 the optional argument *flags*; it defaults to zero. 683 684 .. note:: 685 686 For best match with hardware and network realities, the value of *bufsize* 687 should be a relatively small power of 2, for example, 4096. 688 689 690.. method:: socket.recvfrom(bufsize[, flags]) 691 692 Receive data from the socket. The return value is a pair ``(string, address)`` 693 where *string* is a string representing the data received and *address* is the 694 address of the socket sending the data. See the Unix manual page 695 :manpage:`recv(2)` for the meaning of the optional argument *flags*; it defaults 696 to zero. (The format of *address* depends on the address family --- see above.) 697 698 699.. method:: socket.recvfrom_into(buffer[, nbytes[, flags]]) 700 701 Receive data from the socket, writing it into *buffer* instead of creating a 702 new string. The return value is a pair ``(nbytes, address)`` where *nbytes* is 703 the number of bytes received and *address* is the address of the socket sending 704 the data. See the Unix manual page :manpage:`recv(2)` for the meaning of the 705 optional argument *flags*; it defaults to zero. (The format of *address* 706 depends on the address family --- see above.) 707 708 .. versionadded:: 2.5 709 710 711.. method:: socket.recv_into(buffer[, nbytes[, flags]]) 712 713 Receive up to *nbytes* bytes from the socket, storing the data into a buffer 714 rather than creating a new string. If *nbytes* is not specified (or 0), 715 receive up to the size available in the given buffer. Returns the number of 716 bytes received. See the Unix manual page :manpage:`recv(2)` for the meaning 717 of the optional argument *flags*; it defaults to zero. 718 719 .. versionadded:: 2.5 720 721 722.. method:: socket.send(string[, flags]) 723 724 Send data to the socket. The socket must be connected to a remote socket. The 725 optional *flags* argument has the same meaning as for :meth:`recv` above. 726 Returns the number of bytes sent. Applications are responsible for checking that 727 all data has been sent; if only some of the data was transmitted, the 728 application needs to attempt delivery of the remaining data. 729 730 731.. method:: socket.sendall(string[, flags]) 732 733 Send data to the socket. The socket must be connected to a remote socket. The 734 optional *flags* argument has the same meaning as for :meth:`recv` above. 735 Unlike :meth:`send`, this method continues to send data from *string* until 736 either all data has been sent or an error occurs. ``None`` is returned on 737 success. On error, an exception is raised, and there is no way to determine how 738 much data, if any, was successfully sent. 739 740 741.. method:: socket.sendto(string[, flags], address) 742 743 Send data to the socket. The socket should not be connected to a remote socket, 744 since the destination socket is specified by *address*. The optional *flags* 745 argument has the same meaning as for :meth:`recv` above. Return the number of 746 bytes sent. (The format of *address* depends on the address family --- see 747 above.) 748 749 750.. method:: socket.setblocking(flag) 751 752 Set blocking or non-blocking mode of the socket: if *flag* is 0, the socket is 753 set to non-blocking, else to blocking mode. Initially all sockets are in 754 blocking mode. In non-blocking mode, if a :meth:`recv` call doesn't find any 755 data, or if a :meth:`send` call can't immediately dispose of the data, a 756 :exc:`error` exception is raised; in blocking mode, the calls block until they 757 can proceed. ``s.setblocking(0)`` is equivalent to ``s.settimeout(0.0)``; 758 ``s.setblocking(1)`` is equivalent to ``s.settimeout(None)``. 759 760 761.. method:: socket.settimeout(value) 762 763 Set a timeout on blocking socket operations. The *value* argument can be a 764 nonnegative float expressing seconds, or ``None``. If a float is given, 765 subsequent socket operations will raise a :exc:`timeout` exception if the 766 timeout period *value* has elapsed before the operation has completed. Setting 767 a timeout of ``None`` disables timeouts on socket operations. 768 ``s.settimeout(0.0)`` is equivalent to ``s.setblocking(0)``; 769 ``s.settimeout(None)`` is equivalent to ``s.setblocking(1)``. 770 771 .. versionadded:: 2.3 772 773 774.. method:: socket.gettimeout() 775 776 Return the timeout in seconds (float) associated with socket operations, or 777 ``None`` if no timeout is set. This reflects the last call to 778 :meth:`setblocking` or :meth:`settimeout`. 779 780 .. versionadded:: 2.3 781 782Some notes on socket blocking and timeouts: A socket object can be in one of 783three modes: blocking, non-blocking, or timeout. Sockets are always created in 784blocking mode. In blocking mode, operations block until complete or 785the system returns an error (such as connection timed out). In 786non-blocking mode, operations fail (with an error that is unfortunately 787system-dependent) if they cannot be completed immediately. In timeout mode, 788operations fail if they cannot be completed within the timeout specified for the 789socket or if the system returns an error. The :meth:`~socket.setblocking` 790method is simply a shorthand for certain :meth:`~socket.settimeout` calls. 791 792Timeout mode internally sets the socket in non-blocking mode. The blocking and 793timeout modes are shared between file descriptors and socket objects that refer 794to the same network endpoint. A consequence of this is that file objects 795returned by the :meth:`~socket.makefile` method must only be used when the 796socket is in blocking mode; in timeout or non-blocking mode file operations 797that cannot be completed immediately will fail. 798 799Note that the :meth:`~socket.connect` operation is subject to the timeout 800setting, and in general it is recommended to call :meth:`~socket.settimeout` 801before calling :meth:`~socket.connect` or pass a timeout parameter to 802:meth:`create_connection`. The system network stack may return a connection 803timeout error of its own regardless of any Python socket timeout setting. 804 805 806.. method:: socket.setsockopt(level, optname, value) 807 808 .. index:: module: struct 809 810 Set the value of the given socket option (see the Unix manual page 811 :manpage:`setsockopt(2)`). The needed symbolic constants are defined in the 812 :mod:`socket` module (:const:`SO_\*` etc.). The value can be an integer or a 813 string representing a buffer. In the latter case it is up to the caller to 814 ensure that the string contains the proper bits (see the optional built-in 815 module :mod:`struct` for a way to encode C structures as strings). 816 817 818.. method:: socket.shutdown(how) 819 820 Shut down one or both halves of the connection. If *how* is :const:`SHUT_RD`, 821 further receives are disallowed. If *how* is :const:`SHUT_WR`, further sends 822 are disallowed. If *how* is :const:`SHUT_RDWR`, further sends and receives are 823 disallowed. Depending on the platform, shutting down one half of the connection 824 can also close the opposite half (e.g. on Mac OS X, ``shutdown(SHUT_WR)`` does 825 not allow further reads on the other end of the connection). 826 827Note that there are no methods :meth:`read` or :meth:`write`; use 828:meth:`~socket.recv` and :meth:`~socket.send` without *flags* argument instead. 829 830Socket objects also have these (read-only) attributes that correspond to the 831values given to the :class:`socket` constructor. 832 833 834.. attribute:: socket.family 835 836 The socket family. 837 838 .. versionadded:: 2.5 839 840 841.. attribute:: socket.type 842 843 The socket type. 844 845 .. versionadded:: 2.5 846 847 848.. attribute:: socket.proto 849 850 The socket protocol. 851 852 .. versionadded:: 2.5 853 854 855.. _socket-example: 856 857Example 858------- 859 860Here are four minimal example programs using the TCP/IP protocol: a server that 861echoes all data that it receives back (servicing only one client), and a client 862using it. Note that a server must perform the sequence :func:`socket`, 863:meth:`~socket.bind`, :meth:`~socket.listen`, :meth:`~socket.accept` (possibly 864repeating the :meth:`~socket.accept` to service more than one client), while a 865client only needs the sequence :func:`socket`, :meth:`~socket.connect`. Also 866note that the server does not :meth:`~socket.send`/:meth:`~socket.recv` on the 867socket it is listening on but on the new socket returned by 868:meth:`~socket.accept`. 869 870The first two examples support IPv4 only. :: 871 872 # Echo server program 873 import socket 874 875 HOST = '' # Symbolic name meaning all available interfaces 876 PORT = 50007 # Arbitrary non-privileged port 877 s = socket.socket(socket.AF_INET, socket.SOCK_STREAM) 878 s.bind((HOST, PORT)) 879 s.listen(1) 880 conn, addr = s.accept() 881 print 'Connected by', addr 882 while 1: 883 data = conn.recv(1024) 884 if not data: break 885 conn.send(data) 886 conn.close() 887 888:: 889 890 # Echo client program 891 import socket 892 893 HOST = 'daring.cwi.nl' # The remote host 894 PORT = 50007 # The same port as used by the server 895 s = socket.socket(socket.AF_INET, socket.SOCK_STREAM) 896 s.connect((HOST, PORT)) 897 s.send('Hello, world') 898 data = s.recv(1024) 899 s.close() 900 print 'Received', repr(data) 901 902The next two examples are identical to the above two, but support both IPv4 and 903IPv6. The server side will listen to the first address family available (it 904should listen to both instead). On most of IPv6-ready systems, IPv6 will take 905precedence and the server may not accept IPv4 traffic. The client side will try 906to connect to the all addresses returned as a result of the name resolution, and 907sends traffic to the first one connected successfully. :: 908 909 # Echo server program 910 import socket 911 import sys 912 913 HOST = None # Symbolic name meaning all available interfaces 914 PORT = 50007 # Arbitrary non-privileged port 915 s = None 916 for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, 917 socket.SOCK_STREAM, 0, socket.AI_PASSIVE): 918 af, socktype, proto, canonname, sa = res 919 try: 920 s = socket.socket(af, socktype, proto) 921 except socket.error, msg: 922 s = None 923 continue 924 try: 925 s.bind(sa) 926 s.listen(1) 927 except socket.error, msg: 928 s.close() 929 s = None 930 continue 931 break 932 if s is None: 933 print 'could not open socket' 934 sys.exit(1) 935 conn, addr = s.accept() 936 print 'Connected by', addr 937 while 1: 938 data = conn.recv(1024) 939 if not data: break 940 conn.send(data) 941 conn.close() 942 943:: 944 945 # Echo client program 946 import socket 947 import sys 948 949 HOST = 'daring.cwi.nl' # The remote host 950 PORT = 50007 # The same port as used by the server 951 s = None 952 for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, socket.SOCK_STREAM): 953 af, socktype, proto, canonname, sa = res 954 try: 955 s = socket.socket(af, socktype, proto) 956 except socket.error, msg: 957 s = None 958 continue 959 try: 960 s.connect(sa) 961 except socket.error, msg: 962 s.close() 963 s = None 964 continue 965 break 966 if s is None: 967 print 'could not open socket' 968 sys.exit(1) 969 s.send('Hello, world') 970 data = s.recv(1024) 971 s.close() 972 print 'Received', repr(data) 973 974 975The last example shows how to write a very simple network sniffer with raw 976sockets on Windows. The example requires administrator privileges to modify 977the interface:: 978 979 import socket 980 981 # the public network interface 982 HOST = socket.gethostbyname(socket.gethostname()) 983 984 # create a raw socket and bind it to the public interface 985 s = socket.socket(socket.AF_INET, socket.SOCK_RAW, socket.IPPROTO_IP) 986 s.bind((HOST, 0)) 987 988 # Include IP headers 989 s.setsockopt(socket.IPPROTO_IP, socket.IP_HDRINCL, 1) 990 991 # receive all packages 992 s.ioctl(socket.SIO_RCVALL, socket.RCVALL_ON) 993 994 # receive a package 995 print s.recvfrom(65565) 996 997 # disabled promiscuous mode 998 s.ioctl(socket.SIO_RCVALL, socket.RCVALL_OFF) 999 1000 1001Running an example several times with too small delay between executions, could 1002lead to this error:: 1003 1004 socket.error: [Errno 98] Address already in use 1005 1006This is because the previous execution has left the socket in a ``TIME_WAIT`` 1007state, and can't be immediately reused. 1008 1009There is a :mod:`socket` flag to set, in order to prevent this, 1010:data:`socket.SO_REUSEADDR`:: 1011 1012 s = socket.socket(socket.AF_INET, socket.SOCK_STREAM) 1013 s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1) 1014 s.bind((HOST, PORT)) 1015 1016the :data:`SO_REUSEADDR` flag tells the kernel to reuse a local socket in 1017``TIME_WAIT`` state, without waiting for its natural timeout to expire.