PageRenderTime 58ms CodeModel.GetById 3ms app.highlight 43ms RepoModel.GetById 2ms app.codeStats 0ms

/2.7/Doc/library/socket.rst

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