--- rest25/library/socket.rst	2008-12-19 16:58:07.000000000 +0900
+++ rest262/library/socket.rst	2009-04-05 05:02:09.000000000 +0900
@@ -1,38 +1,38 @@
 
 :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, MacOS, BeOS, OS/2, and probably additional
+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.
+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
@@ -57,44 +57,68 @@
 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.
 
 
@@ -149,62 +173,87 @@
           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 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:
+   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 integer and are meant to be passed to the
+   *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 the :mod:`httplib` and other
+   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
+   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
@@ -218,30 +267,33 @@
    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 ``gethostbyaddr(gethostname())`` (see
-   below).
+   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.
 
@@ -280,35 +332,24 @@
 
 
 .. 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:: ssl(sock[, keyfile, certfile])
-
-   Initiate a SSL connection over the socket *sock*. *keyfile* is the name of a PEM
-   formatted file that contains your private key. *certfile* is a PEM formatted
-   certificate chain file. On success, a new :class:`SSLObject` is returned.
-
-   .. warning::
-
-      This does not do any certificate verification!
-
-
 .. 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])
@@ -317,48 +358,48 @@
    :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 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.
+   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 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.
+   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 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.
+   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 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.
+   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
@@ -539,64 +580,97 @@
 .. 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`, "File Objects.") The file object
+   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. The optional *mode* and *bufsize* arguments
-   are interpreted the same way as by the built-in :func:`file` function; see
-   "Built-in Functions" (section :ref:`built-in-funcs`) for more information.
+   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.  The optional *flags* argument has the
-   same meaning as for :meth:`recv` above. (The format of *address* depends on the
-   address family --- see above.)
+   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])
@@ -643,29 +717,29 @@
 
 
 .. 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.  In blocking mode, operations block until complete.  In
-blocking mode, operations fail (with an error that is unfortunately system-
+non-blocking mode, operations fail (with an error that is unfortunately
-dependent) if they cannot be completed immediately.  In timeout mode, operations
+system-dependent) if they cannot be completed immediately.  In timeout mode,
-fail if they cannot be completed within the timeout specified for the socket.
+operations fail if they cannot be completed within the timeout specified for the
-The :meth:`setblocking` method is simply a shorthand for certain
+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`.
@@ -709,77 +783,44 @@
    The socket type.
 
    .. versionadded:: 2.5
 
 
 .. attribute:: socket.proto
 
    The socket protocol.
 
    .. versionadded:: 2.5
 
 
-.. _ssl-objects:
-
-SSL Objects
------------
-
-SSL objects have the following methods.
-
-
-.. method:: XXX Class.write(s)
-
-   Writes the string *s* to the on the object's SSL connection. The return value is
-   the number of bytes written.
-
-
-.. method:: XXX Class.read([n])
-
-   If *n* is provided, read *n* bytes from the SSL connection, otherwise read until
-   EOF. The return value is a string of the bytes read.
-
-
-.. method:: XXX Class.server()
-
-   Returns a string containing the ASN.1 distinguished name identifying the
-   server's certificate.  (See below for an example showing what distinguished
-   names look like.)
-
-
-.. method:: XXX Class.issuer()
-
-   Returns a string containing the ASN.1 distinguished name identifying the issuer
-   of the server's certificate.
-
-
 .. _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
+   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()
 
@@ -799,108 +840,98 @@
 
 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
+   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):
+   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)
+           s = socket.socket(af, socktype, proto)
        except socket.error, msg:
-   	s = None
-   	continue
+           s = None
+           continue
        try:
-   	s.bind(sa)
-   	s.listen(1)
+           s.bind(sa)
+           s.listen(1)
        except socket.error, msg:
-   	s.close()
-   	s = None
-   	continue
+           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)
+           s = socket.socket(af, socktype, proto)
        except socket.error, msg:
-   	s = None
-   	continue
+           s = None
+           continue
        try:
-   	s.connect(sa)
+           s.connect(sa)
        except socket.error, msg:
-   	s.close()
-   	s = None
-   	continue
+           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)
 
-This example connects to an SSL server, prints the  server and issuer's
-distinguished names, sends some bytes, and reads part of the response::
-
-   import socket
 
-   s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
-   s.connect(('www.verisign.com', 443))
+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::
 
-   ssl_sock = socket.ssl(s)
-
-   print repr(ssl_sock.server())
-   print repr(ssl_sock.issuer())
+   import socket
 
-   # Set a simple HTTP request -- use httplib in actual code.
-   ssl_sock.write("""GET / HTTP/1.0\r
-   Host: www.verisign.com\r\n\r\n""")
+   # the public network interface
+   HOST = socket.gethostbyname(socket.gethostname())
 
-   # Read a chunk of data.  Will not necessarily
-   # read all the data returned by the server.
-   data = ssl_sock.read()
+   # 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))
 
-   # Note that you need to close the underlying socket, not the SSL object.
-   del ssl_sock
-   s.close()
+   # Include IP headers
+   s.setsockopt(socket.IPPROTO_IP, socket.IP_HDRINCL, 1)
 
-At this writing, this SSL example prints the following output (line breaks
-inserted for readability)::
+   # receive all packages
+   s.ioctl(socket.SIO_RCVALL, socket.RCVALL_ON)
 
-   '/C=US/ST=California/L=Mountain View/
-    O=VeriSign, Inc./OU=Production Services/
-    OU=Terms of use at www.verisign.com/rpa (c)00/
-    CN=www.verisign.com'
-   '/O=VeriSign Trust Network/OU=VeriSign, Inc./
-    OU=VeriSign International Server CA - Class 3/
-    OU=www.verisign.com/CPS Incorp.by Ref. LIABILITY LTD.(c)97 VeriSign'
+   # receive a package
+   print s.recvfrom(65565)
 
+   # disabled promiscuous mode
+   s.ioctl(socket.SIO_RCVALL, socket.RCVALL_OFF)
