From: Antoine Pitrou <solipsis@pitrou.net>
Date: Wed, 4 Dec 2013 20:15:24 +0000 (+0100)
Subject: Merge socket doc changes from 3.3
X-Git-Tag: v3.4.0b2~341
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=f9c54944dfe2f2594748a0a92938e4765c0c5900;p=thirdparty%2FPython%2Fcpython.git

Merge socket doc changes from 3.3
---

f9c54944dfe2f2594748a0a92938e4765c0c5900
diff --cc Doc/library/socket.rst
index b01238c29dd4,3bd1c31f496d..c2e9f008bb42
--- a/Doc/library/socket.rst
+++ b/Doc/library/socket.rst
@@@ -305,6 -297,43 +312,57 @@@ Constant
     this platform.
  
  
+ Functions
+ ^^^^^^^^^
+ 
+ Creating sockets
+ ''''''''''''''''
+ 
+ The following functions all create :ref:`socket objects <socket-objects>`.
+ 
+ 
 -.. function:: socket([family[, type[, proto]]])
++.. function:: socket(family=AF_INET, type=SOCK_STREAM, proto=0, fileno=None)
+ 
+    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`, :const:`AF_UNIX`, :const:`AF_CAN` or :const:`AF_RDS`. The
+    socket type should be :const:`SOCK_STREAM` (the default),
+    :const:`SOCK_DGRAM`, :const:`SOCK_RAW` or perhaps one of the other ``SOCK_``
 -   constants. The protocol number is usually zero and may be omitted in that
 -   case or :const:`CAN_RAW` in case the address family is :const:`AF_CAN`.
++   constants. The protocol number is usually zero and may be omitted or in the
++   case where the address family is :const:`AF_CAN` the protocol should be one
++   of :const:`CAN_RAW` or :const:`CAN_BCM`.
++
++   The newly created socket is :ref:`non-inheritable <fd_inheritance>`.
+ 
+    .. versionchanged:: 3.3
+       The AF_CAN family was added.
+       The AF_RDS family was added.
+ 
++   .. versionchanged:: 3.4
++       The CAN_BCM protocol was added.
++
++   .. versionchanged:: 3.4
++      The returned socket is now non-inheritable.
++
+ 
+ .. 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.
+ 
++   The newly created sockets are :ref:`non-inheritable <fd_inheritance>`.
++
+    .. versionchanged:: 3.2
+       The returned socket objects now support the whole socket API, rather
+       than a subset.
+ 
++   .. versionchanged:: 3.4
++      The returned sockets are now non-inheritable.
++
+ 
  .. function:: create_connection(address[, timeout[, source_address]])
  
     Connect to a TCP service listening on the Internet *address* (a 2-tuple
@@@ -331,6 -360,40 +389,45 @@@
        support for the :keyword:`with` statement was added.
  
  
 -.. function:: fromfd(fd, family, type[, proto])
++.. function:: fromfd(fd, family, type, proto=0)
+ 
+    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.
+ 
++   The newly created socket is :ref:`non-inheritable <fd_inheritance>`.
++
++   .. versionchanged:: 3.4
++      The returned socket is now non-inheritable.
++
+ 
+ .. function:: fromshare(data)
+ 
+    Instantiate a socket from data obtained from the :meth:`socket.share`
+    method.  The socket is assumed to be in blocking mode.
+ 
+    Availability: Windows.
+ 
+    .. versionadded:: 3.3
+ 
+ 
+ .. data:: SocketType
+ 
+    This is a Python type object that represents the socket object type. It is the
+    same as ``type(socket(...))``.
+ 
+ 
+ Other functions
+ '''''''''''''''
+ 
+ The :mod:`socket` module also offers various network-related services:
+ 
+ 
  .. function:: getaddrinfo(host, port, family=0, type=0, proto=0, flags=0)
  
     Translate the *host*/*port* argument into a sequence of 5-tuples that contain