luo980/libuv
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: clarify UDP errors and recvmmsg

Browse Source 
PR-URL: https://github.com/libuv/libuv/pull/3061
Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Santiago Gimeno <santiago.gimeno@gmail.com>
This commit is contained in:
Ethel Weston 2020-12-03 09:38:07 +08:00 committed by Santiago Gimeno
parent 9c6cec803a
commit 9cc2667f76
No known key found for this signature in database
GPG Key ID: F28C3C8DA33C03BE
1 changed files with 7 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
docs/src/udp.rst
View File

@ -73,7 +73,8 @@ Data types
* `nread`: Number of bytes that have been received. * `nread`: Number of bytes that have been received.
0 if there is no more data to read. Note that 0 may also mean that an 0 if there is no more data to read. Note that 0 may also mean that an
empty datagram was received (in this case `addr` is not NULL). < 0 if empty datagram was received (in this case `addr` is not NULL). < 0 if
a transmission error was detected. a transmission error was detected; if using :man:`recvmmsg(2)` no more
chunks will be received and the buffer can be freed safely.
* `buf`: :c:type:`uv_buf_t` with the received data. * `buf`: :c:type:`uv_buf_t` with the received data.
* `addr`: ``struct sockaddr*`` containing the address of the sender. * `addr`: ``struct sockaddr*`` containing the address of the sender.
Can be NULL. Valid for the duration of the callback only. Can be NULL. Valid for the duration of the callback only.
@ -84,10 +85,11 @@ Data types
on error. on error.
When using :man:`recvmmsg(2)`, chunks will have the `UV_UDP_MMSG_CHUNK` flag set, When using :man:`recvmmsg(2)`, chunks will have the `UV_UDP_MMSG_CHUNK` flag set,
those must not be freed. There will be a final callback with `nread` set to 0, those must not be freed. If no errors occur, there will be a final callback with
`addr` set to NULL and the buffer pointing at the initially allocated data with `nread` set to 0, `addr` set to NULL and the buffer pointing at the initially
the `UV_UDP_MMSG_CHUNK` flag cleared and the `UV_UDP_MMSG_FREE` flag set. allocated data with the `UV_UDP_MMSG_CHUNK` flag cleared and the `UV_UDP_MMSG_FREE`
The callee can now safely free the provided buffer. flag set. If a UDP socket error occurs, `nread` will be < 0. In either scenario,
the callee can now safely free the provided buffer.
.. versionchanged:: 1.40.0 added the `UV_UDP_MMSG_FREE` flag. .. versionchanged:: 1.40.0 added the `UV_UDP_MMSG_FREE` flag.