PageRenderTime 68ms CodeModel.GetById 3ms app.highlight 56ms RepoModel.GetById 1ms app.codeStats 1ms

/library/socket.rst

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