Skip to content

bpo-12887 and bpo-14345: Document the availability and uses of the SO_ constants. Document SOL_SOCKET #3072

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 3 commits into from
Closed

bpo-12887 and bpo-14345: Document the availability and uses of the SO_ constants. Document SOL_SOCKET #3072

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
73cc260
bpo-12887: Document the availability and uses of the SO_ constants.
ammaraskar Aug 11, 2017
32ee0de
Fix simple issues found in code review
ammaraskar Aug 12, 2017
86cece8
Fix Linux availability version for SO_PEERSEC
ammaraskar Aug 12, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
278 changes: 277 additions & 1 deletion Doc/library/socket.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <https://msdn.microsoft.com/en-us/library/windows/desktop/ms740532(v=vs.85).aspx>`_.

.. 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) <https://msdn.microsoft.com/en-us/library/windows/desktop/ms740532(v=vs.85).aspx>`_

.. 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 <https://msdn.microsoft.com/en-us/library/windows/desktop/cc150667(v=vs.85).aspx>`_
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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It’s or it is


.. Availability: Linux, Windows `(non functional) <https://msdn.microsoft.com/en-us/library/windows/desktop/ms740532(v=vs.85).aspx>`_

.. 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) <https://msdn.microsoft.com/en-us/library/windows/desktop/ms740532(v=vs.85).aspx>`_

.. 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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

First sentence does not make sense. Perhaps you should have a comma (,) instead of the full stop (.)?

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 <https://www.ibm.com/support/knowledgecenter/en/ssw_i5_54/rzab6/coobd.htm>`_
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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don’t understand “passed on to able read call”. Perhaps do you mean something like “before the socket becomes readable” or “before they are returned by a read”?

Spelling: similarly

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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

According to Posix, the SNDLOWAT default depends on the implementation and protocol.


.. Availability: Linux, Windows `(non functional) <https://msdn.microsoft.com/en-us/library/windows/desktop/ms740532(v=vs.85).aspx>`_

.. 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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Extra l in will.

Is it worth clarifying that these timeouts (which raise EAGAIN etc) are independent of the settimeout mechanism (which raises socket.timeout for non-zero timeouts)?

will never time out. On Linux this is a `struct timeval`, on Windows this
is the time in milliseconds.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Struct timeval also measures time in milliseconds. Perhaps your point is that Windows accepts a DWORD rather than the structure?


.. 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I’m not familiar with either API, but it seems this only applies to PASSCRED, and PEERCRED returns credentials straight away.

There seems to be something missing with the reference to recvmsg. The end of that entry covers Python versions, platforms, and before that, receiving file descriptors with SCM_RIGHTS. But as I understand it, when using PASSCRED you would look for SCM_CREDENTIALS messages, with a different data structure. The first couple of paragraphs, about receiving anciliary messages in general, are more relevant.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah I'm not familiar with this API either, I'm just going to add an easily searchable keyword of ancillary message and point to recvmsg


.. 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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Where does this come from? What I found was SO_PASSSEC added to Linux 2.6.18 (https://repo.or.cz/linux-2.6-linus.git/commitdiff/877ce7c), and SO_PEERSEC to 2.6.2 (schwabe/tglx-history@da6e57a).

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Aah that's my mistake. I think 2.6.2 is the right number to include here. I came up with 2.6.13 because I was looking at the blame for sock.c here: https://github.com/torvalds/linux/blame/add459aa1afe05472abc96f6a29aefd0c84e73d6/net/core/sock.c

I scrolled to

case SO_PEERSEC:
    return security_socket_getpeersec_stream(sock, optval, optlen, len);

and saw "Linux-2.6.12-rc2" in the commit message. But it looks like that was a big commit for when Linux switched from bitkeeper to git.

But if we look at the commit that adds

case SO_PASSSEC:
    v.val = test_bit(SOCK_PASSSEC, &sock->flags) ? 1 : 0;
    break;

the commit message says "[AF_UNIX]: Datagram getpeersec" and we can find the same commit in the 2.6.2 changelogs here: https://www.kernel.org/pub/linux/kernel/v2.6/ChangeLog-2.6.2

So I think its safe to say both of these options are available on >= 2.6.2


.. 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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Extra s in processed.

According to my patch at https://bugs.python.org/issue27409 this was only added in 3.3 (or did I make a mistake?). See also https://hg.python.org/cpython/rev/6159311f0f44.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh I came to the 3.1 number by going to https://github.com/python/cpython/blob/master/Modules/socketmodule.c

Clicking the blame button and checking the tag in the commit. The tag says 3.1 but it looks like that is incorrect, since the README at the time says: This is Python version 3.3 alpha 0


.. 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually it can return the real protocol, e.g. IPPROTO_TCP, even when proto is zero.


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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The integer value normally does equal one of those enumeration members; it is just that the integer object is never an enumeration member.

value back you can use the AddressFamily enum. ::

>>> family = s.getsockopt(socket.SOL_SOCKET, socket.SO_DOMAIN)
>>> socket.AddressFamily(family)
<AddressFamily.AF_INET: 2>

Availability: Linux >= 2.6.32.

.. versionadded:: 3.6

.. data:: SO_*
SOMAXCONN
MSG_*
Expand All @@ -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
Expand Down