-
-:mod:`socket` --- Low-level networking interface
-================================================
-
-.. module:: socket
- :synopsis: Low-level networking interface.
-
-
-This module provides access to the BSD *socket* interface. It is available on
-all modern Unix systems, Windows, Mac OS X, BeOS, OS/2, and probably additional
-platforms.
-
-.. note::
-
- Some behavior may be platform dependent, since calls are made to the operating
- system socket APIs.
-
-For an introduction to socket programming (in C), see the following papers: An
-Introductory 4.3BSD Interprocess Communication Tutorial, by Stuart Sechrest and
-An Advanced 4.3BSD Interprocess Communication Tutorial, by Samuel J. Leffler et
-al, both in the UNIX Programmer's Manual, Supplementary Documents 1 (sections
-PS1:7 and PS1:8). The platform-specific reference material for the various
-socket-related system calls are also a valuable source of information on the
-details of socket semantics. For Unix, refer to the manual pages; for Windows,
-see the WinSock (or Winsock 2) specification. For IPv6-ready APIs, readers may
-want to refer to :rfc:`2553` titled Basic Socket Interface Extensions for IPv6.
-
-.. index:: object: socket
-
-The Python interface is a straightforward transliteration of the Unix system
-call and library interface for sockets to Python's object-oriented style: the
-:func:`socket` function returns a :dfn:`socket object` whose methods implement
-the various socket system calls. Parameter types are somewhat higher-level than
-in the C interface: as with :meth:`read` and :meth:`write` operations on Python
-files, buffer allocation on receive operations is automatic, and buffer length
-is implicit on send operations.
-
-Socket addresses are represented as follows: A single string is used for the
-:const:`AF_UNIX` address family. A pair ``(host, port)`` is used for the
-:const:`AF_INET` address family, where *host* is a string representing either a
-hostname in Internet domain notation like ``'daring.cwi.nl'`` or an IPv4 address
-like ``'100.50.200.5'``, and *port* is an integral port number. For
-:const:`AF_INET6` address family, a four-tuple ``(host, port, flowinfo,
-scopeid)`` is used, where *flowinfo* and *scopeid* represents ``sin6_flowinfo``
-and ``sin6_scope_id`` member in :const:`struct sockaddr_in6` in C. For
-:mod:`socket` module methods, *flowinfo* and *scopeid* can be omitted just for
-backward compatibility. Note, however, omission of *scopeid* can cause problems
-in manipulating scoped IPv6 addresses. Other address families are currently not
-supported. The address format required by a particular socket object is
-automatically selected based on the address family specified when the socket
-object was created.
-
-For IPv4 addresses, two special forms are accepted instead of a host address:
-the empty string represents :const:`INADDR_ANY`, and the string
-``'<broadcast>'`` represents :const:`INADDR_BROADCAST`. The behavior is not
-available for IPv6 for backward compatibility, therefore, you may want to avoid
-these if you intend to support IPv6 with your Python programs.
-
-If you use a hostname in the *host* portion of IPv4/v6 socket address, the
-program may show a nondeterministic behavior, as Python uses the first address
-returned from the DNS resolution. The socket address will be resolved
-differently into an actual IPv4/v6 address, depending on the results from DNS
-resolution and/or the host configuration. For deterministic behavior use a
-numeric address in *host* portion.
-
-.. versionadded:: 2.5
- AF_NETLINK sockets are represented as pairs ``pid, groups``.
-
-All errors raise exceptions. The normal exceptions for invalid argument types
-and out-of-memory conditions can be raised; errors related to socket or address
-semantics raise the error :exc:`socket.error`.
-
-Non-blocking mode is supported through :meth:`setblocking`. A generalization of
-this based on timeouts is supported through :meth:`settimeout`.
-
-The module :mod:`socket` exports the following constants and functions:
-
-
-.. exception:: error
-
- .. index:: module: errno
-
- This exception is raised for socket-related errors. The accompanying value is
- either a string telling what went wrong or a pair ``(errno, string)``
- representing an error returned by a system call, similar to the value
- accompanying :exc:`os.error`. See the module :mod:`errno`, which contains names
- for the error codes defined by the underlying operating system.
-
- .. versionchanged:: 2.6
- :exc:`socket.error` is now a child class of :exc:`IOError`.
-
-
-.. exception:: herror
-
- This exception is raised for address-related errors, i.e. for functions that use
- *h_errno* in the C API, including :func:`gethostbyname_ex` and
- :func:`gethostbyaddr`.
-
- The accompanying value is a pair ``(h_errno, string)`` representing an error
- returned by a library call. *string* represents the description of *h_errno*, as
- returned by the :cfunc:`hstrerror` C function.
-
-
-.. exception:: gaierror
-
- This exception is raised for address-related errors, for :func:`getaddrinfo` and
- :func:`getnameinfo`. The accompanying value is a pair ``(error, string)``
- representing an error returned by a library call. *string* represents the
- description of *error*, as returned by the :cfunc:`gai_strerror` C function. The
- *error* value will match one of the :const:`EAI_\*` constants defined in this
- module.
-
-
-.. exception:: timeout
-
- This exception is raised when a timeout occurs on a socket which has had
- timeouts enabled via a prior call to :meth:`settimeout`. The accompanying value
- is a string whose value is currently always "timed out".
-
- .. versionadded:: 2.3
-
-
-.. data:: AF_UNIX
- AF_INET
- AF_INET6
-
- These constants represent the address (and protocol) families, used for the
- first argument to :func:`socket`. If the :const:`AF_UNIX` constant is not
- defined then this protocol is unsupported.
-
-
-.. data:: SOCK_STREAM
- SOCK_DGRAM
- SOCK_RAW
- SOCK_RDM
- SOCK_SEQPACKET
-
- These constants represent the socket types, used for the second argument to
- :func:`socket`. (Only :const:`SOCK_STREAM` and :const:`SOCK_DGRAM` appear to be
- generally useful.)
-
-
-.. data:: SO_*
- SOMAXCONN
- MSG_*
- SOL_*
- IPPROTO_*
- IPPORT_*
- INADDR_*
- IP_*
- IPV6_*
- EAI_*
- AI_*
- NI_*
- TCP_*
-
- Many constants of these forms, documented in the Unix documentation on sockets
- and/or the IP protocol, are also defined in the socket module. They are
- generally used in arguments to the :meth:`setsockopt` and :meth:`getsockopt`
- methods of socket objects. In most cases, only those symbols that are defined
- in the Unix header files are defined; for a few symbols, default values are
- provided.
-
-
-.. data:: has_ipv6
-
- This constant contains a boolean value which indicates if IPv6 is supported on
- this platform.
-
- .. versionadded:: 2.3
-
-
-.. function:: create_connection(address[, timeout])
-
- Connects to the *address* received (as usual, a ``(host, port)`` pair), with an
- optional timeout for the connection. Especially useful for higher-level
- protocols, it is not normally used directly from application-level code.
- Passing the optional *timeout* parameter will set the timeout on the socket
- instance (if it is not given or ``None``, the global default timeout setting is
- used).
-
- .. versionadded:: 2.6
-
-
-.. function:: getaddrinfo(host, port[, family[, socktype[, proto[, flags]]]])
-
- Resolves the *host*/*port* argument, into a sequence of 5-tuples that contain
- all the necessary argument for the sockets manipulation. *host* is a domain
- name, a string representation of IPv4/v6 address or ``None``. *port* is a string
- service name (like ``'http'``), a numeric port number or ``None``.
-
- The rest of the arguments are optional and must be numeric if specified. For
- *host* and *port*, by passing either an empty string or ``None``, you can pass
- ``NULL`` to the C API. The :func:`getaddrinfo` function returns a list of
- 5-tuples with the following structure:
-
- ``(family, socktype, proto, canonname, sockaddr)``
-
- *family*, *socktype*, *proto* are all integer and are meant to be passed to the
- :func:`socket` function. *canonname* is a string representing the canonical name
- of the *host*. It can be a numeric IPv4/v6 address when :const:`AI_CANONNAME` is
- specified for a numeric *host*. *sockaddr* is a tuple describing a socket
- address, as described above. See the source for :mod:`socket` and other
- library modules for a typical usage of the function.
-
- .. versionadded:: 2.2
-
-
-.. function:: getfqdn([name])
-
- Return a fully qualified domain name for *name*. If *name* is omitted or empty,
- it is interpreted as the local host. To find the fully qualified name, the
- hostname returned by :func:`gethostbyaddr` is checked, then aliases for the
- host, if available. The first name which includes a period is selected. In
- case no fully qualified domain name is available, the hostname as returned by
- :func:`gethostname` is returned.
-
- .. versionadded:: 2.0
-
-
-.. function:: gethostbyname(hostname)
-
- Translate a host name to IPv4 address format. The IPv4 address is returned as a
- string, such as ``'100.50.200.5'``. If the host name is an IPv4 address itself
- it is returned unchanged. See :func:`gethostbyname_ex` for a more complete
- interface. :func:`gethostbyname` does not support IPv6 name resolution, and
- :func:`getaddrinfo` should be used instead for IPv4/v6 dual stack support.
-
-
-.. function:: gethostbyname_ex(hostname)
-
- Translate a host name to IPv4 address format, extended interface. Return a
- triple ``(hostname, aliaslist, ipaddrlist)`` where *hostname* is the primary
- host name responding to the given *ip_address*, *aliaslist* is a (possibly
- empty) list of alternative host names for the same address, and *ipaddrlist* is
- a list of IPv4 addresses for the same interface on the same host (often but not
- always a single address). :func:`gethostbyname_ex` does not support IPv6 name
- resolution, and :func:`getaddrinfo` should be used instead for IPv4/v6 dual
- stack support.
-
-
-.. function:: gethostname()
-
- Return a string containing the hostname of the machine where the Python
- interpreter is currently executing. If you want to know the current machine's IP
- address, you may want to use ``gethostbyname(gethostname())``. This operation
- assumes that there is a valid address-to-host mapping for the host, and the
- assumption does not always hold. Note: :func:`gethostname` doesn't always return
- the fully qualified domain name; use ``getfqdn()`` (see above).
-
-
-.. function:: gethostbyaddr(ip_address)
-
- Return a triple ``(hostname, aliaslist, ipaddrlist)`` where *hostname* is the
- primary host name responding to the given *ip_address*, *aliaslist* is a
- (possibly empty) list of alternative host names for the same address, and
- *ipaddrlist* is a list of IPv4/v6 addresses for the same interface on the same
- host (most likely containing only a single address). To find the fully qualified
- domain name, use the function :func:`getfqdn`. :func:`gethostbyaddr` supports
- both IPv4 and IPv6.
-
-
-.. function:: getnameinfo(sockaddr, flags)
-
- Translate a socket address *sockaddr* into a 2-tuple ``(host, port)``. Depending
- on the settings of *flags*, the result can contain a fully-qualified domain name
- or numeric address representation in *host*. Similarly, *port* can contain a
- string port name or a numeric port number.
-
- .. versionadded:: 2.2
-
-
-.. function:: getprotobyname(protocolname)
-
- Translate an Internet protocol name (for example, ``'icmp'``) to a constant
- suitable for passing as the (optional) third argument to the :func:`socket`
- function. This is usually only needed for sockets opened in "raw" mode
- (:const:`SOCK_RAW`); for the normal socket modes, the correct protocol is chosen
- automatically if the protocol is omitted or zero.
-
-
-.. function:: getservbyname(servicename[, protocolname])
-
- Translate an Internet service name and protocol name to a port number for that
- service. The optional protocol name, if given, should be ``'tcp'`` or
- ``'udp'``, otherwise any protocol will match.
-
-
-.. function:: getservbyport(port[, protocolname])
-
- Translate an Internet port number and protocol name to a service name for that
- service. The optional protocol name, if given, should be ``'tcp'`` or
- ``'udp'``, otherwise any protocol will match.
-
-
-.. function:: socket([family[, type[, proto]]])
-
- Create a new socket using the given address family, socket type and protocol
- number. The address family should be :const:`AF_INET` (the default),
- :const:`AF_INET6` or :const:`AF_UNIX`. The socket type should be
- :const:`SOCK_STREAM` (the default), :const:`SOCK_DGRAM` or perhaps one of the
- other ``SOCK_`` constants. The protocol number is usually zero and may be
- omitted in that case.
-
-
-.. function:: socketpair([family[, type[, proto]]])
-
- Build a pair of connected socket objects using the given address family, socket
- type, and protocol number. Address family, socket type, and protocol number are
- as for the :func:`socket` function above. The default family is :const:`AF_UNIX`
- if defined on the platform; otherwise, the default is :const:`AF_INET`.
- Availability: Unix.
-
- .. versionadded:: 2.4
-
-
-.. function:: fromfd(fd, family, type[, proto])
-
- Duplicate the file descriptor *fd* (an integer as returned by a file object's
- :meth:`fileno` method) and build a socket object from the result. Address
- family, socket type and protocol number are as for the :func:`socket` function
- above. The file descriptor should refer to a socket, but this is not checked ---
- subsequent operations on the object may fail if the file descriptor is invalid.
- This function is rarely needed, but can be used to get or set socket options on
- a socket passed to a program as standard input or output (such as a server
- started by the Unix inet daemon). The socket is assumed to be in blocking mode.
- Availability: Unix.
-
-
-.. function:: ntohl(x)
-
- Convert 32-bit positive integers from network to host byte order. On machines
- where the host byte order is the same as network byte order, this is a no-op;
- otherwise, it performs a 4-byte swap operation.
-
-
-.. function:: ntohs(x)
-
- Convert 16-bit positive integers from network to host byte order. On machines
- where the host byte order is the same as network byte order, this is a no-op;
- otherwise, it performs a 2-byte swap operation.
-
-
-.. function:: htonl(x)
-
- Convert 32-bit positive integers from host to network byte order. On machines
- where the host byte order is the same as network byte order, this is a no-op;
- otherwise, it performs a 4-byte swap operation.
-
-
-.. function:: htons(x)
-
- Convert 16-bit positive integers from host to network byte order. On machines
- where the host byte order is the same as network byte order, this is a no-op;
- otherwise, it performs a 2-byte swap operation.
-
-
-.. function:: inet_aton(ip_string)
-
- Convert an IPv4 address from dotted-quad string format (for example,
- '123.45.67.89') to 32-bit packed binary format, as a string four characters in
- length. This is useful when conversing with a program that uses the standard C
- library and needs objects of type :ctype:`struct in_addr`, which is the C type
- for the 32-bit packed binary this function returns.
-
- If the IPv4 address string passed to this function is invalid,
- :exc:`socket.error` will be raised. Note that exactly what is valid depends on
- the underlying C implementation of :cfunc:`inet_aton`.
-
- :func:`inet_aton` does not support IPv6, and :func:`getnameinfo` should be used
- instead for IPv4/v6 dual stack support.
-
-
-.. function:: inet_ntoa(packed_ip)
-
- Convert a 32-bit packed IPv4 address (a string four characters in length) to its
- standard dotted-quad string representation (for example, '123.45.67.89'). This
- is useful when conversing with a program that uses the standard C library and
- needs objects of type :ctype:`struct in_addr`, which is the C type for the
- 32-bit packed binary data this function takes as an argument.
-
- If the string passed to this function is not exactly 4 bytes in length,
- :exc:`socket.error` will be raised. :func:`inet_ntoa` does not support IPv6, and
- :func:`getnameinfo` should be used instead for IPv4/v6 dual stack support.
-
-
-.. function:: inet_pton(address_family, ip_string)
-
- Convert an IP address from its family-specific string format to a packed, binary
- format. :func:`inet_pton` is useful when a library or network protocol calls for
- an object of type :ctype:`struct in_addr` (similar to :func:`inet_aton`) or
- :ctype:`struct in6_addr`.
-
- Supported values for *address_family* are currently :const:`AF_INET` and
- :const:`AF_INET6`. If the IP address string *ip_string* is invalid,
- :exc:`socket.error` will be raised. Note that exactly what is valid depends on
- both the value of *address_family* and the underlying implementation of
- :cfunc:`inet_pton`.
-
- Availability: Unix (maybe not all platforms).
-
- .. versionadded:: 2.3
-
-
-.. function:: inet_ntop(address_family, packed_ip)
-
- Convert a packed IP address (a string of some number of characters) to its
- standard, family-specific string representation (for example, ``'7.10.0.5'`` or
- ``'5aef:2b::8'``) :func:`inet_ntop` is useful when a library or network protocol
- returns an object of type :ctype:`struct in_addr` (similar to :func:`inet_ntoa`)
- or :ctype:`struct in6_addr`.
-
- Supported values for *address_family* are currently :const:`AF_INET` and
- :const:`AF_INET6`. If the string *packed_ip* is not the correct length for the
- specified address family, :exc:`ValueError` will be raised. A
- :exc:`socket.error` is raised for errors from the call to :func:`inet_ntop`.
-
- Availability: Unix (maybe not all platforms).
-
- .. versionadded:: 2.3
-
-
-.. function:: getdefaulttimeout()
-
- Return the default timeout in floating seconds for new socket objects. A value
- of ``None`` indicates that new socket objects have no timeout. When the socket
- module is first imported, the default is ``None``.
-
- .. versionadded:: 2.3
-
-
-.. function:: setdefaulttimeout(timeout)
-
- Set the default timeout in floating seconds for new socket objects. A value of
- ``None`` indicates that new socket objects have no timeout. When the socket
- module is first imported, the default is ``None``.
-
- .. versionadded:: 2.3
-
-
-.. data:: SocketType
-
- This is a Python type object that represents the socket object type. It is the
- same as ``type(socket(...))``.
-
-
-.. seealso::
-
- Module :mod:`SocketServer`
- Classes that simplify writing network servers.
-
-
-.. _socket-objects:
-
-Socket Objects
---------------
-
-Socket objects have the following methods. Except for :meth:`makefile` these
-correspond to Unix system calls applicable to sockets.
-
-
-.. method:: socket.accept()
-
- Accept a connection. The socket must be bound to an address and listening for
- connections. The return value is a pair ``(conn, address)`` where *conn* is a
- *new* socket object usable to send and receive data on the connection, and
- *address* is the address bound to the socket on the other end of the connection.
-
-
-.. method:: socket.bind(address)
-
- Bind the socket to *address*. The socket must not already be bound. (The format
- of *address* depends on the address family --- see above.)
-
- .. note::
-
- This method has historically accepted a pair of parameters for :const:`AF_INET`
- addresses instead of only a tuple. This was never intentional and is no longer
- available in Python 2.0 and later.
-
-
-.. method:: socket.close()
-
- Close the socket. All future operations on the socket object will fail. The
- remote end will receive no more data (after queued data is flushed). Sockets are
- automatically closed when they are garbage-collected.
-
-
-.. method:: socket.connect(address)
-
- Connect to a remote socket at *address*. (The format of *address* depends on the
- address family --- see above.)
-
- .. note::
-
- This method has historically accepted a pair of parameters for :const:`AF_INET`
- addresses instead of only a tuple. This was never intentional and is no longer
- available in Python 2.0 and later.
-
-
-.. method:: socket.connect_ex(address)
-
- Like ``connect(address)``, but return an error indicator instead of raising an
- exception for errors returned by the C-level :cfunc:`connect` call (other
- problems, such as "host not found," can still raise exceptions). The error
- indicator is ``0`` if the operation succeeded, otherwise the value of the
- :cdata:`errno` variable. This is useful to support, for example, asynchronous
- connects.
-
- .. note::
-
- This method has historically accepted a pair of parameters for :const:`AF_INET`
- addresses instead of only a tuple. This was never intentional and is no longer
- available in Python 2.0 and later.
-
-
-.. method:: socket.fileno()
-
- Return the socket's file descriptor (a small integer). This is useful with
- :func:`select.select`.
-
- Under Windows the small integer returned by this method cannot be used where a
- file descriptor can be used (such as :func:`os.fdopen`). Unix does not have
- this limitation.
-
-
-.. method:: socket.getpeername()
-
- Return the remote address to which the socket is connected. This is useful to
- find out the port number of a remote IPv4/v6 socket, for instance. (The format
- of the address returned depends on the address family --- see above.) On some
- systems this function is not supported.
-
-
-.. method:: socket.getsockname()
-
- Return the socket's own address. This is useful to find out the port number of
- an IPv4/v6 socket, for instance. (The format of the address returned depends on
- the address family --- see above.)
-
-
-.. method:: socket.getsockopt(level, optname[, buflen])
-
- Return the value of the given socket option (see the Unix man page
- :manpage:`getsockopt(2)`). The needed symbolic constants (:const:`SO_\*` etc.)
- are defined in this module. If *buflen* is absent, an integer option is assumed
- and its integer value is returned by the function. If *buflen* is present, it
- specifies the maximum length of the buffer used to receive the option in, and
- this buffer is returned as a string. It is up to the caller to decode the
- contents of the buffer (see the optional built-in module :mod:`struct` for a way
- to decode C structures encoded as strings).
-
-
-.. method:: socket.listen(backlog)
-
- Listen for connections made to the socket. The *backlog* argument specifies the
- maximum number of queued connections and should be at least 1; the maximum value
- is system-dependent (usually 5).
-
-
-.. method:: socket.makefile([mode[, bufsize]])
-
- .. index:: single: I/O control; buffering
-
- Return a :dfn:`file object` associated with the socket. (File objects are
- described in :ref:`bltin-file-objects`.) The file object
- references a :cfunc:`dup`\ ped version of the socket file descriptor, so the
- file object and socket object may be closed or garbage-collected independently.
- The socket must be in blocking mode (it can not have a timeout). The optional
- *mode* and *bufsize* arguments are interpreted the same way as by the built-in
- :func:`file` function.
-
-
-.. method:: socket.recv(bufsize[, flags])
-
- Receive data from the socket. The return value is a string representing the
- data received. The maximum amount of data to be received at once is specified
- by *bufsize*. See the Unix manual page :manpage:`recv(2)` for the meaning of
- the optional argument *flags*; it defaults to zero.
-
- .. note::
-
- For best match with hardware and network realities, the value of *bufsize*
- should be a relatively small power of 2, for example, 4096.
-
-
-.. method:: socket.recvfrom(bufsize[, flags])
-
- Receive data from the socket. The return value is a pair ``(string, address)``
- where *string* is a string representing the data received and *address* is the
- address of the socket sending the data. See the Unix manual page
- :manpage:`recv(2)` for the meaning of the optional argument *flags*; it defaults
- to zero. (The format of *address* depends on the address family --- see above.)
-
-
-.. method:: socket.recvfrom_into(buffer[, nbytes[, flags]])
-
- Receive data from the socket, writing it into *buffer* instead of creating a
- new string. The return value is a pair ``(nbytes, address)`` where *nbytes* is
- the number of bytes received and *address* is the address of the socket sending
- the data. See the Unix manual page :manpage:`recv(2)` for the meaning of the
- optional argument *flags*; it defaults to zero. (The format of *address*
- depends on the address family --- see above.)
-
- .. versionadded:: 2.5
-
-
-.. method:: socket.recv_into(buffer[, nbytes[, flags]])
-
- Receive up to *nbytes* bytes from the socket, storing the data into a buffer
- rather than creating a new string. If *nbytes* is not specified (or 0),
- receive up to the size available in the given buffer. See the Unix manual page
- :manpage:`recv(2)` for the meaning of the optional argument *flags*; it defaults
- to zero.
-
- .. versionadded:: 2.5
-
-
-.. method:: socket.send(string[, flags])
-
- Send data to the socket. The socket must be connected to a remote socket. The
- optional *flags* argument has the same meaning as for :meth:`recv` above.
- Returns the number of bytes sent. Applications are responsible for checking that
- all data has been sent; if only some of the data was transmitted, the
- application needs to attempt delivery of the remaining data.
-
-
-.. method:: socket.sendall(string[, flags])
-
- Send data to the socket. The socket must be connected to a remote socket. The
- optional *flags* argument has the same meaning as for :meth:`recv` above.
- Unlike :meth:`send`, this method continues to send data from *string* until
- either all data has been sent or an error occurs. ``None`` is returned on
- success. On error, an exception is raised, and there is no way to determine how
- much data, if any, was successfully sent.
-
-
-.. method:: socket.sendto(string[, flags], address)
-
- Send data to the socket. The socket should not be connected to a remote socket,
- since the destination socket is specified by *address*. The optional *flags*
- argument has the same meaning as for :meth:`recv` above. Return the number of
- bytes sent. (The format of *address* depends on the address family --- see
- above.)
-
-
-.. method:: socket.setblocking(flag)
-
- Set blocking or non-blocking mode of the socket: if *flag* is 0, the socket is
- set to non-blocking, else to blocking mode. Initially all sockets are in
- blocking mode. In non-blocking mode, if a :meth:`recv` call doesn't find any
- data, or if a :meth:`send` call can't immediately dispose of the data, a
- :exc:`error` exception is raised; in blocking mode, the calls block until they
- can proceed. ``s.setblocking(0)`` is equivalent to ``s.settimeout(0)``;
- ``s.setblocking(1)`` is equivalent to ``s.settimeout(None)``.
-
-
-.. method:: socket.settimeout(value)
-
- Set a timeout on blocking socket operations. The *value* argument can be a
- nonnegative float expressing seconds, or ``None``. If a float is given,
- subsequent socket operations will raise an :exc:`timeout` exception if the
- timeout period *value* has elapsed before the operation has completed. Setting
- a timeout of ``None`` disables timeouts on socket operations.
- ``s.settimeout(0.0)`` is equivalent to ``s.setblocking(0)``;
- ``s.settimeout(None)`` is equivalent to ``s.setblocking(1)``.
-
- .. versionadded:: 2.3
-
-
-.. method:: socket.gettimeout()
-
- Return the timeout in floating seconds associated with socket operations, or
- ``None`` if no timeout is set. This reflects the last call to
- :meth:`setblocking` or :meth:`settimeout`.
-
- .. versionadded:: 2.3
-
-Some notes on socket blocking and timeouts: A socket object can be in one of
-three modes: blocking, non-blocking, or timeout. Sockets are always created in
-blocking mode. In blocking mode, operations block until complete. In
-non-blocking mode, operations fail (with an error that is unfortunately
-system-dependent) if they cannot be completed immediately. In timeout mode,
-operations fail if they cannot be completed within the timeout specified for the
-socket. The :meth:`setblocking` method is simply a shorthand for certain
-:meth:`settimeout` calls.
-
-Timeout mode internally sets the socket in non-blocking mode. The blocking and
-timeout modes are shared between file descriptors and socket objects that refer
-to the same network endpoint. A consequence of this is that file objects
-returned by the :meth:`makefile` method must only be used when the socket is in
-blocking mode; in timeout or non-blocking mode file operations that cannot be
-completed immediately will fail.
-
-Note that the :meth:`connect` operation is subject to the timeout setting, and
-in general it is recommended to call :meth:`settimeout` before calling
-:meth:`connect`.
-
-
-.. method:: socket.setsockopt(level, optname, value)
-
- .. index:: module: struct
-
- Set the value of the given socket option (see the Unix manual page
- :manpage:`setsockopt(2)`). The needed symbolic constants are defined in the
- :mod:`socket` module (:const:`SO_\*` etc.). The value can be an integer or a
- string representing a buffer. In the latter case it is up to the caller to
- ensure that the string contains the proper bits (see the optional built-in
- module :mod:`struct` for a way to encode C structures as strings).
-
-
-.. method:: socket.shutdown(how)
-
- Shut down one or both halves of the connection. If *how* is :const:`SHUT_RD`,
- further receives are disallowed. If *how* is :const:`SHUT_WR`, further sends
- are disallowed. If *how* is :const:`SHUT_RDWR`, further sends and receives are
- disallowed.
-
-Note that there are no methods :meth:`read` or :meth:`write`; use :meth:`recv`
-and :meth:`send` without *flags* argument instead.
-
-Socket objects also have these (read-only) attributes that correspond to the
-values given to the :class:`socket` constructor.
-
-
-.. attribute:: socket.family
-
- The socket family.
-
- .. versionadded:: 2.5
-
-
-.. attribute:: socket.type
-
- The socket type.
-
- .. versionadded:: 2.5
-
-
-.. attribute:: socket.proto
-
- The socket protocol.
-
- .. versionadded:: 2.5
-
-
-.. _socket-example:
-
-Example
--------
-
-Here are four minimal example programs using the TCP/IP protocol: a server that
-echoes all data that it receives back (servicing only one client), and a client
-using it. Note that a server must perform the sequence :func:`socket`,
-:meth:`bind`, :meth:`listen`, :meth:`accept` (possibly repeating the
-:meth:`accept` to service more than one client), while a client only needs the
-sequence :func:`socket`, :meth:`connect`. Also note that the server does not
-:meth:`send`/:meth:`recv` on the socket it is listening on but on the new
-socket returned by :meth:`accept`.
-
-The first two examples support IPv4 only. ::
-
- # Echo server program
- import socket
-
- HOST = '' # Symbolic name meaning the local host
- PORT = 50007 # Arbitrary non-privileged port
- s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
- s.bind((HOST, PORT))
- s.listen(1)
- conn, addr = s.accept()
- print 'Connected by', addr
- while 1:
- data = conn.recv(1024)
- if not data: break
- conn.send(data)
- conn.close()
-
-::
-
- # Echo client program
- import socket
-
- HOST = 'daring.cwi.nl' # The remote host
- PORT = 50007 # The same port as used by the server
- s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
- s.connect((HOST, PORT))
- s.send('Hello, world')
- data = s.recv(1024)
- s.close()
- print 'Received', repr(data)
-
-The next two examples are identical to the above two, but support both IPv4 and
-IPv6. The server side will listen to the first address family available (it
-should listen to both instead). On most of IPv6-ready systems, IPv6 will take
-precedence and the server may not accept IPv4 traffic. The client side will try
-to connect to the all addresses returned as a result of the name resolution, and
-sends traffic to the first one connected successfully. ::
-
- # Echo server program
- import socket
- import sys
-
- HOST = '' # Symbolic name meaning the local host
- PORT = 50007 # Arbitrary non-privileged port
- s = None
- for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, socket.SOCK_STREAM, 0, socket.AI_PASSIVE):
- af, socktype, proto, canonname, sa = res
- try:
- s = socket.socket(af, socktype, proto)
- except socket.error, msg:
- s = None
- continue
- try:
- s.bind(sa)
- s.listen(1)
- except socket.error, msg:
- s.close()
- s = None
- continue
- break
- if s is None:
- print 'could not open socket'
- sys.exit(1)
- conn, addr = s.accept()
- print 'Connected by', addr
- while 1:
- data = conn.recv(1024)
- if not data: break
- conn.send(data)
- conn.close()
-
-::
-
- # Echo client program
- import socket
- import sys
-
- HOST = 'daring.cwi.nl' # The remote host
- PORT = 50007 # The same port as used by the server
- s = None
- for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, socket.SOCK_STREAM):
- af, socktype, proto, canonname, sa = res
- try:
- s = socket.socket(af, socktype, proto)
- except socket.error, msg:
- s = None
- continue
- try:
- s.connect(sa)
- except socket.error, msg:
- s.close()
- s = None
- continue
- break
- if s is None:
- print 'could not open socket'
- sys.exit(1)
- s.send('Hello, world')
- data = s.recv(1024)
- s.close()
- print 'Received', repr(data)
-
+\r
+:mod:`socket` --- Low-level networking interface\r
+================================================\r
+\r
+.. module:: socket\r
+ :synopsis: Low-level networking interface.\r
+\r
+\r
+This module provides access to the BSD *socket* interface. It is available on\r
+all modern Unix systems, Windows, Mac OS X, BeOS, OS/2, and probably additional\r
+platforms.\r
+\r
+.. note::\r
+\r
+ Some behavior may be platform dependent, since calls are made to the operating\r
+ system socket APIs.\r
+\r
+For an introduction to socket programming (in C), see the following papers: An\r
+Introductory 4.3BSD Interprocess Communication Tutorial, by Stuart Sechrest and\r
+An Advanced 4.3BSD Interprocess Communication Tutorial, by Samuel J. Leffler et\r
+al, both in the UNIX Programmer's Manual, Supplementary Documents 1 (sections\r
+PS1:7 and PS1:8). The platform-specific reference material for the various\r
+socket-related system calls are also a valuable source of information on the\r
+details of socket semantics. For Unix, refer to the manual pages; for Windows,\r
+see the WinSock (or Winsock 2) specification. For IPv6-ready APIs, readers may\r
+want to refer to :rfc:`2553` titled Basic Socket Interface Extensions for IPv6.\r
+\r
+.. index:: object: socket\r
+\r
+The Python interface is a straightforward transliteration of the Unix system\r
+call and library interface for sockets to Python's object-oriented style: the\r
+:func:`socket` function returns a :dfn:`socket object` whose methods implement\r
+the various socket system calls. Parameter types are somewhat higher-level than\r
+in the C interface: as with :meth:`read` and :meth:`write` operations on Python\r
+files, buffer allocation on receive operations is automatic, and buffer length\r
+is implicit on send operations.\r
+\r
+Socket addresses are represented as follows: A single string is used for the\r
+:const:`AF_UNIX` address family. A pair ``(host, port)`` is used for the\r
+:const:`AF_INET` address family, where *host* is a string representing either a\r
+hostname in Internet domain notation like ``'daring.cwi.nl'`` or an IPv4 address\r
+like ``'100.50.200.5'``, and *port* is an integral port number. For\r
+:const:`AF_INET6` address family, a four-tuple ``(host, port, flowinfo,\r
+scopeid)`` is used, where *flowinfo* and *scopeid* represents ``sin6_flowinfo``\r
+and ``sin6_scope_id`` member in :const:`struct sockaddr_in6` in C. For\r
+:mod:`socket` module methods, *flowinfo* and *scopeid* can be omitted just for\r
+backward compatibility. Note, however, omission of *scopeid* can cause problems\r
+in manipulating scoped IPv6 addresses. Other address families are currently not\r
+supported. The address format required by a particular socket object is\r
+automatically selected based on the address family specified when the socket\r
+object was created.\r
+\r
+For IPv4 addresses, two special forms are accepted instead of a host address:\r
+the empty string represents :const:`INADDR_ANY`, and the string\r
+``'<broadcast>'`` represents :const:`INADDR_BROADCAST`. The behavior is not\r
+available for IPv6 for backward compatibility, therefore, you may want to avoid\r
+these if you intend to support IPv6 with your Python programs.\r
+\r
+If you use a hostname in the *host* portion of IPv4/v6 socket address, the\r
+program may show a nondeterministic behavior, as Python uses the first address\r
+returned from the DNS resolution. The socket address will be resolved\r
+differently into an actual IPv4/v6 address, depending on the results from DNS\r
+resolution and/or the host configuration. For deterministic behavior use a\r
+numeric address in *host* portion.\r
+\r
+.. versionadded:: 2.5\r
+ AF_NETLINK sockets are represented as pairs ``pid, groups``.\r
+\r
+All errors raise exceptions. The normal exceptions for invalid argument types\r
+and out-of-memory conditions can be raised; errors related to socket or address\r
+semantics raise the error :exc:`socket.error`.\r
+\r
+Non-blocking mode is supported through :meth:`setblocking`. A generalization of\r
+this based on timeouts is supported through :meth:`settimeout`.\r
+\r
+The module :mod:`socket` exports the following constants and functions:\r
+\r
+\r
+.. exception:: error\r
+\r
+ .. index:: module: errno\r
+\r
+ This exception is raised for socket-related errors. The accompanying value is\r
+ either a string telling what went wrong or a pair ``(errno, string)``\r
+ representing an error returned by a system call, similar to the value\r
+ accompanying :exc:`os.error`. See the module :mod:`errno`, which contains names\r
+ for the error codes defined by the underlying operating system.\r
+\r
+ .. versionchanged:: 2.6\r
+ :exc:`socket.error` is now a child class of :exc:`IOError`.\r
+\r
+\r
+.. exception:: herror\r
+\r
+ This exception is raised for address-related errors, i.e. for functions that use\r
+ *h_errno* in the C API, including :func:`gethostbyname_ex` and\r
+ :func:`gethostbyaddr`.\r
+\r
+ The accompanying value is a pair ``(h_errno, string)`` representing an error\r
+ returned by a library call. *string* represents the description of *h_errno*, as\r
+ returned by the :cfunc:`hstrerror` C function.\r
+\r
+\r
+.. exception:: gaierror\r
+\r
+ This exception is raised for address-related errors, for :func:`getaddrinfo` and\r
+ :func:`getnameinfo`. The accompanying value is a pair ``(error, string)``\r
+ representing an error returned by a library call. *string* represents the\r
+ description of *error*, as returned by the :cfunc:`gai_strerror` C function. The\r
+ *error* value will match one of the :const:`EAI_\*` constants defined in this\r
+ module.\r
+\r
+\r
+.. exception:: timeout\r
+\r
+ This exception is raised when a timeout occurs on a socket which has had\r
+ timeouts enabled via a prior call to :meth:`settimeout`. The accompanying value\r
+ is a string whose value is currently always "timed out".\r
+\r
+ .. versionadded:: 2.3\r
+\r
+\r
+.. data:: AF_UNIX\r
+ AF_INET\r
+ AF_INET6\r
+\r
+ These constants represent the address (and protocol) families, used for the\r
+ first argument to :func:`socket`. If the :const:`AF_UNIX` constant is not\r
+ defined then this protocol is unsupported.\r
+\r
+\r
+.. data:: SOCK_STREAM\r
+ SOCK_DGRAM\r
+ SOCK_RAW\r
+ SOCK_RDM\r
+ SOCK_SEQPACKET\r
+\r
+ These constants represent the socket types, used for the second argument to\r
+ :func:`socket`. (Only :const:`SOCK_STREAM` and :const:`SOCK_DGRAM` appear to be\r
+ generally useful.)\r
+\r
+\r
+.. data:: SO_*\r
+ SOMAXCONN\r
+ MSG_*\r
+ SOL_*\r
+ IPPROTO_*\r
+ IPPORT_*\r
+ INADDR_*\r
+ IP_*\r
+ IPV6_*\r
+ EAI_*\r
+ AI_*\r
+ NI_*\r
+ TCP_*\r
+\r
+ Many constants of these forms, documented in the Unix documentation on sockets\r
+ and/or the IP protocol, are also defined in the socket module. They are\r
+ generally used in arguments to the :meth:`setsockopt` and :meth:`getsockopt`\r
+ methods of socket objects. In most cases, only those symbols that are defined\r
+ in the Unix header files are defined; for a few symbols, default values are\r
+ provided.\r
+\r
+.. data:: SIO_*\r
+ RCVALL_*\r
+ \r
+ Constants for Windows' WSAIoctl(). The constants are used as arguments to the\r
+ :meth:`ioctl` method of socket objects.\r
+ \r
+ .. versionadded:: 2.6\r
+\r
+\r
+.. data:: has_ipv6\r
+\r
+ This constant contains a boolean value which indicates if IPv6 is supported on\r
+ this platform.\r
+\r
+ .. versionadded:: 2.3\r
+\r
+\r
+.. function:: create_connection(address[, timeout])\r
+\r
+ Connects to the *address* received (as usual, a ``(host, port)`` pair), with an\r
+ optional timeout for the connection. Especially useful for higher-level\r
+ protocols, it is not normally used directly from application-level code.\r
+ Passing the optional *timeout* parameter will set the timeout on the socket\r
+ instance (if it is not given or ``None``, the global default timeout setting is\r
+ used).\r
+\r
+ .. versionadded:: 2.6\r
+\r
+\r
+.. function:: getaddrinfo(host, port[, family[, socktype[, proto[, flags]]]])\r
+\r
+ Resolves the *host*/*port* argument, into a sequence of 5-tuples that contain\r
+ all the necessary argument for the sockets manipulation. *host* is a domain\r
+ name, a string representation of IPv4/v6 address or ``None``. *port* is a string\r
+ service name (like ``'http'``), a numeric port number or ``None``.\r
+\r
+ The rest of the arguments are optional and must be numeric if specified. For\r
+ *host* and *port*, by passing either an empty string or ``None``, you can pass\r
+ ``NULL`` to the C API. The :func:`getaddrinfo` function returns a list of\r
+ 5-tuples with the following structure:\r
+\r
+ ``(family, socktype, proto, canonname, sockaddr)``\r
+\r
+ *family*, *socktype*, *proto* are all integer and are meant to be passed to the\r
+ :func:`socket` function. *canonname* is a string representing the canonical name\r
+ of the *host*. It can be a numeric IPv4/v6 address when :const:`AI_CANONNAME` is\r
+ specified for a numeric *host*. *sockaddr* is a tuple describing a socket\r
+ address, as described above. See the source for :mod:`socket` and other\r
+ library modules for a typical usage of the function.\r
+\r
+ .. versionadded:: 2.2\r
+\r
+\r
+.. function:: getfqdn([name])\r
+\r
+ Return a fully qualified domain name for *name*. If *name* is omitted or empty,\r
+ it is interpreted as the local host. To find the fully qualified name, the\r
+ hostname returned by :func:`gethostbyaddr` is checked, then aliases for the\r
+ host, if available. The first name which includes a period is selected. In\r
+ case no fully qualified domain name is available, the hostname as returned by\r
+ :func:`gethostname` is returned.\r
+\r
+ .. versionadded:: 2.0\r
+\r
+\r
+.. function:: gethostbyname(hostname)\r
+\r
+ Translate a host name to IPv4 address format. The IPv4 address is returned as a\r
+ string, such as ``'100.50.200.5'``. If the host name is an IPv4 address itself\r
+ it is returned unchanged. See :func:`gethostbyname_ex` for a more complete\r
+ interface. :func:`gethostbyname` does not support IPv6 name resolution, and\r
+ :func:`getaddrinfo` should be used instead for IPv4/v6 dual stack support.\r
+\r
+\r
+.. function:: gethostbyname_ex(hostname)\r
+\r
+ Translate a host name to IPv4 address format, extended interface. Return a\r
+ triple ``(hostname, aliaslist, ipaddrlist)`` where *hostname* is the primary\r
+ host name responding to the given *ip_address*, *aliaslist* is a (possibly\r
+ empty) list of alternative host names for the same address, and *ipaddrlist* is\r
+ a list of IPv4 addresses for the same interface on the same host (often but not\r
+ always a single address). :func:`gethostbyname_ex` does not support IPv6 name\r
+ resolution, and :func:`getaddrinfo` should be used instead for IPv4/v6 dual\r
+ stack support.\r
+\r
+\r
+.. function:: gethostname()\r
+\r
+ Return a string containing the hostname of the machine where the Python\r
+ interpreter is currently executing. If you want to know the current machine's IP\r
+ address, you may want to use ``gethostbyname(gethostname())``. This operation\r
+ assumes that there is a valid address-to-host mapping for the host, and the\r
+ assumption does not always hold. Note: :func:`gethostname` doesn't always return\r
+ the fully qualified domain name; use ``getfqdn()`` (see above).\r
+\r
+\r
+.. function:: gethostbyaddr(ip_address)\r
+\r
+ Return a triple ``(hostname, aliaslist, ipaddrlist)`` where *hostname* is the\r
+ primary host name responding to the given *ip_address*, *aliaslist* is a\r
+ (possibly empty) list of alternative host names for the same address, and\r
+ *ipaddrlist* is a list of IPv4/v6 addresses for the same interface on the same\r
+ host (most likely containing only a single address). To find the fully qualified\r
+ domain name, use the function :func:`getfqdn`. :func:`gethostbyaddr` supports\r
+ both IPv4 and IPv6.\r
+\r
+\r
+.. function:: getnameinfo(sockaddr, flags)\r
+\r
+ Translate a socket address *sockaddr* into a 2-tuple ``(host, port)``. Depending\r
+ on the settings of *flags*, the result can contain a fully-qualified domain name\r
+ or numeric address representation in *host*. Similarly, *port* can contain a\r
+ string port name or a numeric port number.\r
+\r
+ .. versionadded:: 2.2\r
+\r
+\r
+.. function:: getprotobyname(protocolname)\r
+\r
+ Translate an Internet protocol name (for example, ``'icmp'``) to a constant\r
+ suitable for passing as the (optional) third argument to the :func:`socket`\r
+ function. This is usually only needed for sockets opened in "raw" mode\r
+ (:const:`SOCK_RAW`); for the normal socket modes, the correct protocol is chosen\r
+ automatically if the protocol is omitted or zero.\r
+\r
+\r
+.. function:: getservbyname(servicename[, protocolname])\r
+\r
+ Translate an Internet service name and protocol name to a port number for that\r
+ service. The optional protocol name, if given, should be ``'tcp'`` or\r
+ ``'udp'``, otherwise any protocol will match.\r
+\r
+\r
+.. function:: getservbyport(port[, protocolname])\r
+\r
+ Translate an Internet port number and protocol name to a service name for that\r
+ service. The optional protocol name, if given, should be ``'tcp'`` or\r
+ ``'udp'``, otherwise any protocol will match.\r
+\r
+\r
+.. function:: socket([family[, type[, proto]]])\r
+\r
+ Create a new socket using the given address family, socket type and protocol\r
+ number. The address family should be :const:`AF_INET` (the default),\r
+ :const:`AF_INET6` or :const:`AF_UNIX`. The socket type should be\r
+ :const:`SOCK_STREAM` (the default), :const:`SOCK_DGRAM` or perhaps one of the\r
+ other ``SOCK_`` constants. The protocol number is usually zero and may be\r
+ omitted in that case.\r
+\r
+\r
+.. function:: socketpair([family[, type[, proto]]])\r
+\r
+ Build a pair of connected socket objects using the given address family, socket\r
+ type, and protocol number. Address family, socket type, and protocol number are\r
+ as for the :func:`socket` function above. The default family is :const:`AF_UNIX`\r
+ if defined on the platform; otherwise, the default is :const:`AF_INET`.\r
+ Availability: Unix.\r
+\r
+ .. versionadded:: 2.4\r
+\r
+\r
+.. function:: fromfd(fd, family, type[, proto])\r
+\r
+ Duplicate the file descriptor *fd* (an integer as returned by a file object's\r
+ :meth:`fileno` method) and build a socket object from the result. Address\r
+ family, socket type and protocol number are as for the :func:`socket` function\r
+ above. The file descriptor should refer to a socket, but this is not checked ---\r
+ subsequent operations on the object may fail if the file descriptor is invalid.\r
+ This function is rarely needed, but can be used to get or set socket options on\r
+ a socket passed to a program as standard input or output (such as a server\r
+ started by the Unix inet daemon). The socket is assumed to be in blocking mode.\r
+ Availability: Unix.\r
+\r
+\r
+.. function:: ntohl(x)\r
+\r
+ Convert 32-bit positive integers from network to host byte order. On machines\r
+ where the host byte order is the same as network byte order, this is a no-op;\r
+ otherwise, it performs a 4-byte swap operation.\r
+\r
+\r
+.. function:: ntohs(x)\r
+\r
+ Convert 16-bit positive integers from network to host byte order. On machines\r
+ where the host byte order is the same as network byte order, this is a no-op;\r
+ otherwise, it performs a 2-byte swap operation.\r
+\r
+\r
+.. function:: htonl(x)\r
+\r
+ Convert 32-bit positive integers from host to network byte order. On machines\r
+ where the host byte order is the same as network byte order, this is a no-op;\r
+ otherwise, it performs a 4-byte swap operation.\r
+\r
+\r
+.. function:: htons(x)\r
+\r
+ Convert 16-bit positive integers from host to network byte order. On machines\r
+ where the host byte order is the same as network byte order, this is a no-op;\r
+ otherwise, it performs a 2-byte swap operation.\r
+\r
+\r
+.. function:: inet_aton(ip_string)\r
+\r
+ Convert an IPv4 address from dotted-quad string format (for example,\r
+ '123.45.67.89') to 32-bit packed binary format, as a string four characters in\r
+ length. This is useful when conversing with a program that uses the standard C\r
+ library and needs objects of type :ctype:`struct in_addr`, which is the C type\r
+ for the 32-bit packed binary this function returns.\r
+\r
+ If the IPv4 address string passed to this function is invalid,\r
+ :exc:`socket.error` will be raised. Note that exactly what is valid depends on\r
+ the underlying C implementation of :cfunc:`inet_aton`.\r
+\r
+ :func:`inet_aton` does not support IPv6, and :func:`getnameinfo` should be used\r
+ instead for IPv4/v6 dual stack support.\r
+\r
+\r
+.. function:: inet_ntoa(packed_ip)\r
+\r
+ Convert a 32-bit packed IPv4 address (a string four characters in length) to its\r
+ standard dotted-quad string representation (for example, '123.45.67.89'). This\r
+ is useful when conversing with a program that uses the standard C library and\r
+ needs objects of type :ctype:`struct in_addr`, which is the C type for the\r
+ 32-bit packed binary data this function takes as an argument.\r
+\r
+ If the string passed to this function is not exactly 4 bytes in length,\r
+ :exc:`socket.error` will be raised. :func:`inet_ntoa` does not support IPv6, and\r
+ :func:`getnameinfo` should be used instead for IPv4/v6 dual stack support.\r
+\r
+\r
+.. function:: inet_pton(address_family, ip_string)\r
+\r
+ Convert an IP address from its family-specific string format to a packed, binary\r
+ format. :func:`inet_pton` is useful when a library or network protocol calls for\r
+ an object of type :ctype:`struct in_addr` (similar to :func:`inet_aton`) or\r
+ :ctype:`struct in6_addr`.\r
+\r
+ Supported values for *address_family* are currently :const:`AF_INET` and\r
+ :const:`AF_INET6`. If the IP address string *ip_string* is invalid,\r
+ :exc:`socket.error` will be raised. Note that exactly what is valid depends on\r
+ both the value of *address_family* and the underlying implementation of\r
+ :cfunc:`inet_pton`.\r
+\r
+ Availability: Unix (maybe not all platforms).\r
+\r
+ .. versionadded:: 2.3\r
+\r
+\r
+.. function:: inet_ntop(address_family, packed_ip)\r
+\r
+ Convert a packed IP address (a string of some number of characters) to its\r
+ standard, family-specific string representation (for example, ``'7.10.0.5'`` or\r
+ ``'5aef:2b::8'``) :func:`inet_ntop` is useful when a library or network protocol\r
+ returns an object of type :ctype:`struct in_addr` (similar to :func:`inet_ntoa`)\r
+ or :ctype:`struct in6_addr`.\r
+\r
+ Supported values for *address_family* are currently :const:`AF_INET` and\r
+ :const:`AF_INET6`. If the string *packed_ip* is not the correct length for the\r
+ specified address family, :exc:`ValueError` will be raised. A\r
+ :exc:`socket.error` is raised for errors from the call to :func:`inet_ntop`.\r
+\r
+ Availability: Unix (maybe not all platforms).\r
+\r
+ .. versionadded:: 2.3\r
+\r
+\r
+.. function:: getdefaulttimeout()\r
+\r
+ Return the default timeout in floating seconds for new socket objects. A value\r
+ of ``None`` indicates that new socket objects have no timeout. When the socket\r
+ module is first imported, the default is ``None``.\r
+\r
+ .. versionadded:: 2.3\r
+\r
+\r
+.. function:: setdefaulttimeout(timeout)\r
+\r
+ Set the default timeout in floating seconds for new socket objects. A value of\r
+ ``None`` indicates that new socket objects have no timeout. When the socket\r
+ module is first imported, the default is ``None``.\r
+\r
+ .. versionadded:: 2.3\r
+\r
+\r
+.. data:: SocketType\r
+\r
+ This is a Python type object that represents the socket object type. It is the\r
+ same as ``type(socket(...))``.\r
+\r
+\r
+.. seealso::\r
+\r
+ Module :mod:`SocketServer`\r
+ Classes that simplify writing network servers.\r
+\r
+\r
+.. _socket-objects:\r
+\r
+Socket Objects\r
+--------------\r
+\r
+Socket objects have the following methods. Except for :meth:`makefile` these\r
+correspond to Unix system calls applicable to sockets.\r
+\r
+\r
+.. method:: socket.accept()\r
+\r
+ Accept a connection. The socket must be bound to an address and listening for\r
+ connections. The return value is a pair ``(conn, address)`` where *conn* is a\r
+ *new* socket object usable to send and receive data on the connection, and\r
+ *address* is the address bound to the socket on the other end of the connection.\r
+\r
+\r
+.. method:: socket.bind(address)\r
+\r
+ Bind the socket to *address*. The socket must not already be bound. (The format\r
+ of *address* depends on the address family --- see above.)\r
+\r
+ .. note::\r
+\r
+ This method has historically accepted a pair of parameters for :const:`AF_INET`\r
+ addresses instead of only a tuple. This was never intentional and is no longer\r
+ available in Python 2.0 and later.\r
+\r
+\r
+.. method:: socket.close()\r
+\r
+ Close the socket. All future operations on the socket object will fail. The\r
+ remote end will receive no more data (after queued data is flushed). Sockets are\r
+ automatically closed when they are garbage-collected.\r
+\r
+\r
+.. method:: socket.connect(address)\r
+\r
+ Connect to a remote socket at *address*. (The format of *address* depends on the\r
+ address family --- see above.)\r
+\r
+ .. note::\r
+\r
+ This method has historically accepted a pair of parameters for :const:`AF_INET`\r
+ addresses instead of only a tuple. This was never intentional and is no longer\r
+ available in Python 2.0 and later.\r
+\r
+\r
+.. method:: socket.connect_ex(address)\r
+\r
+ Like ``connect(address)``, but return an error indicator instead of raising an\r
+ exception for errors returned by the C-level :cfunc:`connect` call (other\r
+ problems, such as "host not found," can still raise exceptions). The error\r
+ indicator is ``0`` if the operation succeeded, otherwise the value of the\r
+ :cdata:`errno` variable. This is useful to support, for example, asynchronous\r
+ connects.\r
+\r
+ .. note::\r
+\r
+ This method has historically accepted a pair of parameters for :const:`AF_INET`\r
+ addresses instead of only a tuple. This was never intentional and is no longer\r
+ available in Python 2.0 and later.\r
+\r
+\r
+.. method:: socket.fileno()\r
+\r
+ Return the socket's file descriptor (a small integer). This is useful with\r
+ :func:`select.select`.\r
+\r
+ Under Windows the small integer returned by this method cannot be used where a\r
+ file descriptor can be used (such as :func:`os.fdopen`). Unix does not have\r
+ this limitation.\r
+\r
+\r
+.. method:: socket.getpeername()\r
+\r
+ Return the remote address to which the socket is connected. This is useful to\r
+ find out the port number of a remote IPv4/v6 socket, for instance. (The format\r
+ of the address returned depends on the address family --- see above.) On some\r
+ systems this function is not supported.\r
+\r
+\r
+.. method:: socket.getsockname()\r
+\r
+ Return the socket's own address. This is useful to find out the port number of\r
+ an IPv4/v6 socket, for instance. (The format of the address returned depends on\r
+ the address family --- see above.)\r
+\r
+\r
+.. method:: socket.getsockopt(level, optname[, buflen])\r
+\r
+ Return the value of the given socket option (see the Unix man page\r
+ :manpage:`getsockopt(2)`). The needed symbolic constants (:const:`SO_\*` etc.)\r
+ are defined in this module. If *buflen* is absent, an integer option is assumed\r
+ and its integer value is returned by the function. If *buflen* is present, it\r
+ specifies the maximum length of the buffer used to receive the option in, and\r
+ this buffer is returned as a string. It is up to the caller to decode the\r
+ contents of the buffer (see the optional built-in module :mod:`struct` for a way\r
+ to decode C structures encoded as strings).\r
+\r
+ \r
+.. method:: socket.ioctl(control, option)\r
+\r
+ :platform: Windows \r
+ \r
+ The `meth:ioctl` method is a limited interface to the WSAIoctl system\r
+ interface. Please refer to the MSDN documentation for more information.\r
+ \r
+ .. versionadded:: 2.6\r
+\r
+\r
+.. method:: socket.listen(backlog)\r
+\r
+ Listen for connections made to the socket. The *backlog* argument specifies the\r
+ maximum number of queued connections and should be at least 1; the maximum value\r
+ is system-dependent (usually 5).\r
+\r
+\r
+.. method:: socket.makefile([mode[, bufsize]])\r
+\r
+ .. index:: single: I/O control; buffering\r
+\r
+ Return a :dfn:`file object` associated with the socket. (File objects are\r
+ described in :ref:`bltin-file-objects`.) The file object\r
+ references a :cfunc:`dup`\ ped version of the socket file descriptor, so the\r
+ file object and socket object may be closed or garbage-collected independently.\r
+ The socket must be in blocking mode (it can not have a timeout). The optional\r
+ *mode* and *bufsize* arguments are interpreted the same way as by the built-in\r
+ :func:`file` function.\r
+\r
+\r
+.. method:: socket.recv(bufsize[, flags])\r
+\r
+ Receive data from the socket. The return value is a string representing the\r
+ data received. The maximum amount of data to be received at once is specified\r
+ by *bufsize*. See the Unix manual page :manpage:`recv(2)` for the meaning of\r
+ the optional argument *flags*; it defaults to zero.\r
+\r
+ .. note::\r
+\r
+ For best match with hardware and network realities, the value of *bufsize*\r
+ should be a relatively small power of 2, for example, 4096.\r
+\r
+\r
+.. method:: socket.recvfrom(bufsize[, flags])\r
+\r
+ Receive data from the socket. The return value is a pair ``(string, address)``\r
+ where *string* is a string representing the data received and *address* is the\r
+ address of the socket sending the data. See the Unix manual page\r
+ :manpage:`recv(2)` for the meaning of the optional argument *flags*; it defaults\r
+ to zero. (The format of *address* depends on the address family --- see above.)\r
+\r
+\r
+.. method:: socket.recvfrom_into(buffer[, nbytes[, flags]])\r
+\r
+ Receive data from the socket, writing it into *buffer* instead of creating a\r
+ new string. The return value is a pair ``(nbytes, address)`` where *nbytes* is\r
+ the number of bytes received and *address* is the address of the socket sending\r
+ the data. See the Unix manual page :manpage:`recv(2)` for the meaning of the\r
+ optional argument *flags*; it defaults to zero. (The format of *address*\r
+ depends on the address family --- see above.)\r
+\r
+ .. versionadded:: 2.5\r
+\r
+\r
+.. method:: socket.recv_into(buffer[, nbytes[, flags]])\r
+\r
+ Receive up to *nbytes* bytes from the socket, storing the data into a buffer\r
+ rather than creating a new string. If *nbytes* is not specified (or 0),\r
+ receive up to the size available in the given buffer. See the Unix manual page\r
+ :manpage:`recv(2)` for the meaning of the optional argument *flags*; it defaults\r
+ to zero.\r
+\r
+ .. versionadded:: 2.5\r
+\r
+\r
+.. method:: socket.send(string[, flags])\r
+\r
+ Send data to the socket. The socket must be connected to a remote socket. The\r
+ optional *flags* argument has the same meaning as for :meth:`recv` above.\r
+ Returns the number of bytes sent. Applications are responsible for checking that\r
+ all data has been sent; if only some of the data was transmitted, the\r
+ application needs to attempt delivery of the remaining data.\r
+\r
+\r
+.. method:: socket.sendall(string[, flags])\r
+\r
+ Send data to the socket. The socket must be connected to a remote socket. The\r
+ optional *flags* argument has the same meaning as for :meth:`recv` above.\r
+ Unlike :meth:`send`, this method continues to send data from *string* until\r
+ either all data has been sent or an error occurs. ``None`` is returned on\r
+ success. On error, an exception is raised, and there is no way to determine how\r
+ much data, if any, was successfully sent.\r
+\r
+\r
+.. method:: socket.sendto(string[, flags], address)\r
+\r
+ Send data to the socket. The socket should not be connected to a remote socket,\r
+ since the destination socket is specified by *address*. The optional *flags*\r
+ argument has the same meaning as for :meth:`recv` above. Return the number of\r
+ bytes sent. (The format of *address* depends on the address family --- see\r
+ above.)\r
+\r
+\r
+.. method:: socket.setblocking(flag)\r
+\r
+ Set blocking or non-blocking mode of the socket: if *flag* is 0, the socket is\r
+ set to non-blocking, else to blocking mode. Initially all sockets are in\r
+ blocking mode. In non-blocking mode, if a :meth:`recv` call doesn't find any\r
+ data, or if a :meth:`send` call can't immediately dispose of the data, a\r
+ :exc:`error` exception is raised; in blocking mode, the calls block until they\r
+ can proceed. ``s.setblocking(0)`` is equivalent to ``s.settimeout(0)``;\r
+ ``s.setblocking(1)`` is equivalent to ``s.settimeout(None)``.\r
+\r
+\r
+.. method:: socket.settimeout(value)\r
+\r
+ Set a timeout on blocking socket operations. The *value* argument can be a\r
+ nonnegative float expressing seconds, or ``None``. If a float is given,\r
+ subsequent socket operations will raise an :exc:`timeout` exception if the\r
+ timeout period *value* has elapsed before the operation has completed. Setting\r
+ a timeout of ``None`` disables timeouts on socket operations.\r
+ ``s.settimeout(0.0)`` is equivalent to ``s.setblocking(0)``;\r
+ ``s.settimeout(None)`` is equivalent to ``s.setblocking(1)``.\r
+\r
+ .. versionadded:: 2.3\r
+\r
+\r
+.. method:: socket.gettimeout()\r
+\r
+ Return the timeout in floating seconds associated with socket operations, or\r
+ ``None`` if no timeout is set. This reflects the last call to\r
+ :meth:`setblocking` or :meth:`settimeout`.\r
+\r
+ .. versionadded:: 2.3\r
+\r
+Some notes on socket blocking and timeouts: A socket object can be in one of\r
+three modes: blocking, non-blocking, or timeout. Sockets are always created in\r
+blocking mode. In blocking mode, operations block until complete. In\r
+non-blocking mode, operations fail (with an error that is unfortunately\r
+system-dependent) if they cannot be completed immediately. In timeout mode,\r
+operations fail if they cannot be completed within the timeout specified for the\r
+socket. The :meth:`setblocking` method is simply a shorthand for certain\r
+:meth:`settimeout` calls.\r
+\r
+Timeout mode internally sets the socket in non-blocking mode. The blocking and\r
+timeout modes are shared between file descriptors and socket objects that refer\r
+to the same network endpoint. A consequence of this is that file objects\r
+returned by the :meth:`makefile` method must only be used when the socket is in\r
+blocking mode; in timeout or non-blocking mode file operations that cannot be\r
+completed immediately will fail.\r
+\r
+Note that the :meth:`connect` operation is subject to the timeout setting, and\r
+in general it is recommended to call :meth:`settimeout` before calling\r
+:meth:`connect`.\r
+\r
+\r
+.. method:: socket.setsockopt(level, optname, value)\r
+\r
+ .. index:: module: struct\r
+\r
+ Set the value of the given socket option (see the Unix manual page\r
+ :manpage:`setsockopt(2)`). The needed symbolic constants are defined in the\r
+ :mod:`socket` module (:const:`SO_\*` etc.). The value can be an integer or a\r
+ string representing a buffer. In the latter case it is up to the caller to\r
+ ensure that the string contains the proper bits (see the optional built-in\r
+ module :mod:`struct` for a way to encode C structures as strings).\r
+\r
+\r
+.. method:: socket.shutdown(how)\r
+\r
+ Shut down one or both halves of the connection. If *how* is :const:`SHUT_RD`,\r
+ further receives are disallowed. If *how* is :const:`SHUT_WR`, further sends\r
+ are disallowed. If *how* is :const:`SHUT_RDWR`, further sends and receives are\r
+ disallowed.\r
+\r
+Note that there are no methods :meth:`read` or :meth:`write`; use :meth:`recv`\r
+and :meth:`send` without *flags* argument instead.\r
+\r
+Socket objects also have these (read-only) attributes that correspond to the\r
+values given to the :class:`socket` constructor.\r
+\r
+\r
+.. attribute:: socket.family\r
+\r
+ The socket family.\r
+\r
+ .. versionadded:: 2.5\r
+\r
+\r
+.. attribute:: socket.type\r
+\r
+ The socket type.\r
+\r
+ .. versionadded:: 2.5\r
+\r
+\r
+.. attribute:: socket.proto\r
+\r
+ The socket protocol.\r
+\r
+ .. versionadded:: 2.5\r
+\r
+\r
+.. _socket-example:\r
+\r
+Example\r
+-------\r
+\r
+Here are four minimal example programs using the TCP/IP protocol: a server that\r
+echoes all data that it receives back (servicing only one client), and a client\r
+using it. Note that a server must perform the sequence :func:`socket`,\r
+:meth:`bind`, :meth:`listen`, :meth:`accept` (possibly repeating the\r
+:meth:`accept` to service more than one client), while a client only needs the\r
+sequence :func:`socket`, :meth:`connect`. Also note that the server does not\r
+:meth:`send`/:meth:`recv` on the socket it is listening on but on the new\r
+socket returned by :meth:`accept`.\r
+\r
+The first two examples support IPv4 only. ::\r
+\r
+ # Echo server program\r
+ import socket\r
+\r
+ HOST = '' # Symbolic name meaning the local host\r
+ PORT = 50007 # Arbitrary non-privileged port\r
+ s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)\r
+ s.bind((HOST, PORT))\r
+ s.listen(1)\r
+ conn, addr = s.accept()\r
+ print 'Connected by', addr\r
+ while 1:\r
+ data = conn.recv(1024)\r
+ if not data: break\r
+ conn.send(data)\r
+ conn.close()\r
+\r
+::\r
+\r
+ # Echo client program\r
+ import socket\r
+\r
+ HOST = 'daring.cwi.nl' # The remote host\r
+ PORT = 50007 # The same port as used by the server\r
+ s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)\r
+ s.connect((HOST, PORT))\r
+ s.send('Hello, world')\r
+ data = s.recv(1024)\r
+ s.close()\r
+ print 'Received', repr(data)\r
+\r
+The next two examples are identical to the above two, but support both IPv4 and\r
+IPv6. The server side will listen to the first address family available (it\r
+should listen to both instead). On most of IPv6-ready systems, IPv6 will take\r
+precedence and the server may not accept IPv4 traffic. The client side will try\r
+to connect to the all addresses returned as a result of the name resolution, and\r
+sends traffic to the first one connected successfully. ::\r
+\r
+ # Echo server program\r
+ import socket\r
+ import sys\r
+\r
+ HOST = '' # Symbolic name meaning the local host\r
+ PORT = 50007 # Arbitrary non-privileged port\r
+ s = None\r
+ for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, socket.SOCK_STREAM, 0, socket.AI_PASSIVE):\r
+ af, socktype, proto, canonname, sa = res\r
+ try:\r
+ s = socket.socket(af, socktype, proto)\r
+ except socket.error, msg:\r
+ s = None\r
+ continue\r
+ try:\r
+ s.bind(sa)\r
+ s.listen(1)\r
+ except socket.error, msg:\r
+ s.close()\r
+ s = None\r
+ continue\r
+ break\r
+ if s is None:\r
+ print 'could not open socket'\r
+ sys.exit(1)\r
+ conn, addr = s.accept()\r
+ print 'Connected by', addr\r
+ while 1:\r
+ data = conn.recv(1024)\r
+ if not data: break\r
+ conn.send(data)\r
+ conn.close()\r
+\r
+::\r
+\r
+ # Echo client program\r
+ import socket\r
+ import sys\r
+\r
+ HOST = 'daring.cwi.nl' # The remote host\r
+ PORT = 50007 # The same port as used by the server\r
+ s = None\r
+ for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, socket.SOCK_STREAM):\r
+ af, socktype, proto, canonname, sa = res\r
+ try:\r
+ s = socket.socket(af, socktype, proto)\r
+ except socket.error, msg:\r
+ s = None\r
+ continue\r
+ try:\r
+ s.connect(sa)\r
+ except socket.error, msg:\r
+ s.close()\r
+ s = None\r
+ continue\r
+ break\r
+ if s is None:\r
+ print 'could not open socket'\r
+ sys.exit(1)\r
+ s.send('Hello, world')\r
+ data = s.recv(1024)\r
+ s.close()\r
+ print 'Received', repr(data)\r
+\r
+ \r
+The last example shows how to write a very simple network sniffer with raw\r
+sockets on Windows. The example requires administrator priviliges to modify\r
+the interface::\r
+\r
+ import socket\r
+\r
+ # the public network interface\r
+ HOST = socket.gethostbyname(socket.gethostname())\r
+ \r
+ # create a raw socket and bind it to the public interface\r
+ s = socket.socket(socket.AF_INET, socket.SOCK_RAW, socket.IPPROTO_IP)\r
+ s.bind((HOST, 0))\r
+ \r
+ # Include IP headers\r
+ s.setsockopt(socket.IPPROTO_IP, socket.IP_HDRINCL, 1)\r
+ \r
+ # receive all packages\r
+ s.ioctl(socket.SIO_RCVALL, socket.RCVALL_ON)\r
+ \r
+ # receive a package\r
+ print s.recvfrom(65565)\r
+ \r
+ # disabled promiscous mode\r
+ s.ioctl(socket.SIO_RCVALL, socket.RCVALL_OFF)\r
projects / python / commitdiff