From: Hugo Landau <hlandau@openssl.org>
Date: Tue, 24 Oct 2023 07:43:49 +0000 (+0100)
Subject: BIO: Document BIO_sendmmsg and BIO_recvmmsg callbacks
X-Git-Tag: openssl-3.3.0-alpha1~777
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=e1559fbb53465cdb156d9317869c11a9575461ba;p=thirdparty%2Fopenssl.git

BIO: Document BIO_sendmmsg and BIO_recvmmsg callbacks

Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Tim Hudson <tjh@openssl.org>
Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/22487)
---

diff --git a/doc/man3/BIO_set_callback.pod b/doc/man3/BIO_set_callback.pod
index b98c0929cb1..114e4cfdfa2 100644
--- a/doc/man3/BIO_set_callback.pod
+++ b/doc/man3/BIO_set_callback.pod
@@ -35,6 +35,13 @@ see L<openssl_user_macros(7)>:
  long BIO_debug_callback(BIO *bio, int cmd, const char *argp, int argi,
                          long argl, long ret);
 
+ typedef struct bio_mmsg_cb_args_st {
+     BIO_MSG    *msg;
+     size_t      stride, num_msg;
+     uint64_t    flags;
+     size_t     *msgs_processed;
+ } BIO_MMSG_CB_ARGS;
+
 =head1 DESCRIPTION
 
 BIO_set_callback_ex() and BIO_get_callback_ex() set and retrieve the BIO
@@ -218,6 +225,34 @@ Note: B<cmd> == B<BIO_CTRL_SET_CALLBACK> is special, because B<parg> is not the
 argument of type B<BIO_info_cb> itself.  In this case B<parg> is a pointer to
 the actual call parameter, see B<BIO_callback_ctrl>.
 
+=item B<BIO_sendmmsg(BIO *b, BIO_MSG *msg, size_t stride, size_t num_msg, uint64_t flags, size_t *msgs_processed)>
+
+  callback_ex(b, BIO_CB_SENDMMSG, args, 0, 0, 0, 0, NULL)
+
+or
+
+  callback(b, BIO_CB_SENDMMSG, args, 0, 0, 0)
+
+is called before the call and
+
+  callback_ex(b, BIO_CB_SENDMMSG | BIO_CB_RETURN, args, ret, 0, 0, 0, NULL)
+
+or
+
+  callback(b, BIO_CB_SENDMMSG | BIO_CB_RETURN, args, ret, 0, 0, 0)
+
+after.
+
+B<args> is a pointer to a B<BIO_MMSG_CB_ARGS> structure containing the arguments
+passed to BIO_sendmmsg(). B<ret> is the return value of the BIO_sendmmsg() call.
+The return value of BIO_sendmmsg() is altered to the value returned by the
+B<BIO_CB_SENDMMSG | BIO_CB_RETURN> call.
+
+=item B<BIO_recvmmsg(BIO *b, BIO_MSG *msg, size_t stride, size_t num_msg, uint64_t flags, size_t *msgs_processed)>
+
+See the documentation for BIO_sendmmsg(). BIO_recvmmsg() works identically
+except that B<BIO_CB_RECVMMSG> is used instead of B<BIO_CB_SENDMMSG>.
+
 =back
 
 =head1 RETURN VALUES