mirror of
https://github.com/openssl/openssl.git
synced 2024-12-27 06:21:43 +08:00
230 lines
10 KiB
Plaintext
230 lines
10 KiB
Plaintext
=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
|