Debian Codegraph @

upstream/debian-unstable/man3/BIO_sendmmsg.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "BIO_SENDMMSG 3SSL"
58 .TH BIO_SENDMMSG 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 BIO_sendmmsg, BIO_recvmmsg, BIO_dgram_set_local_addr_enable,
65 BIO_dgram_get_local_addr_enable, BIO_dgram_get_local_addr_cap,
66 BIO_err_is_non_fatal \- send and receive multiple datagrams in a single call
67 .SH SYNOPSIS
68 .IX Header "SYNOPSIS"
69 .Vb 1
70 \& #include <openssl/bio.h>
71 \&
72 \& typedef struct bio_msg_st {
73 \& void *data;
74 \& size_t data_len;
75 \& BIO_ADDR *peer, *local;
76 \& uint64_t flags;
77 \& } BIO_MSG;
78 \&
79 \& int BIO_sendmmsg(BIO *b, BIO_MSG *msg,
80 \& size_t stride, size_t num_msg, uint64_t flags,
81 \& size_t *msgs_processed);
82 \& int BIO_recvmmsg(BIO *b, BIO_MSG *msg,
83 \& size_t stride, size_t num_msg, uint64_t flags,
84 \& size_t *msgs_processed);
85 \&
86 \& int BIO_dgram_set_local_addr_enable(BIO *b, int enable);
87 \& int BIO_dgram_get_local_addr_enable(BIO *b, int *enable);
88 \& int BIO_dgram_get_local_addr_cap(BIO *b);
89 \& int BIO_err_is_non_fatal(unsigned int errcode);
90 .Ve
91 .SH DESCRIPTION
92 .IX Header "DESCRIPTION"
93 \&\fBBIO_sendmmsg()\fR and \fBBIO_recvmmsg()\fR functions can be used to send and receive
94 multiple messages in a single call to a BIO. They are analogous to \fBsendmmsg\fR\|(2)
95 and \fBrecvmmsg\fR\|(2) on operating systems which provide those functions.
96 .PP
97 The \fBBIO_MSG\fR structure provides a subset of the functionality of the \fBstruct
98 msghdr\fR structure defined by POSIX. These functions accept an array of
99 \&\fBBIO_MSG\fR structures. On any particular invocation, these functions may process
100 all of the passed structures, some of them, or none of them. This is indicated
101 by the value stored in \fI*msgs_processed\fR, which expresses the number of
102 messages processed.
103 .PP
104 The caller should set the \fIdata\fR member of a \fBBIO_MSG\fR to a buffer containing
105 the data to send, or to be filled with a received message. \fIdata_len\fR should be
106 set to the size of the buffer in bytes. If the given \fBBIO_MSG\fR is processed (in
107 other words, if the integer returned by the function is greater than or equal to
108 that \fBBIO_MSG\fR's array index), \fIdata_len\fR will be modified to specify the
109 actual amount of data sent or received.
110 .PP
111 The \fIflags\fR field of a \fBBIO_MSG\fR provides input per-message flags to the
112 invocation. If the invocation processes that \fBBIO_MSG\fR, the \fIflags\fR field is
113 written with output per-message flags, or zero if no such flags are applicable.
114 .PP
115 Currently, no input or output per-message flags are defined and this field
116 should be set to zero before calling \fBBIO_sendmmsg()\fR or \fBBIO_recvmmsg()\fR.
117 .PP
118 The \fIflags\fR argument to \fBBIO_sendmmsg()\fR and \fBBIO_recvmmsg()\fR provides global
119 flags which affect the entire invocation. No global flags are currently
120 defined and this argument should be set to zero.
121 .PP
122 When these functions are used to send and receive datagrams, the \fIpeer\fR field
123 of a \fBBIO_MSG\fR allows the destination address of sent datagrams to be specified
124 on a per-datagram basis, and the source address of received datagrams to be
125 determined. The \fIpeer\fR field should be set to point to a \fBBIO_ADDR\fR, which
126 will be read by \fBBIO_sendmmsg()\fR and used as the destination address for sent
127 datagrams, and written by \fBBIO_recvmmsg()\fR with the source address of received
128 datagrams.
129 .PP
130 Similarly, the \fIlocal\fR field of a \fBBIO_MSG\fR allows the source address of sent
131 datagrams to be specified on a per-datagram basis, and the destination address
132 of received datagrams to be determined. Unlike \fIpeer\fR, support for \fIlocal\fR
133 must be explicitly enabled on a \fBBIO\fR before it can be used; see
134 \&\fBBIO_dgram_set_local_addr_enable()\fR. If \fIlocal\fR is non-NULL in a \fBBIO_MSG\fR and
135 support for \fIlocal\fR has not been enabled, processing of that \fBBIO_MSG\fR fails.
136 .PP
137 \&\fIpeer\fR and \fIlocal\fR should be set to NULL if they are not required. Support for
138 \&\fIlocal\fR may not be available on all platforms; on these platforms, these
139 functions always fail if \fIlocal\fR is non-NULL.
140 .PP
141 If \fIlocal\fR is specified and local address support is enabled, but the operating
142 system does not report a local address for a specific received message, the
143 \&\fBBIO_ADDR\fR it points to will be cleared (address family set to \f(CW\*(C`AF_UNSPEC\*(C'\fR).
144 This is known to happen on Windows when a packet is received which was sent by
145 the local system, regardless of whether the packet's destination address was the
146 loopback address or the IP address of a local non-loopback interface. This is
147 also known to happen on macOS in some circumstances, such as for packets sent
148 before local address support was enabled for a receiving socket. These are
149 OS-specific limitations. As such, users of this API using local address support
150 should expect to sometimes receive a cleared local \fBBIO_ADDR\fR instead of the
151 correct value.
152 .PP
153 The \fIstride\fR argument must be set to \f(CWsizeof(BIO_MSG)\fR. This argument
154 facilitates backwards compatibility if fields are added to \fBBIO_MSG\fR. Callers
155 must zero-initialize \fBBIO_MSG\fR.
156 .PP
157 \&\fInum_msg\fR should be sent to the maximum number of messages to send or receive,
158 which is also the length of the array pointed to by \fImsg\fR.
159 .PP
160 \&\fImsgs_processed\fR must be non-NULL and points to an integer written with the
161 number of messages successfully processed; see the RETURN VALUES section for
162 further discussion.
163 .PP
164 Unlike most BIO functions, these functions explicitly support multi-threaded
165 use. Multiple concurrent writers and multiple concurrent readers of the same BIO
166 are permitted in any combination. As such, these functions do not clear, set, or
167 otherwise modify BIO retry flags. The return value must be used to determine
168 whether an operation should be retried; see below.
169 .PP
170 The support for concurrent use extends to \fBBIO_sendmmsg()\fR and \fBBIO_recvmmsg()\fR
171 only, and no other function may be called on a given BIO while any call to
172 \&\fBBIO_sendmmsg()\fR or \fBBIO_recvmmsg()\fR is in progress, or vice versa.
173 .PP
174 \&\fBBIO_dgram_set_local_addr_enable()\fR and \fBBIO_dgram_get_local_addr_enable()\fR control
175 whether local address support is enabled. To enable local address support, call
176 \&\fBBIO_dgram_set_local_addr_enable()\fR with an argument of 1. The call will fail if
177 local address support is not available for the platform.
178 \&\fBBIO_dgram_get_local_addr_enable()\fR retrieves the value set by
179 \&\fBBIO_dgram_set_local_addr_enable()\fR.
180 .PP
181 \&\fBBIO_dgram_get_local_addr_cap()\fR determines if the \fBBIO\fR is capable of supporting
182 local addresses.
183 .PP
184 \&\fBBIO_err_is_non_fatal()\fR determines if a packed error code represents an error
185 which is transient in nature.
186 .SH NOTES
187 .IX Header "NOTES"
188 Some implementations of the \fBBIO_sendmmsg()\fR and \fBBIO_recvmmsg()\fR BIO methods might
189 always process at most one message at a time, for example when OS-level
190 functionality to transmit or receive multiple messages at a time is not
191 available.
192 .SH "RETURN VALUES"
193 .IX Header "RETURN VALUES"
194 On success, the functions \fBBIO_sendmmsg()\fR and \fBBIO_recvmmsg()\fR return 1 and write
195 the number of messages successfully processed (which need not be nonzero) to
196 \&\fImsgs_processed\fR. Where a positive value n is written to \fImsgs_processed\fR, all
197 entries in the \fBBIO_MSG\fR array from 0 through n\-1 inclusive have their
198 \&\fIdata_len\fR and \fIflags\fR fields updated with the results of the operation on
199 that message. If the call was to \fBBIO_recvmmsg()\fR and the \fIpeer\fR or \fIlocal\fR
200 fields of that message are non-NULL, the \fBBIO_ADDR\fR structures they point to
201 are written with the relevant address.
202 .PP
203 On failure, the functions \fBBIO_sendmmsg()\fR and \fBBIO_recvmmsg()\fR return 0 and write
204 zero to \fImsgs_processed\fR. Thus \fImsgs_processed\fR is always written regardless
205 of the outcome of the function call.
206 .PP
207 If \fBBIO_sendmmsg()\fR and \fBBIO_recvmmsg()\fR fail, they always raise an \fBERR_LIB_BIO\fR
208 error using \fBERR_raise\fR\|(3). Any error may be raised, but the following in
209 particular may be noted:
210 .IP \fBBIO_R_LOCAL_ADDR_NOT_AVAILABLE\fR 2
211 .IX Item "BIO_R_LOCAL_ADDR_NOT_AVAILABLE"
212 The \fIlocal\fR field was set to a non-NULL value, but local address support is not
213 available or not enabled on the BIO.
214 .IP \fBBIO_R_PEER_ADDR_NOT_AVAILABLE\fR 2
215 .IX Item "BIO_R_PEER_ADDR_NOT_AVAILABLE"
216 The \fIpeer\fR field was set to a non-NULL value, but peer address support is not
217 available on the BIO.
218 .IP \fBBIO_R_UNSUPPORTED_METHOD\fR 2
219 .IX Item "BIO_R_UNSUPPORTED_METHOD"
220 The \fBBIO_sendmmsg()\fR or \fBBIO_recvmmsg()\fR method is not supported on the BIO.
221 .IP \fBBIO_R_NON_FATAL\fR 2
222 .IX Item "BIO_R_NON_FATAL"
223 The call failed due to a transient, non-fatal error (for example, because the
224 BIO is in nonblocking mode and the call would otherwise have blocked).
225 .Sp
226 Implementations of this interface which do not make system calls and thereby
227 pass through system error codes using \fBERR_LIB_SYS\fR (for example, memory-based
228 implementations) should issue this reason code to indicate a transient failure.
229 However, users of this interface should not test for this reason code directly,
230 as there are multiple possible packed error codes representing a transient
231 failure; use \fBBIO_err_is_non_fatal()\fR instead (discussed below).
232 .IP "Socket errors" 2
233 .IX Item "Socket errors"
234 OS-level socket errors are reported using an error with library code
235 \&\fBERR_LIB_SYS\fR; for a packed error code \fBerrcode\fR where
236 \&\f(CW\*(C`ERR_SYSTEM_ERROR(errcode) == 1\*(C'\fR, the OS-level socket error code can be
237 retrieved using \f(CWERR_GET_REASON(errcode)\fR. The packed error code can be
238 retrieved by calling \fBERR_peek_last_error\fR\|(3) after the call to \fBBIO_sendmmsg()\fR
239 or \fBBIO_recvmmsg()\fR returns 0.
240 .IP "Non-fatal errors" 2
241 .IX Item "Non-fatal errors"
242 Whether an error is transient can be determined by passing the packed error code
243 to \fBBIO_err_is_non_fatal()\fR. Callers should do this instead of testing the reason
244 code directly, as there are many possible error codes which can indicate a
245 transient error, many of which are system specific.
246 .PP
247 Third parties implementing custom BIOs supporting the \fBBIO_sendmmsg()\fR or
248 \&\fBBIO_recvmmsg()\fR methods should note that it is a required part of the API
249 contract that an error is always raised when either of these functions return 0.
250 .PP
251 \&\fBBIO_dgram_set_local_addr_enable()\fR returns 1 if local address support was
252 successfully enabled or disabled and 0 otherwise.
253 .PP
254 \&\fBBIO_dgram_get_local_addr_enable()\fR returns 1 if the local address support enable
255 flag was successfully retrieved.
256 .PP
257 \&\fBBIO_dgram_get_local_addr_cap()\fR returns 1 if the \fBBIO\fR can support local
258 addresses.
259 .PP
260 \&\fBBIO_err_is_non_fatal()\fR returns 1 if the passed packed error code represents an
261 error which is transient in nature.
262 .SH HISTORY
263 .IX Header "HISTORY"
264 These functions were added in OpenSSL 3.2.
265 .SH COPYRIGHT
266 .IX Header "COPYRIGHT"
267 Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved.
268 .PP
269 Licensed under the Apache License 2.0 (the "License"). You may not use
270 this file except in compliance with the License. You can obtain a copy
271 in the file LICENSE in the source distribution or at
272 <https://www.openssl.org/source/license.html>.