commit 18464c833e7cbd38acc5b3201cd7e08ffd3609ec
parent aa3146708088f2763474c08067084b6910039959
Author: Evgeny Grin (Karlson2k) <k2k@drgrin.dev>
Date: Fri, 30 Oct 2026 19:14:55 +0100
MHD_upgraded_recv(): allowed NULL for zero-sized buffers, clarified doxy
Diffstat:
4 files changed, 41 insertions(+), 17 deletions(-)
diff --git a/doc/manual/responses.inc b/doc/manual/responses.inc
@@ -1054,15 +1054,20 @@ The function will return if one of the following happens:
@item a network error occured.
@end itemize
+If @var{recv_buf_size} is zero, no data is received.
+For a valid @var{urh}, the function returns @code{MHD_SC_OK} immediately
+and stores zero in the variable pointed to by @var{received_size}.
+
@table @var
@item urh
identifies the HTTP-upgraded connection handle
@item recv_buf_size
-size of the @var{recv_buf}
+size of the @var{recv_buf}, must be zero if @var{recv_buf} is @code{NULL}
@item recv_buf
-application buffer where MHD should place received data
+application buffer where MHD should place received data, can be @code{NULL}
+if @var{recv_buf_size} is zero
@item received_size
pointer where to return the number of bytes received
@@ -1076,9 +1081,10 @@ the function may return earlier if waiting is interrupted for some reason.
Returns:
@table @code
@item MHD_SC_OK
-if any data was received (check the @var{received_size}) or
+if any data was received (check the @var{received_size}),
remote shut down send side (indicated by @var{received_size}
-set to zero);
+set to zero while @var{recv_buf_size} is not zero) or
+@var{recv_buf_size} is zero;
@item MHD_SC_UPGRADED_NET_TIMEOUT
if no data was received but and timeout was reached;
diff --git a/src/include/microhttpd2.h b/src/include/microhttpd2.h
@@ -7456,9 +7456,15 @@ MHD_FN_PAR_IN_SIZE_ (6, 5);
* + timeout reached,
* + network error occurs
*
+ * If @a recv_buf_size is zero, no data are received.
+ * For a valid @a urh, the function returns #MHD_SC_OK immediately and stores
+ * zero in the variable pointed to by @a received_size.
+ *
* @param urh the HTTP-Upgraded handle
- * @param recv_buf_size the size of the @a recv_buf
- * @param recv_buf the buffer to receive the data
+ * @param recv_buf_size the size of the @a recv_buf,
+ * must be zero if @a recv_buf is NULL
+ * @param recv_buf the buffer to receive the data,
+ * can be NULL if @a recv_buf_size is zero
* @param received_size the pointer to variable to get amount of received data
* @param max_wait_millisec the maximum wait time for the data,
* non-blocking operation if set to zero,
@@ -7466,9 +7472,10 @@ MHD_FN_PAR_IN_SIZE_ (6, 5);
* #MHD_WAIT_INDEFINITELY,
* the function may return earlier if waiting is
* interrupted or by other reasons
- * @return #MHD_SC_OK if ANY data received (check the @a received_size) or
+ * @return #MHD_SC_OK if ANY data received (check the @a received_size),
* remote shut down send side (indicated by @a received_size
- * set to zero),
+ * set to zero while @a recv_buf_size is not zero) or
+ * @a recv_buf_size is zero,
* #MHD_SC_UPGRADED_NET_TIMEOUT if NO data received but timeout expired,
* #MHD_SC_UPGRADED_NET_CONN_CLOSED if network connection has been
* closed,
@@ -7487,8 +7494,9 @@ MHD_upgraded_recv (struct MHD_UpgradedHandle *MHD_RESTRICT urh,
void *MHD_RESTRICT recv_buf,
size_t *MHD_RESTRICT received_size,
uint_fast64_t max_wait_millisec)
-MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_OUT_SIZE_ (3, 2)
-MHD_FN_PAR_OUT_ (4);
+MHD_FN_PAR_NONNULL_ (1)
+MHD_FN_PAR_NONNULL_IF_NONZERO_ (3, 2) MHD_FN_PAR_OUT_SIZE_ (3, 2)
+MHD_FN_PAR_NONNULL_ (4) MHD_FN_PAR_OUT_ (4);
/**
diff --git a/src/include/microhttpd2_main.h.in b/src/include/microhttpd2_main.h.in
@@ -2394,9 +2394,15 @@ MHD_FN_PAR_IN_SIZE_ (6, 5);
* + timeout reached,
* + network error occurs
*
+ * If @a recv_buf_size is zero, no data are received.
+ * For a valid @a urh, the function returns #MHD_SC_OK immediately and stores
+ * zero in the variable pointed to by @a received_size.
+ *
* @param urh the HTTP-Upgraded handle
- * @param recv_buf_size the size of the @a recv_buf
- * @param recv_buf the buffer to receive the data
+ * @param recv_buf_size the size of the @a recv_buf,
+ * must be zero if @a recv_buf is NULL
+ * @param recv_buf the buffer to receive the data,
+ * can be NULL if @a recv_buf_size is zero
* @param received_size the pointer to variable to get amount of received data
* @param max_wait_millisec the maximum wait time for the data,
* non-blocking operation if set to zero,
@@ -2404,9 +2410,10 @@ MHD_FN_PAR_IN_SIZE_ (6, 5);
* #MHD_WAIT_INDEFINITELY,
* the function may return earlier if waiting is
* interrupted or by other reasons
- * @return #MHD_SC_OK if ANY data received (check the @a received_size) or
+ * @return #MHD_SC_OK if ANY data received (check the @a received_size),
* remote shut down send side (indicated by @a received_size
- * set to zero),
+ * set to zero while @a recv_buf_size is not zero) or
+ * @a recv_buf_size is zero,
* #MHD_SC_UPGRADED_NET_TIMEOUT if NO data received but timeout expired,
* #MHD_SC_UPGRADED_NET_CONN_CLOSED if network connection has been
* closed,
@@ -2425,8 +2432,9 @@ MHD_upgraded_recv (struct MHD_UpgradedHandle *MHD_RESTRICT urh,
void *MHD_RESTRICT recv_buf,
size_t *MHD_RESTRICT received_size,
uint_fast64_t max_wait_millisec)
-MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_OUT_SIZE_ (3, 2)
-MHD_FN_PAR_OUT_ (4);
+MHD_FN_PAR_NONNULL_ (1)
+MHD_FN_PAR_NONNULL_IF_NONZERO_ (3, 2) MHD_FN_PAR_OUT_SIZE_ (3, 2)
+MHD_FN_PAR_NONNULL_ (4) MHD_FN_PAR_OUT_ (4);
/**
diff --git a/src/mhd2/upgraded_net.c b/src/mhd2/upgraded_net.c
@@ -123,8 +123,10 @@ mhd_sleep (uint_fast32_t millisec)
MHD_EXTERN_
-MHD_FN_PAR_NONNULL_ALL_
+MHD_FN_PAR_NONNULL_ (1)
+MHD_FN_PAR_NONNULL_IF_NONZERO_ (3, 2)
MHD_FN_PAR_OUT_SIZE_ (3, 2)
+MHD_FN_PAR_NONNULL_ (4)
MHD_FN_PAR_OUT_ (4) enum MHD_StatusCode
MHD_upgraded_recv (struct MHD_UpgradedHandle *MHD_RESTRICT urh,
size_t recv_buf_size,
