bpo-37345: Add formal UDPLITE support (GH-14258)

At the moment you can definitely use UDPLITE sockets on Linux systems, but it would be good if this support were formalized such that you can detect support at runtime easily.

At the moment, to make and use a UDPLITE socket requires something like the following code:

```
>>> import socket
>>> a = socket.socket(socket.AF_INET, socket.SOCK_DGRAM, 136)
>>> b = socket.socket(socket.AF_INET, socket.SOCK_DGRAM, 136)
>>> a.bind(('localhost', 44444))
>>> b.sendto(b'test'*256, ('localhost', 44444))
>>> b.setsockopt(136, 10, 16)
>>> b.sendto(b'test'*256, ('localhost', 44444))
>>> b.setsockopt(136, 10, 32)
>>> b.sendto(b'test'*256, ('localhost', 44444))
>>> b.setsockopt(136, 10, 64)
>>> b.sendto(b'test'*256, ('localhost', 44444))
```

If you look at this through Wireshark, you can see that the packets are different in that the checksums and checksum coverages change.

With the pull request that I am submitting momentarily, you could do the following code instead:

```
>>> import socket
>>> a = socket.socket(socket.AF_INET, socket.SOCK_DGRAM, socket.IPPROTO_UDPLITE)
>>> b = socket.socket(socket.AF_INET, socket.SOCK_DGRAM, socket.IPPROTO_UDPLITE)
>>> a.bind(('localhost', 44444))
>>> b.sendto(b'test'*256, ('localhost', 44444))
>>> b.set_send_checksum_coverage(16)
>>> b.sendto(b'test'*256, ('localhost', 44444))
>>> b.set_send_checksum_coverage(32)
>>> b.sendto(b'test'*256, ('localhost', 44444))
>>> b.set_send_checksum_coverage(64)
>>> b.sendto(b'test'*256, ('localhost', 44444))
```

One can also detect support for UDPLITE just by checking

```
>>> hasattr(socket, 'IPPROTO_UDPLITE')
```


https://bugs.python.org/issue37345

1 files changed, 17 insertions, 0 deletions

diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst
index e0dbbb4..f2e7949 100644
--- a/Doc/library/socket.rst
+++ b/Doc/library/socket.rst
@@ -200,6 +200,23 @@ created.  Socket addresses are represented as follows:
 
   .. versionadded:: 3.8
 
+- :const:`IPPROTO_UDPLITE` is a variant of UDP which allows you to specify
+  what portion of a packet is covered with the checksum. It adds two socket
+  options that you can change.
+  ``self.setsockopt(IPPROTO_UDPLITE, UDPLITE_SEND_CSCOV, length)`` will
+  change what portion of outgoing packets are covered by the checksum and
+  ``self.setsockopt(IPPROTO_UDPLITE, UDPLITE_RECV_CSCOV, length)`` will
+  filter out packets which cover too little of their data. In both cases
+  ``length`` should be in ``range(8, 2**16, 8)``.
+
+  Such a socket should be constructed with
+  ``socket(AF_INET, SOCK_DGRAM, IPPROTO_UDPLITE)`` for IPv4 or
+  ``socket(AF_INET6, SOCK_DGRAM, IPPROTO_UDPLITE)`` for IPv6.
+
+  .. availability:: Linux >= 2.6.20, FreeBSD >= 10.1-RELEASE
+
+  .. versionadded:: 3.9
+
 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