Copyright year updates

[thirdparty/openssl.git] / doc / man3 / BIO_sendmmsg.pod

=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 analogous 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_PEER_ADDR_NOT_AVAILABLE>

The I<peer> field was set to a non-NULL value, but peer address support is not
available 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

Third parties implementing custom BIOs supporting the BIO_sendmmsg() or
BIO_recvmmsg() methods should note that it is a required part of the API
contract that an error is always raised when either of these functions return 0.

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.2.

=head1 COPYRIGHT

Copyright 2000-2023 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