PageRenderTime 47ms CodeModel.GetById 2ms app.highlight 33ms RepoModel.GetById 1ms app.codeStats 1ms

/Doc/library/socket.rst

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