BIO_sendmmsg/BIO_recvmmsg (API only)

Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/18923)

1 files changed, 220 insertions, 0 deletions

diff --git a/doc/man3/BIO_sendmmsg.pod b/doc/man3/BIO_sendmmsg.pod
new file mode 100644
index 0000000000..6940847e22
--- /dev/null
+++ b/doc/man3/BIO_sendmmsg.pod
@@ -0,0 +1,220 @@
+=pod
+
+=head1 NAME
+
+BIO_sendmmsg, BIO_recvmmsg, BIO_dgram_set_local_addr_enable,
+BIO_dgram_get_local_addr_enable, BIO_dgram_get_local_addr_cap,
+BIO_err_is_non_fatal - send and receive multiple datagrams in a single call
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+
+ typedef struct bio_msg_st {
+     void *data;
+     size_t data_len;
+     BIO_ADDR *peer, *local;
+     uint64_t flags;
+ } BIO_MSG;
+
+ int BIO_sendmmsg(BIO *b, BIO_MSG *msg,
+                  size_t stride, size_t num_msg, uint64_t flags,
+                  size_t *msgs_processed);
+ int BIO_recvmmsg(BIO *b, BIO_MSG *msg,
+                  size_t stride, size_t num_msg, uint64_t flags,
+                  size_t *msgs_processed);
+
+ int BIO_dgram_set_local_addr_enable(BIO *b, int enable);
+ int BIO_dgram_get_local_addr_enable(BIO *b, int *enable);
+ int BIO_dgram_get_local_addr_cap(BIO *b);
+ int BIO_err_is_non_fatal(unsigned int errcode);
+
+=head1 DESCRIPTION
+
+BIO_sendmmsg() and BIO_recvmmsg() functions can be used to send and receive
+multiple messages in a single call to a BIO. They are analagous to sendmmsg(2)
+and recvmmsg(2) on operating systems which provide those functions.
+
+The B<BIO_MSG> structure provides a subset of the functionality of the B<struct
+msghdr> structure defined by POSIX. These functions accept an array of
+B<BIO_MSG> structures. On any particular invocation, these functions may process
+all of the passed structures, some of them, or none of them. This is indicated
+by the value stored in I<*msgs_processed>, which expresses the number of
+messages processed.
+
+The caller should set the I<data> member of a B<BIO_MSG> to a buffer containing
+the data to send, or to be filled with a received message. I<data_len> should be
+set to the size of the buffer in bytes. If the given B<BIO_MSG> is processed (in
+other words, if the integer returned by the function is greater than or equal to
+that B<BIO_MSG>'s array index), I<data_len> will be modified to specify the
+actual amount of data sent or received.
+
+The I<flags> field of a B<BIO_MSG> provides input per-message flags to the
+invocation. If the invocation processes that B<BIO_MSG>, the I<flags> field is
+written with output per-message flags, or zero if no such flags are applicable.
+
+Currently, no input or output per-message flags are defined and this field
+should be set to zero before calling BIO_sendmmsg() or BIO_recvmmsg().
+
+The I<flags> argument to BIO_sendmmsg() and BIO_recvmmsg() provides global
+flags which affect the entire invocation. No global flags are currently
+defined and this argument should be set to zero.
+
+When these functions are used to send and receive datagrams, the I<peer> field
+of a B<BIO_MSG> allows the destination address of sent datagrams to be specified
+on a per-datagram basis, and the source address of received datagrams to be
+determined. The I<peer> field should be set to point to a B<BIO_ADDR>, which
+will be read by BIO_sendmmsg() and used as the destination address for sent
+datagrams, and written by BIO_recvmmsg() with the source address of received
+datagrams.
+
+Similarly, the I<local> field of a B<BIO_MSG> allows the source address of sent
+datagrams to be specified on a per-datagram basis, and the destination address
+of received datagrams to be determined. Unlike I<peer>, support for I<local>
+must be explicitly enabled on a B<BIO> before it can be used; see
+BIO_dgram_set_local_addr_enable(). If I<local> is non-NULL in a B<BIO_MSG> and
+support for I<local> has not been enabled, processing of that B<BIO_MSG> fails.
+
+I<peer> and I<local> should be set to NULL if they are not required. Support for
+I<local> may not be available on all platforms; on these platforms, these
+functions always fail if I<local> is non-NULL.
+
+If I<local> is specified and local address support is enabled, but the operating
+system does not report a local address for a specific received message, the
+B<BIO_ADDR> it points to will be cleared (address family set to C<AF_UNSPEC>).
+This is known to happen on Windows when a packet is received which was sent by
+the local system, regardless of whether the packet's destination address was the
+loopback address or the IP address of a local non-loopback interface. This is
+also known to happen on macOS in some circumstances, such as for packets sent
+before local address support was enabled for a receiving socket. These are
+OS-specific limitations. As such, users of this API using local address support
+should expect to sometimes receive a cleared local B<BIO_ADDR> instead of the
+correct value.
+
+The I<stride> argument must be set to C<sizeof(BIO_MSG)>. This argument
+facilitates backwards compatibility if fields are added to B<BIO_MSG>. Callers
+must zero-initialize B<BIO_MSG>.
+
+I<num_msg> should be sent to the maximum number of messages to send or receive,
+which is also the length of the array pointed to by I<msg>.
+
+I<msgs_processed> must be non-NULL and points to an integer written with the
+number of messages successfully processed; see the RETURN VALUES section for
+further discussion.
+
+Unlike most BIO functions, these functions explicitly support multi-threaded
+use. Multiple concurrent writers and multiple concurrent readers of the same BIO
+are permitted in any combination. As such, these functions do not clear, set, or
+otherwise modify BIO retry flags. The return value must be used to determine
+whether an operation should be retried; see below.
+
+The support for concurrent use extends to BIO_sendmmsg() and BIO_recvmmsg()
+only, and no other function may be called on a given BIO while any call to
+BIO_sendmmsg() or BIO_recvmmsg() is in progress, or vice versa.
+
+BIO_dgram_set_local_addr_enable() and BIO_dgram_get_local_addr_enable() control
+whether local address support is enabled. To enable local address support, call
+BIO_dgram_set_local_addr_enable() with an argument of 1. The call will fail if
+local address support is not available for the platform.
+BIO_dgram_get_local_addr_enable() retrieves the value set by
+BIO_dgram_set_local_addr_enable().
+
+BIO_dgram_get_local_addr_cap() determines if the B<BIO> is capable of supporting
+local addresses.
+
+BIO_err_is_non_fatal() determines if a packed error code represents an error
+which is transient in nature.
+
+=head1 NOTES
+
+Some implementations of the BIO_sendmmsg() and BIO_recvmmsg() BIO methods might
+always process at most one message at a time, for example when OS-level
+functionality to transmit or receive multiple messages at a time is not
+available.
+
+=head1 RETURN VALUES
+
+On success, the functions BIO_sendmmsg() and BIO_recvmmsg() return 1 and write
+the number of messages successfully processed (which need not be nonzero) to
+I<msgs_processed>. Where a positive value n is written to I<msgs_processed>, all
+entries in the B<BIO_MSG> array from 0 through n-1 inclusive have their
+I<data_len> and I<flags> fields updated with the results of the operation on
+that message. If the call was to BIO_recvmmsg() and the I<peer> or I<local>
+fields of that message are non-NULL, the B<BIO_ADDR> structures they point to
+are written with the relevant address.
+
+On failure, the functions BIO_sendmmsg() and BIO_recvmmsg() return 0 and write
+zero to I<msgs_processed>. Thus I<msgs_processed> is always written regardless
+of the outcome of the function call.
+
+If BIO_sendmmsg() and BIO_recvmmsg() fail, they always raise an B<ERR_LIB_BIO>
+error using L<ERR_raise(3)>. Any error may be raised, but the following in
+particular may be noted:
+
+=over 2
+
+=item B<BIO_R_LOCAL_ADDR_NOT_AVAILABLE>
+
+The I<local> field was set to a non-NULL value, but local address support is not
+available or not enabled on the BIO.
+
+=item B<BIO_R_UNSUPPORTED_METHOD>
+
+The BIO_sendmmsg() or BIO_recvmmsg() method is not supported on the BIO.
+
+=item B<BIO_R_NON_FATAL>
+
+The call failed due to a transient, non-fatal error (for example, because the
+BIO is in nonblocking mode and the call would otherwise have blocked).
+
+Implementations of this interface which do not make system calls and thereby
+pass through system error codes using B<ERR_LIB_SYS> (for example, memory-based
+implementations) should issue this reason code to indicate a transient failure.
+However, users of this interface should not test for this reason code directly,
+as there are multiple possible packed error codes representing a transient
+failure; use BIO_err_is_non_fatal() instead (discussed below).
+
+=item Socket errors
+
+OS-level socket errors are reported using an error with library code
+B<ERR_LIB_SYS>; for a packed error code B<errcode> where
+C<ERR_SYSTEM_ERROR(errcode) == 1>, the OS-level socket error code can be
+retrieved using C<ERR_GET_REASON(errcode)>. The packed error code can be
+retrieved by calling L<ERR_peek_last_error(3)> after the call to BIO_sendmmsg()
+or BIO_recvmmsg() returns 0.
+
+=item Non-fatal errors
+
+Whether an error is transient can be determined by passing the packed error code
+to BIO_err_is_non_fatal(). Callers should do this instead of testing the reason
+code directly, as there are many possible error codes which can indicate a
+transient error, many of which are system specific.
+
+=back
+
+BIO_dgram_set_local_addr_enable() returns 1 if local address support was
+successfully enabled or disabled and 0 otherwise.
+
+BIO_dgram_get_local_addr_enable() returns 1 if the local address support enable
+flag was successfully retrieved.
+
+BIO_dgram_get_local_addr_cap() returns 1 if the B<BIO> can support local
+addresses.
+
+BIO_err_is_non_fatal() returns 1 if the passed packed error code represents an
+error which is transient in nature.
+
+=head1 HISTORY
+
+These functions were added in OpenSSL 3.1.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2022 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut