diff --git a/sys/include/net/sock.h b/sys/include/net/sock.h index 339a89a132..ebf9481c06 100644 --- a/sys/include/net/sock.h +++ b/sys/include/net/sock.h @@ -245,19 +245,6 @@ struct _sock_tl_ep { uint16_t port; /**< transport layer port (in host byte order) */ }; -/** - * @brief Releases the stack-internal buffer space provided by the - * `sock_*_recv_buf()` functions. - * - * @see - * - @ref sock_dtls_recv_buf() - * - @ref sock_ip_recv_buf() - * - @ref sock_udp_recv_buf() - * - * @param[in] buf_ctx Stack-internal buffer context to release. - */ -void sock_recv_buf_free(void *buf_ctx); - #ifdef __cplusplus } #endif diff --git a/sys/include/net/sock/dtls.h b/sys/include/net/sock/dtls.h index 54b098d1df..8ed6e50d21 100644 --- a/sys/include/net/sock/dtls.h +++ b/sys/include/net/sock/dtls.h @@ -615,9 +615,11 @@ ssize_t sock_dtls_recv(sock_dtls_t *sock, sock_dtls_session_t *remote, * Cannot be NULL. * @param[out] data Pointer to a stack-internal buffer space containing the * received data. - * @param[out] buf_ctx Stack-internal buffer context. Must be used to release - * the buffer space using @ref sock_recv_buf_free() after - * the data in @p data was handled. + * @param[in,out] buf_ctx Stack-internal buffer context. If it points to a + * `NULL` pointer, the stack returns a new buffer space for + * a new packet. If it does not point to a `NULL` pointer, + * an existing context is assumed to get a next segment in + * a buffer. * @param[in] timeout Receive timeout in microseconds. * If 0 and no data is available, the function returns * immediately. @@ -626,7 +628,13 @@ ssize_t sock_dtls_recv(sock_dtls_t *sock, sock_dtls_session_t *remote, * * @note Function may block if data is not available and @p timeout != 0 * - * @return The number of bytes received on success + * @note Function blocks if no packet is currently waiting. + * + * @return The number of bytes received on success. May not be the complete + * payload. Continue calling with the returned @p buf_ctx to get more + * buffers until result is 0 or an error. + * @return 0, if no received data is available, but everything is in order. + * If @p buf_ctx was provided, it was released. * @return -EADDRNOTAVAIL, if the local endpoint of @p sock is not set. * @return -EAGAIN, if @p timeout is `0` and no data is available. * @return -EINVAL, if @p remote is invalid or @p sock is not properly diff --git a/sys/include/net/sock/ip.h b/sys/include/net/sock/ip.h index d19139ec0a..0b3deb9bdc 100644 --- a/sys/include/net/sock/ip.h +++ b/sys/include/net/sock/ip.h @@ -435,9 +435,11 @@ ssize_t sock_ip_recv(sock_ip_t *sock, void *data, size_t max_len, * @param[in] sock A raw IPv4/IPv6 sock object. * @param[out] data Pointer to a stack-internal buffer space containing the * received data. - * @param[out] buf_ctx Stack-internal buffer context. Must be used to release - * the buffer space using @ref sock_recv_buf_free() after - * the data in @p data was handled. + * @param[in,out] buf_ctx Stack-internal buffer context. If it points to a + * `NULL` pointer, the stack returns a new buffer space + * for a new packet. If it does not point to a `NULL` + * pointer, an existing context is assumed to get a next + * segment in a buffer. * @param[in] timeout Timeout for receive in microseconds. * If 0 and no data is available, the function returns * immediately. @@ -448,8 +450,11 @@ ssize_t sock_ip_recv(sock_ip_t *sock, void *data, size_t max_len, * * @note Function blocks if no packet is currently waiting. * - * @return The number of bytes received on success. + * @return The number of bytes received on success. May not be the complete + * payload. Continue calling with the returned `buf_ctx` to get more + * buffers until result is 0 or an error. * @return 0, if no received data is available, but everything is in order. + * If @p buf_ctx was provided, it was released. * @return -EADDRNOTAVAIL, if local of @p sock is not given. * @return -EAGAIN, if @p timeout is `0` and no data is available. * @return -EINVAL, if @p remote is invalid or @p sock is not properly diff --git a/sys/include/net/sock/udp.h b/sys/include/net/sock/udp.h index f0cadad467..1fe7124c03 100644 --- a/sys/include/net/sock/udp.h +++ b/sys/include/net/sock/udp.h @@ -422,9 +422,11 @@ ssize_t sock_udp_recv(sock_udp_t *sock, void *data, size_t max_len, * @param[in] sock A UDP sock object. * @param[out] data Pointer to a stack-internal buffer space containing the * received data. - * @param[out] buf_ctx Stack-internal buffer context. Must be used to release - * the buffer space using @ref sock_recv_buf_free() after - * the data in @p data was handled. + * @param[in,out] buf_ctx Stack-internal buffer context. If it points to a + * `NULL` pointer, the stack returns a new buffer space + * for a new packet. If it does not point to a `NULL` + * pointer, an existing context is assumed to get a next + * segment in a buffer. * @param[in] timeout Timeout for receive in microseconds. * If 0 and no data is available, the function returns * immediately. @@ -435,8 +437,11 @@ ssize_t sock_udp_recv(sock_udp_t *sock, void *data, size_t max_len, * * @note Function blocks if no packet is currently waiting. * - * @return The number of bytes received on success. + * @return The number of bytes received on success. May not be the complete + * payload. Continue calling with the returned `buf_ctx` to get more + * buffers until result is 0 or an error. * @return 0, if no received data is available, but everything is in order. + * If @p buf_ctx was provided, it was released. * @return -EADDRNOTAVAIL, if local of @p sock is not given. * @return -EAGAIN, if @p timeout is `0` and no data is available. * @return -EINVAL, if @p remote is invalid or @p sock is not properly