PageRenderTime 75ms CodeModel.GetById 3ms app.highlight 61ms RepoModel.GetById 1ms app.codeStats 1ms

/Doc/library/socket.rst

https://bitbucket.org/atsuoishimoto/cpython
ReStructuredText | 1515 lines | 1053 code | 462 blank | 0 comment | 0 complexity | 9380a42050c970265eb5cada479fb2c2 MD5 | raw file

Large files files are truncated, but you can click here to view the full 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
  43The address format required by a particular socket object is automatically
  44selected based on the address family specified when the socket object was
  45created.  Socket addresses are represented as follows:
  46
  47- The address of an :const:`AF_UNIX` socket bound to a file system node
  48  is represented as a string, using the file system encoding and the
  49  ``'surrogateescape'`` error handler (see :pep:`383`).  An address in
  50  Linux's abstract namespace is returned as a :class:`bytes` object with
  51  an initial null byte; note that sockets in this namespace can
  52  communicate with normal file system sockets, so programs intended to
  53  run on Linux may need to deal with both types of address.  A string or
  54  :class:`bytes` object can be used for either type of address when
  55  passing it as an argument.
  56
  57   .. versionchanged:: 3.3
  58      Previously, :const:`AF_UNIX` socket paths were assumed to use UTF-8
  59      encoding.
  60
  61- A pair ``(host, port)`` is used for the :const:`AF_INET` address family,
  62  where *host* is a string representing either a hostname in Internet domain
  63  notation like ``'daring.cwi.nl'`` or an IPv4 address like ``'100.50.200.5'``,
  64  and *port* is an integer.
  65
  66- For :const:`AF_INET6` address family, a four-tuple ``(host, port, flowinfo,
  67  scopeid)`` is used, where *flowinfo* and *scopeid* represent the ``sin6_flowinfo``
  68  and ``sin6_scope_id`` members in :const:`struct sockaddr_in6` in C.  For
  69  :mod:`socket` module methods, *flowinfo* and *scopeid* can be omitted just for
  70  backward compatibility.  Note, however, omission of *scopeid* can cause problems
  71  in manipulating scoped IPv6 addresses.
  72
  73- :const:`AF_NETLINK` sockets are represented as pairs ``(pid, groups)``.
  74
  75- Linux-only support for TIPC is available using the :const:`AF_TIPC`
  76  address family.  TIPC is an open, non-IP based networked protocol designed
  77  for use in clustered computer environments.  Addresses are represented by a
  78  tuple, and the fields depend on the address type. The general tuple form is
  79  ``(addr_type, v1, v2, v3 [, scope])``, where:
  80
  81  - *addr_type* is one of :const:`TIPC_ADDR_NAMESEQ`, :const:`TIPC_ADDR_NAME`,
  82    or :const:`TIPC_ADDR_ID`.
  83  - *scope* is one of :const:`TIPC_ZONE_SCOPE`, :const:`TIPC_CLUSTER_SCOPE`, and
  84    :const:`TIPC_NODE_SCOPE`.
  85  - If *addr_type* is :const:`TIPC_ADDR_NAME`, then *v1* is the server type, *v2* is
  86    the port identifier, and *v3* should be 0.
  87
  88    If *addr_type* is :const:`TIPC_ADDR_NAMESEQ`, then *v1* is the server type, *v2*
  89    is the lower port number, and *v3* is the upper port number.
  90
  91    If *addr_type* is :const:`TIPC_ADDR_ID`, then *v1* is the node, *v2* is the
  92    reference, and *v3* should be set to 0.
  93
  94    If *addr_type* is :const:`TIPC_ADDR_ID`, then *v1* is the node, *v2* is the
  95    reference, and *v3* should be set to 0.
  96
  97- A tuple ``(interface, )`` is used for the :const:`AF_CAN` address family,
  98  where *interface* is a string representing a network interface name like
  99  ``'can0'``. The network interface name ``''`` can be used to receive packets
 100  from all network interfaces of this family.
 101
 102- A string or a tuple ``(id, unit)`` is used for the :const:`SYSPROTO_CONTROL`
 103  protocol of the :const:`PF_SYSTEM` family. The string is the name of a
 104  kernel control using a dynamically-assigned ID. The tuple can be used if ID
 105  and unit number of the kernel control are known or if a registered ID is
 106  used.
 107
 108  .. versionadded:: 3.3
 109
 110- Certain other address families (:const:`AF_BLUETOOTH`, :const:`AF_PACKET`,
 111  :const:`AF_CAN`) support specific representations.
 112
 113  .. XXX document them!
 114
 115For IPv4 addresses, two special forms are accepted instead of a host address:
 116the empty string represents :const:`INADDR_ANY`, and the string
 117``'<broadcast>'`` represents :const:`INADDR_BROADCAST`.  This behavior is not
 118compatible with IPv6, therefore, you may want to avoid these if you intend
 119to support IPv6 with your Python programs.
 120
 121If you use a hostname in the *host* portion of IPv4/v6 socket address, the
 122program may show a nondeterministic behavior, as Python uses the first address
 123returned from the DNS resolution.  The socket address will be resolved
 124differently into an actual IPv4/v6 address, depending on the results from DNS
 125resolution and/or the host configuration.  For deterministic behavior use a
 126numeric address in *host* portion.
 127
 128All errors raise exceptions.  The normal exceptions for invalid argument types
 129and out-of-memory conditions can be raised; starting from Python 3.3, errors
 130related to socket or address semantics raise :exc:`OSError` or one of its
 131subclasses (they used to raise :exc:`socket.error`).
 132
 133Non-blocking mode is supported through :meth:`~socket.setblocking`.  A
 134generalization of this based on timeouts is supported through
 135:meth:`~socket.settimeout`.
 136
 137
 138Module contents
 139---------------
 140
 141The module :mod:`socket` exports the following elements.
 142
 143
 144Exceptions
 145^^^^^^^^^^
 146
 147.. exception:: error
 148
 149   A deprecated alias of :exc:`OSError`.
 150
 151   .. versionchanged:: 3.3
 152      Following :pep:`3151`, this class was made an alias of :exc:`OSError`.
 153
 154
 155.. exception:: herror
 156
 157   A subclass of :exc:`OSError`, this exception is raised for
 158   address-related errors, i.e. for functions that use *h_errno* in the POSIX
 159   C API, including :func:`gethostbyname_ex` and :func:`gethostbyaddr`.
 160   The accompanying value is a pair ``(h_errno, string)`` representing an
 161   error returned by a library call.  *h_errno* is a numeric value, while
 162   *string* represents the description of *h_errno*, as returned by the
 163   :c:func:`hstrerror` C function.
 164
 165   .. versionchanged:: 3.3
 166      This class was made a subclass of :exc:`OSError`.
 167
 168.. exception:: gaierror
 169
 170   A subclass of :exc:`OSError`, this exception is raised for
 171   address-related errors by :func:`getaddrinfo` and :func:`getnameinfo`.
 172   The accompanying value is a pair ``(error, string)`` representing an error
 173   returned by a library call.  *string* represents the description of
 174   *error*, as returned by the :c:func:`gai_strerror` C function.  The
 175   numeric *error* value will match one of the :const:`EAI_\*` constants
 176   defined in this module.
 177
 178   .. versionchanged:: 3.3
 179      This class was made a subclass of :exc:`OSError`.
 180
 181.. exception:: timeout
 182
 183   A subclass of :exc:`OSError`, this exception is raised when a timeout
 184   occurs on a socket which has had timeouts enabled via a prior call to
 185   :meth:`~socket.settimeout` (or implicitly through
 186   :func:`~socket.setdefaulttimeout`).  The accompanying value is a string
 187   whose value is currently always "timed out".
 188
 189   .. versionchanged:: 3.3
 190      This class was made a subclass of :exc:`OSError`.
 191
 192
 193Constants
 194^^^^^^^^^
 195
 196.. data:: AF_UNIX
 197          AF_INET
 198          AF_INET6
 199
 200   These constants represent the address (and protocol) families, used for the
 201   first argument to :func:`.socket`.  If the :const:`AF_UNIX` constant is not
 202   defined then this protocol is unsupported.  More constants may be available
 203   depending on the system.
 204
 205
 206.. data:: SOCK_STREAM
 207          SOCK_DGRAM
 208          SOCK_RAW
 209          SOCK_RDM
 210          SOCK_SEQPACKET
 211
 212   These constants represent the socket types, used for the second argument to
 213   :func:`.socket`.  More constants may be available depending on the system.
 214   (Only :const:`SOCK_STREAM` and :const:`SOCK_DGRAM` appear to be generally
 215   useful.)
 216
 217.. data:: SOCK_CLOEXEC
 218          SOCK_NONBLOCK
 219
 220   These two constants, if defined, can be combined with the socket types and
 221   allow you to set some flags atomically (thus avoiding possible race
 222   conditions and the need for separate calls).
 223
 224   .. seealso::
 225
 226      `Secure File Descriptor Handling <http://udrepper.livejournal.com/20407.html>`_
 227      for a more thorough explanation.
 228
 229   Availability: Linux >= 2.6.27.
 230
 231   .. versionadded:: 3.2
 232
 233.. data:: SO_*
 234          SOMAXCONN
 235          MSG_*
 236          SOL_*
 237          SCM_*
 238          IPPROTO_*
 239          IPPORT_*
 240          INADDR_*
 241          IP_*
 242          IPV6_*
 243          EAI_*
 244          AI_*
 245          NI_*
 246          TCP_*
 247
 248   Many constants of these forms, documented in the Unix documentation on sockets
 249   and/or the IP protocol, are also defined in the socket module. They are
 250   generally used in arguments to the :meth:`setsockopt` and :meth:`getsockopt`
 251   methods of socket objects.  In most cases, only those symbols that are defined
 252   in the Unix header files are defined; for a few symbols, default values are
 253   provided.
 254
 255.. data:: AF_CAN
 256          PF_CAN
 257          SOL_CAN_*
 258          CAN_*
 259
 260   Many constants of these forms, documented in the Linux documentation, are
 261   also defined in the socket module.
 262
 263   Availability: Linux >= 2.6.25.
 264
 265   .. versionadded:: 3.3
 266
 267.. data:: CAN_BCM
 268          CAN_BCM_*
 269
 270   CAN_BCM, in the CAN protocol family, is the broadcast manager (BCM) protocol.
 271   Broadcast manager constants, documented in the Linux documentation, are also
 272   defined in the socket module.
 273
 274   Availability: Linux >= 2.6.25.
 275
 276   .. versionadded:: 3.4
 277
 278.. data:: AF_RDS
 279          PF_RDS
 280          SOL_RDS
 281          RDS_*
 282
 283   Many constants of these forms, documented in the Linux documentation, are
 284   also defined in the socket module.
 285
 286   Availability: Linux >= 2.6.30.
 287
 288   .. versionadded:: 3.3
 289
 290
 291.. data:: SIO_*
 292          RCVALL_*
 293
 294   Constants for Windows' WSAIoctl(). The constants are used as arguments to the
 295   :meth:`~socket.socket.ioctl` method of socket objects.
 296
 297
 298.. data:: TIPC_*
 299
 300   TIPC related constants, matching the ones exported by the C socket API. See
 301   the TIPC documentation for more information.
 302
 303.. data:: AF_LINK
 304
 305  Availability: BSD, OSX.
 306
 307  .. versionadded:: 3.4
 308
 309.. data:: has_ipv6
 310
 311   This constant contains a boolean value which indicates if IPv6 is supported on
 312   this platform.
 313
 314
 315Functions
 316^^^^^^^^^
 317
 318Creating sockets
 319''''''''''''''''
 320
 321The following functions all create :ref:`socket objects <socket-objects>`.
 322
 323
 324.. function:: socket(family=AF_INET, type=SOCK_STREAM, proto=0, fileno=None)
 325
 326   Create a new socket using the given address family, socket type and protocol
 327   number.  The address family should be :const:`AF_INET` (the default),
 328   :const:`AF_INET6`, :const:`AF_UNIX`, :const:`AF_CAN` or :const:`AF_RDS`. The
 329   socket type should be :const:`SOCK_STREAM` (the default),
 330   :const:`SOCK_DGRAM`, :const:`SOCK_RAW` or perhaps one of the other ``SOCK_``
 331   constants. The protocol number is usually zero and may be omitted or in the
 332   case where the address family is :const:`AF_CAN` the protocol should be one
 333   of :const:`CAN_RAW` or :const:`CAN_BCM`.
 334
 335   The newly created socket is :ref:`non-inheritable <fd_inheritance>`.
 336
 337   .. versionchanged:: 3.3
 338      The AF_CAN family was added.
 339      The AF_RDS family was added.
 340
 341   .. versionchanged:: 3.4
 342       The CAN_BCM protocol was added.
 343
 344   .. versionchanged:: 3.4
 345      The returned socket is now non-inheritable.
 346
 347
 348.. function:: socketpair([family[, type[, proto]]])
 349
 350   Build a pair of connected socket objects using the given address family, socket
 351   type, and protocol number.  Address family, socket type, and protocol number are
 352   as for the :func:`.socket` function above. The default family is :const:`AF_UNIX`
 353   if defined on the platform; otherwise, the default is :const:`AF_INET`.
 354   Availability: Unix.
 355
 356   The newly created sockets are :ref:`non-inheritable <fd_inheritance>`.
 357
 358   .. versionchanged:: 3.2
 359      The returned socket objects now support the whole socket API, rather
 360      than a subset.
 361
 362   .. versionchanged:: 3.4
 363      The returned sockets are now non-inheritable.
 364
 365
 366.. function:: create_connection(address[, timeout[, source_address]])
 367
 368   Connect to a TCP service listening on the Internet *address* (a 2-tuple
 369   ``(host, port)``), and return the socket object.  This is a higher-level
 370   function than :meth:`socket.connect`: if *host* is a non-numeric hostname,
 371   it will try to resolve it for both :data:`AF_INET` and :data:`AF_INET6`,
 372   and then try to connect to all possible addresses in turn until a
 373   connection succeeds.  This makes it easy to write clients that are
 374   compatible to both IPv4 and IPv6.
 375
 376   Passing the optional *timeout* parameter will set the timeout on the
 377   socket instance before attempting to connect.  If no *timeout* is
 378   supplied, the global default timeout setting returned by
 379   :func:`getdefaulttimeout` is used.
 380
 381   If supplied, *source_address* must be a 2-tuple ``(host, port)`` for the
 382   socket to bind to as its source address before connecting.  If host or port
 383   are '' or 0 respectively the OS default behavior will be used.
 384
 385   .. versionchanged:: 3.2
 386      *source_address* was added.
 387
 388   .. versionchanged:: 3.2
 389      support for the :keyword:`with` statement was added.
 390
 391
 392.. function:: fromfd(fd, family, type, proto=0)
 393
 394   Duplicate the file descriptor *fd* (an integer as returned by a file object's
 395   :meth:`fileno` method) and build a socket object from the result.  Address
 396   family, socket type and protocol number are as for the :func:`.socket` function
 397   above. The file descriptor should refer to a socket, but this is not checked ---
 398   subsequent operations on the object may fail if the file descriptor is invalid.
 399   This function is rarely needed, but can be used to get or set socket options on
 400   a socket passed to a program as standard input or output (such as a server
 401   started by the Unix inet daemon).  The socket is assumed to be in blocking mode.
 402
 403   The newly created socket is :ref:`non-inheritable <fd_inheritance>`.
 404
 405   .. versionchanged:: 3.4
 406      The returned socket is now non-inheritable.
 407
 408
 409.. function:: fromshare(data)
 410
 411   Instantiate a socket from data obtained from the :meth:`socket.share`
 412   method.  The socket is assumed to be in blocking mode.
 413
 414   Availability: Windows.
 415
 416   .. versionadded:: 3.3
 417
 418
 419.. data:: SocketType
 420
 421   This is a Python type object that represents the socket object type. It is the
 422   same as ``type(socket(...))``.
 423
 424
 425Other functions
 426'''''''''''''''
 427
 428The :mod:`socket` module also offers various network-related services:
 429
 430
 431.. function:: getaddrinfo(host, port, family=0, type=0, proto=0, flags=0)
 432
 433   Translate the *host*/*port* argument into a sequence of 5-tuples that contain
 434   all the necessary arguments for creating a socket connected to that service.
 435   *host* is a domain name, a string representation of an IPv4/v6 address
 436   or ``None``. *port* is a string service name such as ``'http'``, a numeric
 437   port number or ``None``.  By passing ``None`` as the value of *host*
 438   and *port*, you can pass ``NULL`` to the underlying C API.
 439
 440   The *family*, *type* and *proto* arguments can be optionally specified
 441   in order to narrow the list of addresses returned.  Passing zero as a
 442   value for each of these arguments selects the full range of results.
 443   The *flags* argument can be one or several of the ``AI_*`` constants,
 444   and will influence how results are computed and returned.
 445   For example, :const:`AI_NUMERICHOST` will disable domain name resolution
 446   and will raise an error if *host* is a domain name.
 447
 448   The function returns a list of 5-tuples with the following structure:
 449
 450   ``(family, type, proto, canonname, sockaddr)``
 451
 452   In these tuples, *family*, *type*, *proto* are all integers and are
 453   meant to be passed to the :func:`.socket` function.  *canonname* will be
 454   a string representing the canonical name of the *host* if
 455   :const:`AI_CANONNAME` is part of the *flags* argument; else *canonname*
 456   will be empty.  *sockaddr* is a tuple describing a socket address, whose
 457   format depends on the returned *family* (a ``(address, port)`` 2-tuple for
 458   :const:`AF_INET`, a ``(address, port, flow info, scope id)`` 4-tuple for
 459   :const:`AF_INET6`), and is meant to be passed to the :meth:`socket.connect`
 460   method.
 461
 462   The following example fetches address information for a hypothetical TCP
 463   connection to ``www.python.org`` on port 80 (results may differ on your
 464   system if IPv6 isn't enabled)::
 465
 466      >>> socket.getaddrinfo("www.python.org", 80, proto=socket.SOL_TCP)
 467      [(2, 1, 6, '', ('82.94.164.162', 80)),
 468       (10, 1, 6, '', ('2001:888:2000:d::a2', 80, 0, 0))]
 469
 470   .. versionchanged:: 3.2
 471      parameters can now be passed as single keyword arguments.
 472
 473.. function:: getfqdn([name])
 474
 475   Return a fully qualified domain name for *name*. If *name* is omitted or empty,
 476   it is interpreted as the local host.  To find the fully qualified name, the
 477   hostname returned by :func:`gethostbyaddr` is checked, followed by aliases for the
 478   host, if available.  The first name which includes a period is selected.  In
 479   case no fully qualified domain name is available, the hostname as returned by
 480   :func:`gethostname` is returned.
 481
 482
 483.. function:: gethostbyname(hostname)
 484
 485   Translate a host name to IPv4 address format.  The IPv4 address is returned as a
 486   string, such as  ``'100.50.200.5'``.  If the host name is an IPv4 address itself
 487   it is returned unchanged.  See :func:`gethostbyname_ex` for a more complete
 488   interface. :func:`gethostbyname` does not support IPv6 name resolution, and
 489   :func:`getaddrinfo` should be used instead for IPv4/v6 dual stack support.
 490
 491
 492.. function:: gethostbyname_ex(hostname)
 493
 494   Translate a host name to IPv4 address format, extended interface. Return a
 495   triple ``(hostname, aliaslist, ipaddrlist)`` where *hostname* is the primary
 496   host name responding to the given *ip_address*, *aliaslist* is a (possibly
 497   empty) list of alternative host names for the same address, and *ipaddrlist* is
 498   a list of IPv4 addresses for the same interface on the same host (often but not
 499   always a single address). :func:`gethostbyname_ex` does not support IPv6 name
 500   resolution, and :func:`getaddrinfo` should be used instead for IPv4/v6 dual
 501   stack support.
 502
 503
 504.. function:: gethostname()
 505
 506   Return a string containing the hostname of the machine where  the Python
 507   interpreter is currently executing.
 508
 509   If you want to know the current machine's IP address, you may want to use
 510   ``gethostbyname(gethostname())``. This operation assumes that there is a
 511   valid address-to-host mapping for the host, and the assumption does not
 512   always hold.
 513
 514   Note: :func:`gethostname` doesn't always return the fully qualified domain
 515   name; use ``getfqdn()`` (see above).
 516
 517
 518.. function:: gethostbyaddr(ip_address)
 519
 520   Return a triple ``(hostname, aliaslist, ipaddrlist)`` where *hostname* is the
 521   primary host name responding to the given *ip_address*, *aliaslist* is a
 522   (possibly empty) list of alternative host names for the same address, and
 523   *ipaddrlist* is a list of IPv4/v6 addresses for the same interface on the same
 524   host (most likely containing only a single address). To find the fully qualified
 525   domain name, use the function :func:`getfqdn`. :func:`gethostbyaddr` supports
 526   both IPv4 and IPv6.
 527
 528
 529.. function:: getnameinfo(sockaddr, flags)
 530
 531   Translate a socket address *sockaddr* into a 2-tuple ``(host, port)``. Depending
 532   on the settings of *flags*, the result can contain a fully-qualified domain name
 533   or numeric address representation in *host*.  Similarly, *port* can contain a
 534   string port name or a numeric port number.
 535
 536
 537.. function:: getprotobyname(protocolname)
 538
 539   Translate an Internet protocol name (for example, ``'icmp'``) to a constant
 540   suitable for passing as the (optional) third argument to the :func:`.socket`
 541   function.  This is usually only needed for sockets opened in "raw" mode
 542   (:const:`SOCK_RAW`); for the normal socket modes, the correct protocol is chosen
 543   automatically if the protocol is omitted or zero.
 544
 545
 546.. function:: getservbyname(servicename[, protocolname])
 547
 548   Translate an Internet service name and protocol name to a port number for that
 549   service.  The optional protocol name, if given, should be ``'tcp'`` or
 550   ``'udp'``, otherwise any protocol will match.
 551
 552
 553.. function:: getservbyport(port[, protocolname])
 554
 555   Translate an Internet port number and protocol name to a service name for that
 556   service.  The optional protocol name, if given, should be ``'tcp'`` or
 557   ``'udp'``, otherwise any protocol will match.
 558
 559
 560.. function:: ntohl(x)
 561
 562   Convert 32-bit positive integers from network to host byte order.  On machines
 563   where the host byte order is the same as network byte order, this is a no-op;
 564   otherwise, it performs a 4-byte swap operation.
 565
 566
 567.. function:: ntohs(x)
 568
 569   Convert 16-bit positive integers from network to host byte order.  On machines
 570   where the host byte order is the same as network byte order, this is a no-op;
 571   otherwise, it performs a 2-byte swap operation.
 572
 573
 574.. function:: htonl(x)
 575
 576   Convert 32-bit positive integers from host to network byte order.  On machines
 577   where the host byte order is the same as network byte order, this is a no-op;
 578   otherwise, it performs a 4-byte swap operation.
 579
 580
 581.. function:: htons(x)
 582
 583   Convert 16-bit positive integers from host to network byte order.  On machines
 584   where the host byte order is the same as network byte order, this is a no-op;
 585   otherwise, it performs a 2-byte swap operation.
 586
 587
 588.. function:: inet_aton(ip_string)
 589
 590   Convert an IPv4 address from dotted-quad string format (for example,
 591   '123.45.67.89') to 32-bit packed binary format, as a bytes object four characters in
 592   length.  This is useful when conversing with a program that uses the standard C
 593   library and needs objects of type :c:type:`struct in_addr`, which is the C type
 594   for the 32-bit packed binary this function returns.
 595
 596   :func:`inet_aton` also accepts strings with less than three dots; see the
 597   Unix manual page :manpage:`inet(3)` for details.
 598
 599   If the IPv4 address string passed to this function is invalid,
 600   :exc:`OSError` will be raised. Note that exactly what is valid depends on
 601   the underlying C implementation of :c:func:`inet_aton`.
 602
 603   :func:`inet_aton` does not support IPv6, and :func:`inet_pton` should be used
 604   instead for IPv4/v6 dual stack support.
 605
 606
 607.. function:: inet_ntoa(packed_ip)
 608
 609   Convert a 32-bit packed IPv4 address (a bytes object four characters in
 610   length) to its standard dotted-quad string representation (for example,
 611   '123.45.67.89').  This is useful when conversing with a program that uses the
 612   standard C library and needs objects of type :c:type:`struct in_addr`, which
 613   is the C type for the 32-bit packed binary data this function takes as an
 614   argument.
 615
 616   If the byte sequence passed to this function is not exactly 4 bytes in
 617   length, :exc:`OSError` will be raised. :func:`inet_ntoa` does not
 618   support IPv6, and :func:`inet_ntop` should be used instead for IPv4/v6 dual
 619   stack support.
 620
 621
 622.. function:: inet_pton(address_family, ip_string)
 623
 624   Convert an IP address from its family-specific string format to a packed,
 625   binary format. :func:`inet_pton` is useful when a library or network protocol
 626   calls for an object of type :c:type:`struct in_addr` (similar to
 627   :func:`inet_aton`) or :c:type:`struct in6_addr`.
 628
 629   Supported values for *address_family* are currently :const:`AF_INET` and
 630   :const:`AF_INET6`. If the IP address string *ip_string* is invalid,
 631   :exc:`OSError` will be raised. Note that exactly what is valid depends on
 632   both the value of *address_family* and the underlying implementation of
 633   :c:func:`inet_pton`.
 634
 635   Availability: Unix (maybe not all platforms), Windows.
 636
 637
 638.. function:: inet_ntop(address_family, packed_ip)
 639
 640   Convert a packed IP address (a bytes object of some number of characters) to its
 641   standard, family-specific string representation (for example, ``'7.10.0.5'`` or
 642   ``'5aef:2b::8'``). :func:`inet_ntop` is useful when a library or network protocol
 643   returns an object of type :c:type:`struct in_addr` (similar to :func:`inet_ntoa`)
 644   or :c:type:`struct in6_addr`.
 645
 646   Supported values for *address_family* are currently :const:`AF_INET` and
 647   :const:`AF_INET6`. If the string *packed_ip* is not the correct length for the
 648   specified address family, :exc:`ValueError` will be raised.  A
 649   :exc:`OSError` is raised for errors from the call to :func:`inet_ntop`.
 650
 651   Availability: Unix (maybe not all platforms), Windows.
 652
 653
 654..
 655   XXX: Are sendmsg(), recvmsg() and CMSG_*() available on any
 656   non-Unix platforms?  The old (obsolete?) 4.2BSD form of the
 657   interface, in which struct msghdr has no msg_control or
 658   msg_controllen members, is not currently supported.
 659
 660.. function:: CMSG_LEN(length)
 661
 662   Return the total length, without trailing padding, of an ancillary
 663   data item with associated data of the given *length*.  This value
 664   can often be used as the buffer size for :meth:`~socket.recvmsg` to
 665   receive a single item of ancillary data, but :rfc:`3542` requires
 666   portable applications to use :func:`CMSG_SPACE` and thus include
 667   space for padding, even when the item will be the last in the
 668   buffer.  Raises :exc:`OverflowError` if *length* is outside the
 669   permissible range of values.
 670
 671   Availability: most Unix platforms, possibly others.
 672
 673   .. versionadded:: 3.3
 674
 675
 676.. function:: CMSG_SPACE(length)
 677
 678   Return the buffer size needed for :meth:`~socket.recvmsg` to
 679   receive an ancillary data item with associated data of the given
 680   *length*, along with any trailing padding.  The buffer space needed
 681   to receive multiple items is the sum of the :func:`CMSG_SPACE`
 682   values for their associated data lengths.  Raises
 683   :exc:`OverflowError` if *length* is outside the permissible range
 684   of values.
 685
 686   Note that some systems might support ancillary data without
 687   providing this function.  Also note that setting the buffer size
 688   using the results of this function may not precisely limit the
 689   amount of ancillary data that can be received, since additional
 690   data may be able to fit into the padding area.
 691
 692   Availability: most Unix platforms, possibly others.
 693
 694   .. versionadded:: 3.3
 695
 696
 697.. function:: getdefaulttimeout()
 698
 699   Return the default timeout in seconds (float) for new socket objects. A value
 700   of ``None`` indicates that new socket objects have no timeout. When the socket
 701   module is first imported, the default is ``None``.
 702
 703
 704.. function:: setdefaulttimeout(timeout)
 705
 706   Set the default timeout in seconds (float) for new socket objects.  When
 707   the socket module is first imported, the default is ``None``.  See
 708   :meth:`~socket.settimeout` for possible values and their respective
 709   meanings.
 710
 711
 712.. function:: sethostname(name)
 713
 714   Set the machine's hostname to *name*.  This will raise a
 715   :exc:`OSError` if you don't have enough rights.
 716
 717   Availability: Unix.
 718
 719   .. versionadded:: 3.3
 720
 721
 722.. function:: if_nameindex()
 723
 724   Return a list of network interface information
 725   (index int, name string) tuples.
 726   :exc:`OSError` if the system call fails.
 727
 728   Availability: Unix.
 729
 730   .. versionadded:: 3.3
 731
 732
 733.. function:: if_nametoindex(if_name)
 734
 735   Return a network interface index number corresponding to an
 736   interface name.
 737   :exc:`OSError` if no interface with the given name exists.
 738
 739   Availability: Unix.
 740
 741   .. versionadded:: 3.3
 742
 743
 744.. function:: if_indextoname(if_index)
 745
 746   Return a network interface name corresponding to a
 747   interface index number.
 748   :exc:`OSError` if no interface with the given index exists.
 749
 750   Availability: Unix.
 751
 752   .. versionadded:: 3.3
 753
 754
 755.. _socket-objects:
 756
 757Socket Objects
 758--------------
 759
 760Socket objects have the following methods.  Except for
 761:meth:`~socket.makefile`, these correspond to Unix system calls applicable
 762to sockets.
 763
 764
 765.. method:: socket.accept()
 766
 767   Accept a connection. The socket must be bound to an address and listening for
 768   connections. The return value is a pair ``(conn, address)`` where *conn* is a
 769   *new* socket object usable to send and receive data on the connection, and
 770   *address* is the address bound to the socket on the other end of the connection.
 771
 772   The newly created socket is :ref:`non-inheritable <fd_inheritance>`.
 773
 774   .. versionchanged:: 3.4
 775      The socket is now non-inheritable.
 776
 777
 778.. method:: socket.bind(address)
 779
 780   Bind the socket to *address*.  The socket must not already be bound. (The format
 781   of *address* depends on the address family --- see above.)
 782
 783
 784.. method:: socket.close()
 785
 786   Mark the socket closed.  The underlying system resource (e.g. a file
 787   descriptor) is also closed when all file objects from :meth:`makefile()`
 788   are closed.  Once that happens, all future operations on the socket
 789   object will fail. The remote end will receive no more data (after
 790   queued data is flushed).
 791
 792   Sockets are automatically closed when they are garbage-collected, but
 793   it is recommended to :meth:`close` them explicitly, or to use a
 794   :keyword:`with` statement around them.
 795
 796   .. note::
 797      :meth:`close()` releases the resource associated with a connection but
 798      does not necessarily close the connection immediately.  If you want
 799      to close the connection in a timely fashion, call :meth:`shutdown()`
 800      before :meth:`close()`.
 801
 802
 803.. method:: socket.connect(address)
 804
 805   Connect to a remote socket at *address*. (The format of *address* depends on the
 806   address family --- see above.)
 807
 808
 809.. method:: socket.connect_ex(address)
 810
 811   Like ``connect(address)``, but return an error indicator instead of raising an
 812   exception for errors returned by the C-level :c:func:`connect` call (other
 813   problems, such as "host not found," can still raise exceptions).  The error
 814   indicator is ``0`` if the operation succeeded, otherwise the value of the
 815   :c:data:`errno` variable.  This is useful to support, for example, asynchronous
 816   connects.
 817
 818
 819.. method:: socket.detach()
 820
 821   Put the socket object into closed state without actually closing the
 822   underlying file descriptor.  The file descriptor is returned, and can
 823   be reused for other purposes.
 824
 825   .. versionadded:: 3.2
 826
 827
 828.. method:: socket.dup()
 829
 830   Duplicate the socket.
 831
 832   The newly created socket is :ref:`non-inheritable <fd_inheritance>`.
 833
 834   .. versionchanged:: 3.4
 835      The socket is now non-inheritable.
 836
 837
 838.. method:: socket.fileno()
 839
 840   Return the socket's file descriptor (a small integer).  This is useful with
 841   :func:`select.select`.
 842
 843   Under Windows the small integer returned by this method cannot be used where a
 844   file descriptor can be used (such as :func:`os.fdopen`).  Unix does not have
 845   this limitation.
 846
 847
 848.. method:: socket.get_inheritable()
 849
 850   Get the :ref:`inheritable flag <fd_inheritance>` of the socket's file
 851   descriptor or socket's handle: ``True`` if the socket can be inherited in
 852   child processes, ``False`` if it cannot.
 853
 854   .. versionadded:: 3.4
 855
 856
 857.. method:: socket.getpeername()
 858
 859   Return the remote address to which the socket is connected.  This is useful to
 860   find out the port number of a remote IPv4/v6 socket, for instance. (The format
 861   of the address returned depends on the address family --- see above.)  On some
 862   systems this function is not supported.
 863
 864
 865.. method:: socket.getsockname()
 866
 867   Return the socket's own address.  This is useful to find out the port number of
 868   an IPv4/v6 socket, for instance. (The format of the address returned depends on
 869   the address family --- see above.)
 870
 871
 872.. method:: socket.getsockopt(level, optname[, buflen])
 873
 874   Return the value of the given socket option (see the Unix man page
 875   :manpage:`getsockopt(2)`).  The needed symbolic constants (:const:`SO_\*` etc.)
 876   are defined in this module.  If *buflen* is absent, an integer option is assumed
 877   and its integer value is returned by the function.  If *buflen* is present, it
 878   specifies the maximum length of the buffer used to receive the option in, and
 879   this buffer is returned as a bytes object.  It is up to the caller to decode the
 880   contents of the buffer (see the optional built-in module :mod:`struct` for a way
 881   to decode C structures encoded as byte strings).
 882
 883
 884.. method:: socket.gettimeout()
 885
 886   Return the timeout in seconds (float) associated with socket operations,
 887   or ``None`` if no timeout is set.  This reflects the last call to
 888   :meth:`setblocking` or :meth:`settimeout`.
 889
 890
 891.. method:: socket.ioctl(control, option)
 892
 893   :platform: Windows
 894
 895   The :meth:`ioctl` method is a limited interface to the WSAIoctl system
 896   interface.  Please refer to the `Win32 documentation
 897   <http://msdn.microsoft.com/en-us/library/ms741621%28VS.85%29.aspx>`_ for more
 898   information.
 899
 900   On other platforms, the generic :func:`fcntl.fcntl` and :func:`fcntl.ioctl`
 901   functions may be used; they accept a socket object as their first argument.
 902
 903.. method:: socket.listen(backlog)
 904
 905   Listen for connections made to the socket.  The *backlog* argument specifies the
 906   maximum number of queued connections and should be at least 0; the maximum value
 907   is system-dependent (usually 5), the minimum value is forced to 0.
 908
 909
 910.. method:: socket.makefile(mode='r', buffering=None, *, encoding=None, \
 911                            errors=None, newline=None)
 912
 913   .. index:: single: I/O control; buffering
 914
 915   Return a :term:`file object` associated with the socket.  The exact returned
 916   type depends on the arguments given to :meth:`makefile`.  These arguments are
 917   interpreted the same way as by the built-in :func:`open` function.
 918
 919   The socket must be in blocking mode; it can have a timeout, but the file
 920   object's internal buffer may end up in a inconsistent state if a timeout
 921   occurs.
 922
 923   Closing the file object returned by :meth:`makefile` won't close the
 924   original socket unless all other file objects have been closed and
 925   :meth:`socket.close` has been called on the socket object.
 926
 927   .. note::
 928
 929      On Windows, the file-like object created by :meth:`makefile` cannot be
 930      used where a file object with a file descriptor is expected, such as the
 931      stream arguments of :meth:`subprocess.Popen`.
 932
 933
 934.. method:: socket.recv(bufsize[, flags])
 935
 936   Receive data from the socket.  The return value is a bytes object representing the
 937   data received.  The maximum amount of data to be received at once is specified
 938   by *bufsize*.  See the Unix manual page :manpage:`recv(2)` for the meaning of
 939   the optional argument *flags*; it defaults to zero.
 940
 941   .. note::
 942
 943      For best match with hardware and network realities, the value of  *bufsize*
 944      should be a relatively small power of 2, for example, 4096.
 945
 946
 947.. method:: socket.recvfrom(bufsize[, flags])
 948
 949   Receive data from the socket.  The return value is a pair ``(bytes, address)``
 950   where *bytes* is a bytes object representing the data received and *address* is the
 951   address of the socket sending the data.  See the Unix manual page
 952   :manpage:`recv(2)` for the meaning of the optional argument *flags*; it defaults
 953   to zero. (The format of *address* depends on the address family --- see above.)
 954
 955
 956.. method:: socket.recvmsg(bufsize[, ancbufsize[, flags]])
 957
 958   Receive normal data (up to *bufsize* bytes) and ancillary data from
 959   the socket.  The *ancbufsize* argument sets the size in bytes of
 960   the internal buffer used to receive the ancillary data; it defaults
 961   to 0, meaning that no ancillary data will be received.  Appropriate
 962   buffer sizes for ancillary data can be calculated using
 963   :func:`CMSG_SPACE` or :func:`CMSG_LEN`, and items which do not fit
 964   into the buffer might be truncated or discarded.  The *flags*
 965   argument defaults to 0 and has the same meaning as for
 966   :meth:`recv`.
 967
 968   The return value is a 4-tuple: ``(data, ancdata, msg_flags,
 969   address)``.  The *data* item is a :class:`bytes` object holding the
 970   non-ancillary data received.  The *ancdata* item is a list of zero
 971   or more tuples ``(cmsg_level, cmsg_type, cmsg_data)`` representing
 972   the ancillary data (control messages) received: *cmsg_level* and
 973   *cmsg_type* are integers specifying the protocol level and
 974   protocol-specific type respectively, and *cmsg_data* is a
 975   :class:`bytes` object holding the associated data.  The *msg_flags*
 976   item is the bitwise OR of various flags indicating conditions on
 977   the received message; see your system documentation for details.
 978   If the receiving socket is unconnected, *address* is the address of
 979   the sending socket, if available; otherwise, its value is
 980   unspecified.
 981
 982   On some systems, :meth:`sendmsg` and :meth:`recvmsg` can be used to
 983   pass file descriptors between processes over an :const:`AF_UNIX`
 984   socket.  When this facility is used (it is often restricted to
 985   :const:`SOCK_STREAM` sockets), :meth:`recvmsg` will return, in its
 986   ancillary data, items of the form ``(socket.SOL_SOCKET,
 987   socket.SCM_RIGHTS, fds)``, where *fds* is a :class:`bytes` object
 988   representing the new file descriptors as a binary array of the
 989   native C :c:type:`int` type.  If :meth:`recvmsg` raises an
 990   exception after the system call returns, it will first attempt to
 991   close any file descriptors received via this mechanism.
 992
 993   Some systems do not indicate the truncated length of ancillary data
 994   items which have been only partially received.  If an item appears
 995   to extend beyond the end of the buffer, :meth:`recvmsg` will issue
 996   a :exc:`RuntimeWarning`, and will return the part of it which is
 997   inside the buffer provided it has not been truncated before the
 998   start of its associated data.
 999
1000   On systems which support the :const:`SCM_RIGHTS` mechanism, the
1001   following function will receive up to *maxfds* file descriptors,
1002   returning the message data and a list containing the descriptors
1003   (while ignoring unexpected conditions such as unrelated control
1004   messages being received).  See also :meth:`sendmsg`. ::
1005
1006      import socket, array
1007
1008      def recv_fds(sock, msglen, maxfds):
1009          fds = array.array("i")   # Array of ints
1010          msg, ancdata, flags, addr = sock.recvmsg(msglen, socket.CMSG_LEN(maxfds * fds.itemsize))
1011          for cmsg_level, cmsg_type, cmsg_data in ancdata:
1012              if (cmsg_level == socket.SOL_SOCKET and cmsg_type == socket.SCM_RIGHTS):
1013                  # Append data, ignoring any truncated integers at the end.
1014                  fds.fromstring(cmsg_data[:len(cmsg_data) - (len(cmsg_data) % fds.itemsize)])
1015          return msg, list(fds)
1016
1017   Availability: most Unix platforms, possibly others.
1018
1019   .. versionadded:: 3.3
1020
1021
1022.. method:: socket.recvmsg_into(buffers[, ancbufsize[, flags]])
1023
1024   Receive normal data and ancillary data from the socket, behaving as
1025   :meth:`recvmsg` would, but scatter the non-ancillary data into a
1026   series of buffers instead of returning a new bytes object.  The
1027   *buffers* argument must be an iterable of objects that export
1028   writable buffers (e.g. :class:`bytearray` objects); these will be
1029   filled with successive chunks of the non-ancillary data until it
1030   has all been written or there are no more buffers.  The operating
1031   system may set a limit (:func:`~os.sysconf` value ``SC_IOV_MAX``)
1032   on the number of buffers that can be used.  The *ancbufsize* and
1033   *flags* arguments have the same meaning as for :meth:`recvmsg`.
1034
1035   The return value is a 4-tuple: ``(nbytes, ancdata, msg_flags,
1036   address)``, where *nbytes* is the total number of bytes of
1037   non-ancillary data written into the buffers, and *ancdata*,
1038   *msg_flags* and *address* are the same as for :meth:`recvmsg`.
1039
1040   Example::
1041
1042      >>> import socket
1043      >>> s1, s2 = socket.socketpair()
1044      >>> b1 = bytearray(b'----')
1045      >>> b2 = bytearray(b'0123456789')
1046      >>> b3 = bytearray(b'--------------')
1047      >>> s1.send(b'Mary had a little lamb')
1048      22
1049      >>> s2.recvmsg_into([b1, memoryview(b2)[2:9], b3])
1050      (22, [], 0, None)
1051      >>> [b1, b2, b3]
1052      [bytearray(b'Mary'), bytearray(b'01 had a 9'), bytearray(b'little lamb---')]
1053
1054   Availability: most Unix platforms, possibly others.
1055
1056   .. versionadded:: 3.3
1057
1058
1059.. method:: socket.recvfrom_into(buffer[, nbytes[, flags]])
1060
1061   Receive data from the socket, writing it into *buffer* instead of creating a
1062   new bytestring.  The return value is a pair ``(nbytes, address)`` where *nbytes* is
1063   the number of bytes received and *address* is the address of the socket sending
1064   the data.  See the Unix manual page :manpage:`recv(2)` for the meaning of the
1065   optional argument *flags*; it defaults to zero.  (The format of *address*
1066   depends on the address family --- see above.)
1067
1068
1069.. method:: socket.recv_into(buffer[, nbytes[, flags]])
1070
1071   Receive up to *nbytes* bytes from the socket, storing the data into a buffer
1072   rather than creating a new bytestring.  If *nbytes* is not specified (or 0),
1073   receive up to the size available in the given buffer.  Returns the number of
1074   bytes received.  See the Unix manual page :manpage:`recv(2)` for the meaning
1075   of the optional argument *flags*; it defaults to zero.
1076
1077
1078.. method:: socket.send(bytes[, flags])
1079
1080   Send data to the socket.  The socket must be connected to a remote socket.  The
1081   optional *flags* argument has the same meaning as for :meth:`recv` above.
1082   Returns the number of bytes sent. Applications are responsible for checking that
1083   all data has been sent; if only some of the data was transmitted, the
1084   application needs to attempt delivery of the remaining data. For further
1085   information on this topic, consult the :ref:`socket-howto`.
1086
1087
1088.. method:: socket.sendall(bytes[, flags])
1089
1090   Send data to the socket.  The socket must be connected to a remote socket.  The
1091   optional *flags* argument has the same meaning as for :meth:`recv` above.
1092   Unlike :meth:`send`, this method continues to send data from *bytes* until
1093   either all data has been sent or an error occurs.  ``None`` is returned on
1094   success.  On error, an exception is raised, and there is no way to determine how
1095   much data, if any, was successfully sent.
1096
1097
1098.. method:: socket.sendto(bytes, address)
1099            socket.sendto(bytes, flags, address)
1100
1101   Send data to the socket.  The socket should not be connected to a remote socket,
1102   since the destination socket is specified by *address*.  The optional *flags*
1103   argument has the same meaning as for :meth:`recv` above.  Return the number of
1104   bytes sent. (The format of *address* depends on the address family --- see
1105   above.)
1106
1107
1108.. method:: socket.sendmsg(buffers[, ancdata[, flags[, address]]])
1109
1110   Send normal and ancillary data to the socket, gathering the
1111   non-ancillary data from a series of buffers and concatenating it
1112   into a single message.  The *buffers* argument specifies the
1113   non-ancillary data as an iterable of buffer-compatible objects
1114   (e.g. :class:`bytes` objects); the operating system may set a limit
1115   (:func:`~os.sysconf` value ``SC_IOV_MAX``) on the number of buffers
1116   that can be used.  The *ancdata* argument specifies the ancillary
1117   data (control messages) as an iterable of zero or more tuples
1118   ``(cmsg_level, cmsg_type, cmsg_data)``, where *cmsg_level* and
1119   *cmsg_type* are integers specifying the protocol level and
1120   protocol-specific type respectively, and *cmsg_data* is a
1121   buffer-compatible object holding the associated data.  Note that
1122   some systems (in particular, systems without :func:`CMSG_SPACE`)
1123   might support sending only one control message per call.  The
1124   *flags* argument defaults to 0 and has the same meaning as for
1125   :meth:`send`.  If *address* is supplied and not ``None``, it sets a
1126   destination address for the message.  The return value is the
1127   number of bytes of non-ancillary data sent.
1128
1129   The following function sends the list of file descriptors *fds*
1130   over an :const:`AF_UNIX` socket, on systems which support the
1131   :const:`SCM_RIGHTS` mechanism.  See also :meth:`recvmsg`. ::
1132
1133      import socket, array
1134
1135      def send_fds(sock, msg, fds):
1136          return sock.sendmsg([msg], [(socket.SOL_SOCKET, socket.SCM_RIGHTS, array.array("i", fds))])
1137
1138   Availability: most Unix platforms, possibly others.
1139
1140   .. versionadded:: 3.3
1141
1142
1143.. method:: socket.set_inheritable(inheritable)
1144
1145   Set the :ref:`inheritable flag <fd_inheritance>` of the socket's file
1146   descriptor or socket's handle.
1147
1148   .. versionadded:: 3.4
1149
1150
1151.. method:: socket.setblocking(flag)
1152
1153   Set blocking or non-blocking mode of the socket: if *flag* is false, the
1154   socket is set to non-blocking, else to blocking mode.
1155
1156   This method is a shorthand for certain :meth:`~socket.settimeout` calls:
1157
1158   * ``sock.setblocking(True)`` is equivalent to ``sock.settimeout(None)``
1159
1160   * ``sock.setblocking(False)`` is equivalent to ``sock.settimeout(0.0)``
1161
1162
1163.. method:: socket.settimeout(value)
1164
1165   Set a timeout on blocking socket operations.  The *value* argument can be a
1166   nonnegative floating point number expressing seconds, or ``None``.
1167   If a non-zero value is given, subsequent socket operations will raise a
1168   :exc:`timeout` exception if the timeout period *value* has elapsed before
1169   the operation has completed.  If zero is given, the socket is put in
1170   non-blocking mode. If ``None`` is given, the socket is put in blocking mode.
1171
1172   For further information, please consult the :ref:`notes on socket timeouts <socket-timeouts>`.
1173
1174
1175.. method:: socket.setsockopt(level, optname, value)
1176
1177   .. index:: module: struct
1178
1179   Set the value of the given socket option (see the Unix manual page
1180   :manpage:`setsockopt(2)`).  The needed symbolic constants are defined in the
1181   :mod:`socket` module (:const:`SO_\*` etc.).  The value can be an integer or a
1182   bytes object representing a buffer.  In the latter case it is up to the caller to
1183   ensure that the bytestring contains the proper bits (see the optional built-in
1184   module :mod:`struct` for a way to encode C structures as bytestrings).
1185
1186
1187.. method:: socket.shutdown(how)
1188
1189   Shut down one or both halves of the connection.  If *how* is :const:`SHUT_RD`,
1190   further receives are disallowed.  If *how* is :const:`SHUT_WR`, further sends
1191   are disallowed.  If *how* is :const:`SHUT_RDWR`, further sends and receives are
1192   disallowed.
1193
1194
1195.. method:: socket.share(process_id)
1196
1197   Duplicate a socket and prepare it for sharing with a target process.  The
1198   target process must be provided with *process_id*.  The resulting bytes object
1199   can then be passed to the target process using some form of interprocess
1200   communication and the socket can be recreated there using :func:`fromshare`.
1201   Once this method has been called, it is safe to close the socket since
1202   the operating system has already duplicated it for the target process.
1203
1204   Availability: Windows.
1205
1206   .. versionadded:: 3.3
1207
1208
1209Note that there are no methods :meth:`read` or :meth:`write`; use
1210:meth:`~socket.recv` and :meth:`~socket.send` without *flags* argument instead.
1211
1212Socket objects also have these (read-only) attributes that correspond to the
1213values given to the :class:`socket` constructor.
1214
1215
1216.. attribute:: socket.family
1217
1218   The socket family.
1219
1220
1221.. attribute:: socket.type
1222
1223   The socket type.
1224
1225
1226.. attribute:: socket.proto
1227
1228   The socket protocol.
1229
1230
1231
1232.. _socket-timeouts:
1233
1234Notes on socket timeouts
1235------------------------
1236
1237A socket object can be in one of three modes: blocking, non-blocking, or
1238timeout.  Sockets are by default always created in blocking mode, but this
1239can be changed by calling :func:`setdefaulttimeout`.
1240
1241* In *blocking mode*, operations block until complete or the system returns
1242  an error (such as connection timed out).
1243
1244* In *non-blocking mode*, operations fail (with an error that is unfortunately
1245  system-dependent) if they cannot be completed immediately: functions from the
1246  :mod:`select` can be used to know when and whether a socket is available for
1247  reading or writing.
1248
1249* In *timeout mode*, operations fail if they cannot be completed within the
1250  timeout specified for the socket (they raise a :exc:`timeout` exception)
1251  or if the system returns an error.
1252
1253.. note::
1254   At the operating system level, sockets in *timeout mode* are internally set
1255   in non-blocking mode.  Also, the blocking and timeout modes are shared between
1256   file descriptors and socket objects that refer to the same network endpoint.
1257   This implementation detail can have visible consequences if e.g. you decide
1258   to use the :meth:`~socket.fileno()` of a socket.
1259
1260Timeouts and the ``connect`` method
1261^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1262
1263The :meth:`~socket.connect` operation is also subject to the timeout
1264setting, and in general it is recommended to call :meth:`~socket.settimeout`
1265before calling :meth:`~socket.connect` or pass a timeout parameter to
1266:meth:`create_connection`.  However, the system network stack may also
1267return a connection timeout error of its own regardless of any Python socket
1268timeout setting.
1269
1270Timeouts and the ``accept`` method
1271^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1272
1273If :func:`getdefaulttimeout` is not :const:`None`, sockets returned by
1274the :meth:`~socket.accept` method inherit that timeout.  Otherwise, the
1275behaviour depends on settings of the listening socket:
1276
1277* if the listening …

Large files files are truncated, but you can click here to view the full file