Adding upstream version 4.23.0.upstream/4.23.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 272 insertions, 0 deletions

diff --git a/upstream/debian-unstable/man3/BIO_sendmmsg.3ssl b/upstream/debian-unstable/man3/BIO_sendmmsg.3ssl
new file mode 100644
index 00000000..3d3d8295
--- /dev/null
+++ b/upstream/debian-unstable/man3/BIO_sendmmsg.3ssl
@@ -0,0 +1,272 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "BIO_SENDMMSG 3SSL"
+.TH BIO_SENDMMSG 3SSL 2024-04-04 3.2.2-dev OpenSSL
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH 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
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 1
+\& #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);
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+\&\fBBIO_sendmmsg()\fR and \fBBIO_recvmmsg()\fR functions can be used to send and receive
+multiple messages in a single call to a BIO. They are analogous to \fBsendmmsg\fR\|(2)
+and \fBrecvmmsg\fR\|(2) on operating systems which provide those functions.
+.PP
+The \fBBIO_MSG\fR structure provides a subset of the functionality of the \fBstruct
+msghdr\fR structure defined by POSIX. These functions accept an array of
+\&\fBBIO_MSG\fR 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 \fI*msgs_processed\fR, which expresses the number of
+messages processed.
+.PP
+The caller should set the \fIdata\fR member of a \fBBIO_MSG\fR to a buffer containing
+the data to send, or to be filled with a received message. \fIdata_len\fR should be
+set to the size of the buffer in bytes. If the given \fBBIO_MSG\fR is processed (in
+other words, if the integer returned by the function is greater than or equal to
+that \fBBIO_MSG\fR's array index), \fIdata_len\fR will be modified to specify the
+actual amount of data sent or received.
+.PP
+The \fIflags\fR field of a \fBBIO_MSG\fR provides input per-message flags to the
+invocation. If the invocation processes that \fBBIO_MSG\fR, the \fIflags\fR field is
+written with output per-message flags, or zero if no such flags are applicable.
+.PP
+Currently, no input or output per-message flags are defined and this field
+should be set to zero before calling \fBBIO_sendmmsg()\fR or \fBBIO_recvmmsg()\fR.
+.PP
+The \fIflags\fR argument to \fBBIO_sendmmsg()\fR and \fBBIO_recvmmsg()\fR provides global
+flags which affect the entire invocation. No global flags are currently
+defined and this argument should be set to zero.
+.PP
+When these functions are used to send and receive datagrams, the \fIpeer\fR field
+of a \fBBIO_MSG\fR 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 \fIpeer\fR field should be set to point to a \fBBIO_ADDR\fR, which
+will be read by \fBBIO_sendmmsg()\fR and used as the destination address for sent
+datagrams, and written by \fBBIO_recvmmsg()\fR with the source address of received
+datagrams.
+.PP
+Similarly, the \fIlocal\fR field of a \fBBIO_MSG\fR 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 \fIpeer\fR, support for \fIlocal\fR
+must be explicitly enabled on a \fBBIO\fR before it can be used; see
+\&\fBBIO_dgram_set_local_addr_enable()\fR. If \fIlocal\fR is non-NULL in a \fBBIO_MSG\fR and
+support for \fIlocal\fR has not been enabled, processing of that \fBBIO_MSG\fR fails.
+.PP
+\&\fIpeer\fR and \fIlocal\fR should be set to NULL if they are not required. Support for
+\&\fIlocal\fR may not be available on all platforms; on these platforms, these
+functions always fail if \fIlocal\fR is non-NULL.
+.PP
+If \fIlocal\fR is specified and local address support is enabled, but the operating
+system does not report a local address for a specific received message, the
+\&\fBBIO_ADDR\fR it points to will be cleared (address family set to \f(CW\*(C`AF_UNSPEC\*(C'\fR).
+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 \fBBIO_ADDR\fR instead of the
+correct value.
+.PP
+The \fIstride\fR argument must be set to \f(CWsizeof(BIO_MSG)\fR. This argument
+facilitates backwards compatibility if fields are added to \fBBIO_MSG\fR. Callers
+must zero-initialize \fBBIO_MSG\fR.
+.PP
+\&\fInum_msg\fR should be sent to the maximum number of messages to send or receive,
+which is also the length of the array pointed to by \fImsg\fR.
+.PP
+\&\fImsgs_processed\fR 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.
+.PP
+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.
+.PP
+The support for concurrent use extends to \fBBIO_sendmmsg()\fR and \fBBIO_recvmmsg()\fR
+only, and no other function may be called on a given BIO while any call to
+\&\fBBIO_sendmmsg()\fR or \fBBIO_recvmmsg()\fR is in progress, or vice versa.
+.PP
+\&\fBBIO_dgram_set_local_addr_enable()\fR and \fBBIO_dgram_get_local_addr_enable()\fR control
+whether local address support is enabled. To enable local address support, call
+\&\fBBIO_dgram_set_local_addr_enable()\fR with an argument of 1. The call will fail if
+local address support is not available for the platform.
+\&\fBBIO_dgram_get_local_addr_enable()\fR retrieves the value set by
+\&\fBBIO_dgram_set_local_addr_enable()\fR.
+.PP
+\&\fBBIO_dgram_get_local_addr_cap()\fR determines if the \fBBIO\fR is capable of supporting
+local addresses.
+.PP
+\&\fBBIO_err_is_non_fatal()\fR determines if a packed error code represents an error
+which is transient in nature.
+.SH NOTES
+.IX Header "NOTES"
+Some implementations of the \fBBIO_sendmmsg()\fR and \fBBIO_recvmmsg()\fR 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.
+.SH "RETURN VALUES"
+.IX Header "RETURN VALUES"
+On success, the functions \fBBIO_sendmmsg()\fR and \fBBIO_recvmmsg()\fR return 1 and write
+the number of messages successfully processed (which need not be nonzero) to
+\&\fImsgs_processed\fR. Where a positive value n is written to \fImsgs_processed\fR, all
+entries in the \fBBIO_MSG\fR array from 0 through n\-1 inclusive have their
+\&\fIdata_len\fR and \fIflags\fR fields updated with the results of the operation on
+that message. If the call was to \fBBIO_recvmmsg()\fR and the \fIpeer\fR or \fIlocal\fR
+fields of that message are non-NULL, the \fBBIO_ADDR\fR structures they point to
+are written with the relevant address.
+.PP
+On failure, the functions \fBBIO_sendmmsg()\fR and \fBBIO_recvmmsg()\fR return 0 and write
+zero to \fImsgs_processed\fR. Thus \fImsgs_processed\fR is always written regardless
+of the outcome of the function call.
+.PP
+If \fBBIO_sendmmsg()\fR and \fBBIO_recvmmsg()\fR fail, they always raise an \fBERR_LIB_BIO\fR
+error using \fBERR_raise\fR\|(3). Any error may be raised, but the following in
+particular may be noted:
+.IP \fBBIO_R_LOCAL_ADDR_NOT_AVAILABLE\fR 2
+.IX Item "BIO_R_LOCAL_ADDR_NOT_AVAILABLE"
+The \fIlocal\fR field was set to a non-NULL value, but local address support is not
+available or not enabled on the BIO.
+.IP \fBBIO_R_PEER_ADDR_NOT_AVAILABLE\fR 2
+.IX Item "BIO_R_PEER_ADDR_NOT_AVAILABLE"
+The \fIpeer\fR field was set to a non-NULL value, but peer address support is not
+available on the BIO.
+.IP \fBBIO_R_UNSUPPORTED_METHOD\fR 2
+.IX Item "BIO_R_UNSUPPORTED_METHOD"
+The \fBBIO_sendmmsg()\fR or \fBBIO_recvmmsg()\fR method is not supported on the BIO.
+.IP \fBBIO_R_NON_FATAL\fR 2
+.IX Item "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).
+.Sp
+Implementations of this interface which do not make system calls and thereby
+pass through system error codes using \fBERR_LIB_SYS\fR (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 \fBBIO_err_is_non_fatal()\fR instead (discussed below).
+.IP "Socket errors" 2
+.IX Item "Socket errors"
+OS-level socket errors are reported using an error with library code
+\&\fBERR_LIB_SYS\fR; for a packed error code \fBerrcode\fR where
+\&\f(CW\*(C`ERR_SYSTEM_ERROR(errcode) == 1\*(C'\fR, the OS-level socket error code can be
+retrieved using \f(CWERR_GET_REASON(errcode)\fR. The packed error code can be
+retrieved by calling \fBERR_peek_last_error\fR\|(3) after the call to \fBBIO_sendmmsg()\fR
+or \fBBIO_recvmmsg()\fR returns 0.
+.IP "Non-fatal errors" 2
+.IX Item "Non-fatal errors"
+Whether an error is transient can be determined by passing the packed error code
+to \fBBIO_err_is_non_fatal()\fR. 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.
+.PP
+Third parties implementing custom BIOs supporting the \fBBIO_sendmmsg()\fR or
+\&\fBBIO_recvmmsg()\fR 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.
+.PP
+\&\fBBIO_dgram_set_local_addr_enable()\fR returns 1 if local address support was
+successfully enabled or disabled and 0 otherwise.
+.PP
+\&\fBBIO_dgram_get_local_addr_enable()\fR returns 1 if the local address support enable
+flag was successfully retrieved.
+.PP
+\&\fBBIO_dgram_get_local_addr_cap()\fR returns 1 if the \fBBIO\fR can support local
+addresses.
+.PP
+\&\fBBIO_err_is_non_fatal()\fR returns 1 if the passed packed error code represents an
+error which is transient in nature.
+.SH HISTORY
+.IX Header "HISTORY"
+These functions were added in OpenSSL 3.2.
+.SH COPYRIGHT
+.IX Header "COPYRIGHT"
+Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved.
+.PP
+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
+<https://www.openssl.org/source/license.html>.