diff options
Diffstat (limited to 'secure/lib/libcrypto/man/man3/BIO_sendmmsg.3')
| -rw-r--r-- | secure/lib/libcrypto/man/man3/BIO_sendmmsg.3 | 53 |
1 files changed, 28 insertions, 25 deletions
diff --git a/secure/lib/libcrypto/man/man3/BIO_sendmmsg.3 b/secure/lib/libcrypto/man/man3/BIO_sendmmsg.3 index f415219e8130..e029c64faa22 100644 --- a/secure/lib/libcrypto/man/man3/BIO_sendmmsg.3 +++ b/secure/lib/libcrypto/man/man3/BIO_sendmmsg.3 @@ -1,5 +1,5 @@ .\" -*- mode: troff; coding: utf-8 -*- -.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) .\" .\" Standard preamble: .\" ======================================================================== @@ -52,10 +52,13 @@ . \} .\} .rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l .\" ======================================================================== .\" .IX Title "BIO_SENDMMSG 3ossl" -.TH BIO_SENDMMSG 3ossl 2025-09-30 3.5.4 OpenSSL +.TH BIO_SENDMMSG 3ossl 2026-04-07 3.5.6 OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -105,14 +108,14 @@ The caller should set the \fIdata\fR member of a \fBBIO_MSG\fR to a buffer conta 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 +that \fBBIO_MSG\fR\*(Aqs 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 +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. +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 +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 @@ -121,47 +124,47 @@ 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 +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 +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 +\&\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. +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 +the local system, regardless of whether the packet\*(Aqs 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 +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. +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 +\&\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 +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 @@ -186,7 +189,7 @@ 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 +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" @@ -197,7 +200,7 @@ the number of messages successfully processed (which need not be nonzero) to 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 +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 @@ -209,35 +212,35 @@ 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 +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 +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 +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 +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 +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 +\&\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 +.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 |
