PageRenderTime 77ms CodeModel.GetById 10ms app.highlight 55ms RepoModel.GetById 1ms app.codeStats 0ms

/Doc/library/socket.rst

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

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