[docs] [issue34617] socket.recvfrom(): docs should warn about packet truncation when bufsize is insufficient

[Anees Ahmed]

New submission from Anees Ahmed <aneesahmedpro at gmail.com>:

When one is receiving UDP packets (socket.SOCK_DGRAM) using:

    socket.recvfrom(bufsize, flags)

the UDP packet payload is truncated if it was too big to fit into the buffer (decided by `bufsize` here).


This is documented in Linux Docs:

    All receive operations return only one packet.  When the packet is
    smaller than the passed buffer, only that much data is returned; when
    it is bigger, the packet is truncated and the MSG_TRUNC flag is set.
    MSG_WAITALL is not supported.

    Source: http://man7.org/linux/man-pages/man7/udp.7.html


This is also documented in Windows Docs:

    For message-oriented sockets, data is extracted from the first enqueued message, up to the size of the buffer specified. If the datagram or message is larger than the buffer specified, the buffer is filled with the first part of the datagram, and recvfrom generates the error WSAEMSGSIZE. For unreliable protocols (for example, UDP) the excess data is lost. For UDP if the packet received contains no data (empty), the return value from the recvfrom function function is zero.

    Source: https://docs.microsoft.com/en-us/windows/desktop/api/winsock2/nf-winsock2-recvfrom


** PYTHON DOCS DO NOT WARN ABOUT THIS AT ALL !!! **

The relevant portion of Python Docs is here: https://docs.python.org/3.7/library/socket.html#socket.socket.recvfrom


I, not knowing this simple fact when I started socket programming today, wasted half an hour finding out what was wrong. This is a very important piece of information that MUST be present in the Python Docs, even though it is present at Linux Docs and Windows Docs.


PROPOSED FIX
------------

Include the warning about packet truncation in the docs.

NOTE: I have only pointed out socket.recvfrom(), but there are other related functions too, e.g. socket.recvfrom_into(), which require the same warning in their docs.

----------
assignee: docs at python
components: Documentation
messages: 324901
nosy: Anees Ahmed, docs at python
priority: normal
severity: normal
status: open
title: socket.recvfrom(): docs should warn about packet truncation when bufsize is insufficient
type: enhancement
versions: Python 2.7, Python 3.4, Python 3.5, Python 3.6, Python 3.7, Python 3.8

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue34617>
_______________________________________