MCL/sf/adapt/qemu: comparison symbian-qemu-0.9.1-12/python-2.6.1/Doc/library/socket.rst

equal deleted inserted replaced

-:ffa851df0825
+:2fb8b9db1c86
+: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:`3493` 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``.
+.. versionadded:: 2.6
+Linux-only support for TIPC is also available using the :const:`AF_TIPC`
+address family. TIPC is an open, non-IP based networked protocol designed
+for use in clustered computer environments.  Addresses are represented by a
+tuple, and the fields depend on the address type. The general tuple form is
+``(addr_type, v1, v2, v3 [, scope])``, where:
+- *addr_type* is one of TIPC_ADDR_NAMESEQ, TIPC_ADDR_NAME, or
+TIPC_ADDR_ID.
+- *scope* is one of TIPC_ZONE_SCOPE, TIPC_CLUSTER_SCOPE, and
+TIPC_NODE_SCOPE.
+- If *addr_type* is TIPC_ADDR_NAME, then *v1* is the server type, *v2* is
+the port identifier, and *v3* should be 0.
+If *addr_type* is TIPC_ADDR_NAMESEQ, then *v1* is the server type, *v2*
+is the lower port number, and *v3* is the upper port number.
+If *addr_type* is TIPC_ADDR_ID, then *v1* is the node, *v2* is the
+reference, and *v3* should be set to 0.
+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:: SIO_*
+RCVALL_*
+Constants for Windows' WSAIoctl(). The constants are used as arguments to the
+:meth:`ioctl` method of socket objects.
+.. versionadded:: 2.6
+.. data:: TIPC_*
+TIPC related constants, matching the ones exported by the C socket API. See
+the TIPC documentation for more information.
+.. versionadded:: 2.6
+.. 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])
+Convenience function.  Connect to *address* (a 2-tuple ``(host, port)``),
+and return the socket object.  Passing the optional *timeout* parameter will
+set the timeout on the socket instance before attempting to connect.  If no
+*timeout* is supplied, the global default timeout setting returned by
+:func:`getdefaulttimeout` 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 arguments for creating the corresponding socket. *host* is a domain
+name, a string representation of an IPv4/v6 address or ``None``. *port* is a string
+service name such as ``'http'``, a numeric port number or ``None``.
+The rest of the arguments are optional and must be numeric if specified.
+By passing ``None`` as the value of *host* and *port*, , 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 integers 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, followed by 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.ioctl(control, option)
+:platform: Windows
+The :meth:`ioctl` method is a limited interface to the WSAIoctl system
+interface. Please refer to the MSDN documentation for more information.
+.. versionadded:: 2.6
+.. 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 all available interfaces
+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 = None               # Symbolic name meaning all available interfaces
+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)
+The last example shows how to write a very simple network sniffer with raw
+sockets on Windows. The example requires administrator privileges to modify
+the interface::
+import socket
+# the public network interface
+HOST = socket.gethostbyname(socket.gethostname())
+# create a raw socket and bind it to the public interface
+s = socket.socket(socket.AF_INET, socket.SOCK_RAW, socket.IPPROTO_IP)
+s.bind((HOST, 0))
+# Include IP headers
+s.setsockopt(socket.IPPROTO_IP, socket.IP_HDRINCL, 1)
+# receive all packages
+s.ioctl(socket.SIO_RCVALL, socket.RCVALL_ON)
+# receive a package
+print s.recvfrom(65565)
+# disabled promiscuous mode
+s.ioctl(socket.SIO_RCVALL, socket.RCVALL_OFF)