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

[aneesahmed777]

BPO	34617
Nosy	@aneesahmed777

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2018-09-09.22:21:11.308>
labels = ['3.8', 'type-feature', '3.7', 'docs']
title = 'socket.recvfrom(): docs should warn about packet truncation when bufsize is insufficient'
updated_at = <Date 2018-09-09.22:21:11.308>
user = 'https://github.com/aneesahmed777'

bugs.python.org fields:

activity = <Date 2018-09-09.22:21:11.308>
actor = 'Anees Ahmed'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2018-09-09.22:21:11.308>
creator = 'Anees Ahmed'
dependencies = []
files = []
hgrepos = []
issue_num = 34617
keywords = []
message_count = 1.0
messages = ['324901']
nosy_count = 2.0
nosy_names = ['docs@python', 'Anees Ahmed']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue34617'
versions = ['Python 2.7', 'Python 3.4', 'Python 3.5', 'Python 3.6', 'Python 3.7', 'Python 3.8']

[aneesahmed777]

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.