New submission from Anees Ahmed <aneesahmed...@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@python
components: Documentation
messages: 324901
nosy: Anees Ahmed, docs@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 <rep...@bugs.python.org>
<https://bugs.python.org/issue34617>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe:
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
