From 73cc260505ff8ce240cbe5c5dc7123c02c6a6d74 Mon Sep 17 00:00:00 2001 From: Ammar Askar Date: Fri, 11 Aug 2017 01:10:31 -0400 Subject: [PATCH 1/3] bpo-12887: Document the availability and uses of the SO_ constants. bpo-14345: Document SOL_SOCKET --- Doc/library/socket.rst | 278 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 277 insertions(+), 1 deletion(-) diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst index 8af6bc5439beea..da00f2f439f8ef 100644 --- a/Doc/library/socket.rst +++ b/Doc/library/socket.rst @@ -277,6 +277,283 @@ Constants .. versionadded:: 3.2 +Socket level options +'''''''''''''''''''' + +These constants are passed to :meth:`socket.setsockopt` and :meth:`socket.getsockopt` +with a level of :const:`SOL_SOCKET` to set and get socket settings. Their availability +and behavior is dependent upon the underlying OS. Basic descriptions of each option are +documented below but your OS's documentation will be far more reliable. The following +table serves a basic compatibility guide. + +Unless otherwise noted, these options are available on Linux versions >= 2.3, +FreeBSD >= 2 and Windows >= 2000. + +======================= =========== =========== ================ +Socket Option Linux FreeBSD Windows +======================= =========== =========== ================ +**SO_DEBUG** ✓ ✓ ✓ [1]_ +**SO_ACCEPTCONN** ✓ ✓ ✓ +**SO_REUSEADDR** ✓ ✓ ✓ +**SO_EXCLUSIVEADDRUSE** ✓ +**SO_KEEPALIVE** ✓ ✓ ✓ +**SO_DONTROUTE** ✓ ✓ ✓ [1]_ +**SO_BROADCAST** ✓ ✓ ✓ >= Vista +**SO_USELOOPBACK** ✓ ✓ >= Vista [1]_ +**SO_LINGER** ✓ ✓ ✓ +**SO_OOBINLINE** ✓ ✓ ✓ +**SO_REUSEPORT** ✓ >= 3.9 ✓ +**SO_SNDBUF** ✓ ✓ ✓ +**SO_RCVBUF** ✓ ✓ ✓ +**SO_SNDLOWAT** ✓ ✓ ✓ [1]_ +**SO_RCVLOWAT** ✓ ✓ ✓ [1]_ +**SO_SNDTIMEO** ✓ ✓ ✓ +**SO_RCVTIMEO** ✓ ✓ ✓ +**SO_ERROR** ✓ ✓ ✓ +**SO_TYPE** ✓ ✓ ✓ +**SO_SETFIB** ✓ >= 7.1 +**SO_PASSCRED** ✓ +**SO_PEERCRED** ✓ +**SO_PASSSEC** ✓ >= 2.6.18 +**SO_PEERSEC** ✓ >= 2.6.18 +**SO_BINDTODEVICE** ✓ +**SO_PRIORITY** ✓ +**SO_MARK** ✓ >= 2.6.25 +**SO_DOMAIN** ✓ >= 2.6.32 +**SO_PROTOCOL** ✓ >= 2.6.32 ✓ >= 8.3 +======================= =========== =========== ================ + +.. [1] On Windows these options exist purely for compatibility + and are `not functional `_. + +.. data:: SOL_SOCKET + + This is the level parameter passed to :meth:`socket.setsockopt` + and :meth:`socket.getsockopt` to change socket level parameters. + + For example, this is how to change a socket's sending buffer size. :: + + >>> s.getsockopt(socket.SOL_SOCKET, socket.SO_SNDBUF) + 16384 + >>> s.setsockopt(socket.SOL_SOCKET, socket.SO_SNDBUF, 2048) + >>> s.getsockopt(socket.SOL_SOCKET, socket.SO_SNDBUF) + 2048 + +.. data:: SO_DEBUG + + Setting this option to 1 on a socket causes it to print out debugging + information into the kernel log. (Viewable with dmesg) + +.. Availability: Linux, Windows `(non functional) `_ + +.. data:: SO_ACCEPTCONN + + Returns 1 if the socket is marked to accept connections with + :meth:`socket.listen`. This option is read only. + +.. Availability: Linux, Windows + +.. data:: SO_REUSEADDR + + Allows a socket to be able to bind to an address that was previously + bound to. When a socket shuts down, whether by virtue of the program + exiting or an explicit call to shut it down, it takes the OS some time + to terminate existing connections and perform the proper shut down + procedure. SO_REUSEADDR allows bypassing of this behavior and permits + another socket to be able to bind to the address. + +.. Availability: Linux, Windows + +.. data:: SO_EXCLUSIVEADDRUSE + + Allows overriding SO_REUSEADDR behavior for exclusive access to an + address and port for high availability services. + + .. seealso:: + + `Microsoft's documentation `_ + on this option. + +.. Availability: Windows + +.. data:: SO_KEEPALIVE + + Set to 1 to enable sending of keep-alive packets on certain types of + sockets. + +.. Availability: Linux, Windows + +.. data:: SO_DONTROUTE + + Indicates that packets sent through this socket should be routed + through the interface its bound to. + +.. Availability: Linux, Windows `(non functional) `_ + +.. data:: SO_BROADCAST + + This option may be set to 1 to enable broadcasting messages, if + supported by the protocol. Note that IPV6 (:const:`AF_INET6`) does + not support broadcasting. + +.. Availability: Linux, Windows >= Vista. + +.. data:: SO_USELOOPBACK + +.. Availability: FreeBSD, Windows >= Vista `(non functional) `_ + +.. data:: SO_LINGER + + When a socket is set to linger. A call to :meth:`socket.close` or + :meth:`socket.shutdown` will not return until all queued messages + for the socket have been successfully sent or the linger timeout + is reached. If the socket is closed due to the program exiting, it + will linger in the background. + + The value for this option is a struct on most operating systems. + Consult your OS documentation for the struct's details. + +.. Availability: Linux, Windows + +.. data:: SO_OOBINLINE + + Allows receiving of out of band data in the normal stream. + + .. seealso:: + + `Out-of-band data `_ + for an in depth explanation. + +.. Availability: Linux, Windows + +.. data:: SO_REUSEPORT + +.. Availability: Linux >= 3.9 (for TCP/UDP) + +.. data:: SO_SNDBUF + SO_RCVBUF + + Sets the size of the sending and receiving buffers for this socket in + bytes. Most operating systems impose an upper limit on the size of + these buffers. + +.. Availability: Linux, Windows + +.. data:: + SO_RCVLOWAT + SO_SNDLOWAT + + SO_RCVLOWAT sets the minimum number of bytes that must be present in + the socket's internal receive buffer before they are passed on to able + read call. SO_SNDLOWAT similiary sets the minimum bytes before data is + sent from the send buffer to the socket protocol. + + SO_SNDLOWAT is read-only on Linux and SO_RCVLOWAT is read-only on + Linux versions below 2.4. + + Both these values default to 1. + +.. Availability: Linux, Windows `(non functional) `_ + +.. data:: SO_RCVTIMEO + SO_SNDTIMEO + + Specifies the amount of time send and receive calls for this socket willl + block before timing out. The default timeout of zero means that operations + will never time out. On Linux this is a `struct timeval`, on Windows this + is the time in milliseconds. + +.. Availability: Linux, Windows + +.. data:: SO_ERROR + + Gets and resets the pending socket error. + +.. Availability: Linux, Windows + +.. data:: SO_TYPE + + Gets the type of the socket. This type corresponds to the type as + defined in the :func:`socket.socket` function. Examples include + :const:`SOCK_STREAM` and :const:`SOCK_DGRAM`. + +.. Availability: Linux, Windows + +.. data:: SO_SETFIB + + Sets the FIB (routing table) for the socket. + + Availability: FreeBSD >= 7.1 + + .. versionadded:: 3.1 + +.. data:: SO_PASSCRED + SO_PEERCRED + + Allows for the passing of SCM credentials over unix sockets. + See the end of :func:`socket.recvmsg` for details. + + .. versionadded:: 3.3 + +.. Availability: Linux + +.. data:: SO_PASSSEC + SO_PEERSEC + + Allows for the passing of security contexts over unix sockets. + + .. versionadded:: 3.6 + +.. Availability: Linux >= 2.6.13 + +.. data:: SO_BINDTODEVICE + + Binds a socket to a particular network interface device like "eth0", + When bound, only packets received from that particular device are + processsed by the socket. + + .. versionadded:: 3.1 + +.. Availability: Linux + +.. data:: SO_PRIORITY + + Sets the protocol-defined priority for each packet sent on this socket. + Packets with higher priority may be processed first depending on the + queueing mechanism of the network interface. + + .. versionadded:: 3.4 + +.. Availability: Linux + +.. data:: SO_MARK + + Sets the mark on each packet sent through this socket. This may be used + for routing or packet filtering. + + .. versionadded:: 3.5 + +.. Availability: Linux >= 2.6.25 + +.. data:: SO_DOMAIN + SO_PROTOCOL + + Passing ``SO_DOMAIN`` to :meth:`socket.getsockopt` allows for the retrival + of the ``family`` value as defined in the :func:`socket.socket` function. + ``SO_PROTOCOL`` returns the ``proto`` value. Both these options are read only. + + The value returned for the ``family`` is an integer and not one of the + friendly constants above like :const:`AF_INET`. In order to get a constant + value back you can use the AddressFamily enum. :: + + >>> family = s.getsockopt(socket.SOL_SOCKET, socket.SO_DOMAIN) + >>> socket.AddressFamily(family) + + + Availability: Linux >= 2.6.32. + + .. versionadded:: 3.6 + .. data:: SO_* SOMAXCONN MSG_* @@ -300,7 +577,6 @@ Constants provided. .. versionchanged:: 3.6 - ``SO_DOMAIN``, ``SO_PROTOCOL``, ``SO_PEERSEC``, ``SO_PASSSEC``, ``TCP_USER_TIMEOUT``, ``TCP_CONGESTION`` were added. .. versionchanged:: 3.7 From 32ee0de72ca70fc581afe42572e6652951ad0a5a Mon Sep 17 00:00:00 2001 From: Ammar Askar Date: Sat, 12 Aug 2017 09:34:03 -0400 Subject: [PATCH 2/3] Fix simple issues found in code review --- Doc/library/socket.rst | 49 +++++++++++++++++++++++------------------- 1 file changed, 27 insertions(+), 22 deletions(-) diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst index da00f2f439f8ef..833ce96d4680bf 100644 --- a/Doc/library/socket.rst +++ b/Doc/library/socket.rst @@ -359,14 +359,14 @@ Socket Option Linux FreeBSD Windows bound to. When a socket shuts down, whether by virtue of the program exiting or an explicit call to shut it down, it takes the OS some time to terminate existing connections and perform the proper shut down - procedure. SO_REUSEADDR allows bypassing of this behavior and permits + procedure. ``SO_REUSEADDR`` allows bypassing of this behavior and permits another socket to be able to bind to the address. .. Availability: Linux, Windows .. data:: SO_EXCLUSIVEADDRUSE - Allows overriding SO_REUSEADDR behavior for exclusive access to an + Allows overriding ``SO_REUSEADDR`` behavior for exclusive access to an address and port for high availability services. .. seealso:: @@ -386,7 +386,7 @@ Socket Option Linux FreeBSD Windows .. data:: SO_DONTROUTE Indicates that packets sent through this socket should be routed - through the interface its bound to. + through the interface it is bound to. .. Availability: Linux, Windows `(non functional) `_ @@ -404,8 +404,8 @@ Socket Option Linux FreeBSD Windows .. data:: SO_LINGER - When a socket is set to linger. A call to :meth:`socket.close` or - :meth:`socket.shutdown` will not return until all queued messages + When a socket is set to linger, a call to :meth:`~socket.close` or + :meth:`~socket.shutdown` will not return until all queued messages for the socket have been successfully sent or the linger timeout is reached. If the socket is closed due to the program exiting, it will linger in the background. @@ -443,25 +443,26 @@ Socket Option Linux FreeBSD Windows SO_RCVLOWAT SO_SNDLOWAT - SO_RCVLOWAT sets the minimum number of bytes that must be present in - the socket's internal receive buffer before they are passed on to able - read call. SO_SNDLOWAT similiary sets the minimum bytes before data is + ``SO_RCVLOWAT`` sets the minimum number of bytes that must be present in + the socket's internal receive buffer before they are returned by a + read call. ``SO_SNDLOWAT`` similiary sets the minimum bytes before data is sent from the send buffer to the socket protocol. SO_SNDLOWAT is read-only on Linux and SO_RCVLOWAT is read-only on Linux versions below 2.4. - Both these values default to 1. - .. Availability: Linux, Windows `(non functional) `_ .. data:: SO_RCVTIMEO SO_SNDTIMEO - Specifies the amount of time send and receive calls for this socket willl - block before timing out. The default timeout of zero means that operations - will never time out. On Linux this is a `struct timeval`, on Windows this - is the time in milliseconds. + Specifies the amount of time send and receive calls for this socket will + block before timing out. The default timeout of zero means that operations + will never time out. + + This is independent of :meth:`~socket.settimeout`. + + On Linux this is a `struct timeval`, on Windows this is an integer. .. Availability: Linux, Windows @@ -490,8 +491,8 @@ Socket Option Linux FreeBSD Windows .. data:: SO_PASSCRED SO_PEERCRED - Allows for the passing of SCM credentials over unix sockets. - See the end of :func:`socket.recvmsg` for details. + Allows for the passing of SCM credentials over unix sockets. These + are passed as ancillary messages which can be received using :func:`~socket.recvmsg` .. versionadded:: 3.3 @@ -512,7 +513,7 @@ Socket Option Linux FreeBSD Windows When bound, only packets received from that particular device are processsed by the socket. - .. versionadded:: 3.1 + .. versionadded:: 3.3 .. Availability: Linux @@ -538,12 +539,16 @@ Socket Option Linux FreeBSD Windows .. data:: SO_DOMAIN SO_PROTOCOL - Passing ``SO_DOMAIN`` to :meth:`socket.getsockopt` allows for the retrival + Passing ``SO_DOMAIN`` to :meth:`~socket.getsockopt` allows for the retrival of the ``family`` value as defined in the :func:`socket.socket` function. - ``SO_PROTOCOL`` returns the ``proto`` value. Both these options are read only. - - The value returned for the ``family`` is an integer and not one of the - friendly constants above like :const:`AF_INET`. In order to get a constant + ``SO_PROTOCOL`` returns the ``proto`` value. The protocol value can be the + exact protocol used such as ``IPPROTO_TCP`` even if 0 was passed in to specify + the default protocol. + + Both these options are read only. + + The value returned for the ``family`` is an integer which is the value of + the constants above like :const:`AF_INET`. In order to get the const name value back you can use the AddressFamily enum. :: >>> family = s.getsockopt(socket.SOL_SOCKET, socket.SO_DOMAIN) From 86cece89d5c6452a92004af0276147187034d41f Mon Sep 17 00:00:00 2001 From: Ammar Askar Date: Sat, 12 Aug 2017 15:15:07 -0400 Subject: [PATCH 3/3] Fix Linux availability version for SO_PEERSEC --- Doc/library/socket.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst index 833ce96d4680bf..1e3a872a2455c5 100644 --- a/Doc/library/socket.rst +++ b/Doc/library/socket.rst @@ -314,8 +314,8 @@ Socket Option Linux FreeBSD Windows **SO_SETFIB** ✓ >= 7.1 **SO_PASSCRED** ✓ **SO_PEERCRED** ✓ -**SO_PASSSEC** ✓ >= 2.6.18 -**SO_PEERSEC** ✓ >= 2.6.18 +**SO_PASSSEC** ✓ >= 2.6.2 +**SO_PEERSEC** ✓ >= 2.6.2 **SO_BINDTODEVICE** ✓ **SO_PRIORITY** ✓ **SO_MARK** ✓ >= 2.6.25 @@ -457,11 +457,11 @@ Socket Option Linux FreeBSD Windows SO_SNDTIMEO Specifies the amount of time send and receive calls for this socket will - block before timing out. The default timeout of zero means that operations + block before timing out. The default timeout of zero means that operations will never time out. This is independent of :meth:`~socket.settimeout`. - + On Linux this is a `struct timeval`, on Windows this is an integer. .. Availability: Linux, Windows @@ -505,7 +505,7 @@ Socket Option Linux FreeBSD Windows .. versionadded:: 3.6 -.. Availability: Linux >= 2.6.13 +.. Availability: Linux >= 2.6.2 .. data:: SO_BINDTODEVICE @@ -542,12 +542,12 @@ Socket Option Linux FreeBSD Windows Passing ``SO_DOMAIN`` to :meth:`~socket.getsockopt` allows for the retrival of the ``family`` value as defined in the :func:`socket.socket` function. ``SO_PROTOCOL`` returns the ``proto`` value. The protocol value can be the - exact protocol used such as ``IPPROTO_TCP`` even if 0 was passed in to specify + exact protocol used such as ``IPPROTO_TCP`` even if 0 was passed in to specify the default protocol. - + Both these options are read only. - The value returned for the ``family`` is an integer which is the value of + The value returned for the ``family`` is an integer which is the value of the constants above like :const:`AF_INET`. In order to get the const name value back you can use the AddressFamily enum. ::