xref: /freebsd/crypto/openssl/doc/man3/BIO_sendmmsg.pod (revision e7be843b4a162e68651d3911f0357ed464915629) 
1*e7be843bSPierre Pronchery=pod
2*e7be843bSPierre Pronchery
3*e7be843bSPierre Pronchery=head1 NAME
4*e7be843bSPierre Pronchery
5*e7be843bSPierre ProncheryBIO_sendmmsg, BIO_recvmmsg, BIO_dgram_set_local_addr_enable,
6*e7be843bSPierre ProncheryBIO_dgram_get_local_addr_enable, BIO_dgram_get_local_addr_cap,
7*e7be843bSPierre ProncheryBIO_err_is_non_fatal - send and receive multiple datagrams in a single call
8*e7be843bSPierre Pronchery
9*e7be843bSPierre Pronchery=head1 SYNOPSIS
10*e7be843bSPierre Pronchery
11*e7be843bSPierre Pronchery #include <openssl/bio.h>
12*e7be843bSPierre Pronchery
13*e7be843bSPierre Pronchery typedef struct bio_msg_st {
14*e7be843bSPierre Pronchery     void *data;
15*e7be843bSPierre Pronchery     size_t data_len;
16*e7be843bSPierre Pronchery     BIO_ADDR *peer, *local;
17*e7be843bSPierre Pronchery     uint64_t flags;
18*e7be843bSPierre Pronchery } BIO_MSG;
19*e7be843bSPierre Pronchery
20*e7be843bSPierre Pronchery int BIO_sendmmsg(BIO *b, BIO_MSG *msg,
21*e7be843bSPierre Pronchery                  size_t stride, size_t num_msg, uint64_t flags,
22*e7be843bSPierre Pronchery                  size_t *msgs_processed);
23*e7be843bSPierre Pronchery int BIO_recvmmsg(BIO *b, BIO_MSG *msg,
24*e7be843bSPierre Pronchery                  size_t stride, size_t num_msg, uint64_t flags,
25*e7be843bSPierre Pronchery                  size_t *msgs_processed);
26*e7be843bSPierre Pronchery
27*e7be843bSPierre Pronchery int BIO_dgram_set_local_addr_enable(BIO *b, int enable);
28*e7be843bSPierre Pronchery int BIO_dgram_get_local_addr_enable(BIO *b, int *enable);
29*e7be843bSPierre Pronchery int BIO_dgram_get_local_addr_cap(BIO *b);
30*e7be843bSPierre Pronchery int BIO_err_is_non_fatal(unsigned int errcode);
31*e7be843bSPierre Pronchery
32*e7be843bSPierre Pronchery=head1 DESCRIPTION
33*e7be843bSPierre Pronchery
34*e7be843bSPierre ProncheryBIO_sendmmsg() and BIO_recvmmsg() functions can be used to send and receive
35*e7be843bSPierre Proncherymultiple messages in a single call to a BIO. They are analogous to sendmmsg(2)
36*e7be843bSPierre Proncheryand recvmmsg(2) on operating systems which provide those functions.
37*e7be843bSPierre Pronchery
38*e7be843bSPierre ProncheryThe B<BIO_MSG> structure provides a subset of the functionality of the B<struct
39*e7be843bSPierre Proncherymsghdr> structure defined by POSIX. These functions accept an array of
40*e7be843bSPierre ProncheryB<BIO_MSG> structures. On any particular invocation, these functions may process
41*e7be843bSPierre Proncheryall of the passed structures, some of them, or none of them. This is indicated
42*e7be843bSPierre Proncheryby the value stored in I<*msgs_processed>, which expresses the number of
43*e7be843bSPierre Proncherymessages processed.
44*e7be843bSPierre Pronchery
45*e7be843bSPierre ProncheryThe caller should set the I<data> member of a B<BIO_MSG> to a buffer containing
46*e7be843bSPierre Proncherythe data to send, or to be filled with a received message. I<data_len> should be
47*e7be843bSPierre Proncheryset to the size of the buffer in bytes. If the given B<BIO_MSG> is processed (in
48*e7be843bSPierre Proncheryother words, if the integer returned by the function is greater than or equal to
49*e7be843bSPierre Proncherythat B<BIO_MSG>'s array index), I<data_len> will be modified to specify the
50*e7be843bSPierre Proncheryactual amount of data sent or received.
51*e7be843bSPierre Pronchery
52*e7be843bSPierre ProncheryThe I<flags> field of a B<BIO_MSG> provides input per-message flags to the
53*e7be843bSPierre Proncheryinvocation. If the invocation processes that B<BIO_MSG>, the I<flags> field is
54*e7be843bSPierre Proncherywritten with output per-message flags, or zero if no such flags are applicable.
55*e7be843bSPierre Pronchery
56*e7be843bSPierre ProncheryCurrently, no input or output per-message flags are defined and this field
57*e7be843bSPierre Proncheryshould be set to zero before calling BIO_sendmmsg() or BIO_recvmmsg().
58*e7be843bSPierre Pronchery
59*e7be843bSPierre ProncheryThe I<flags> argument to BIO_sendmmsg() and BIO_recvmmsg() provides global
60*e7be843bSPierre Proncheryflags which affect the entire invocation. No global flags are currently
61*e7be843bSPierre Proncherydefined and this argument should be set to zero.
62*e7be843bSPierre Pronchery
63*e7be843bSPierre ProncheryWhen these functions are used to send and receive datagrams, the I<peer> field
64*e7be843bSPierre Proncheryof a B<BIO_MSG> allows the destination address of sent datagrams to be specified
65*e7be843bSPierre Proncheryon a per-datagram basis, and the source address of received datagrams to be
66*e7be843bSPierre Proncherydetermined. The I<peer> field should be set to point to a B<BIO_ADDR>, which
67*e7be843bSPierre Proncherywill be read by BIO_sendmmsg() and used as the destination address for sent
68*e7be843bSPierre Proncherydatagrams, and written by BIO_recvmmsg() with the source address of received
69*e7be843bSPierre Proncherydatagrams.
70*e7be843bSPierre Pronchery
71*e7be843bSPierre ProncherySimilarly, the I<local> field of a B<BIO_MSG> allows the source address of sent
72*e7be843bSPierre Proncherydatagrams to be specified on a per-datagram basis, and the destination address
73*e7be843bSPierre Proncheryof received datagrams to be determined. Unlike I<peer>, support for I<local>
74*e7be843bSPierre Proncherymust be explicitly enabled on a B<BIO> before it can be used; see
75*e7be843bSPierre ProncheryBIO_dgram_set_local_addr_enable(). If I<local> is non-NULL in a B<BIO_MSG> and
76*e7be843bSPierre Proncherysupport for I<local> has not been enabled, processing of that B<BIO_MSG> fails.
77*e7be843bSPierre Pronchery
78*e7be843bSPierre ProncheryI<peer> and I<local> should be set to NULL if they are not required. Support for
79*e7be843bSPierre ProncheryI<local> may not be available on all platforms; on these platforms, these
80*e7be843bSPierre Proncheryfunctions always fail if I<local> is non-NULL.
81*e7be843bSPierre Pronchery
82*e7be843bSPierre ProncheryIf I<local> is specified and local address support is enabled, but the operating
83*e7be843bSPierre Proncherysystem does not report a local address for a specific received message, the
84*e7be843bSPierre ProncheryB<BIO_ADDR> it points to will be cleared (address family set to C<AF_UNSPEC>).
85*e7be843bSPierre ProncheryThis is known to happen on Windows when a packet is received which was sent by
86*e7be843bSPierre Proncherythe local system, regardless of whether the packet's destination address was the
87*e7be843bSPierre Proncheryloopback address or the IP address of a local non-loopback interface. This is
88*e7be843bSPierre Proncheryalso known to happen on macOS in some circumstances, such as for packets sent
89*e7be843bSPierre Proncherybefore local address support was enabled for a receiving socket. These are
90*e7be843bSPierre ProncheryOS-specific limitations. As such, users of this API using local address support
91*e7be843bSPierre Proncheryshould expect to sometimes receive a cleared local B<BIO_ADDR> instead of the
92*e7be843bSPierre Proncherycorrect value.
93*e7be843bSPierre Pronchery
94*e7be843bSPierre ProncheryThe I<stride> argument must be set to C<sizeof(BIO_MSG)>. This argument
95*e7be843bSPierre Proncheryfacilitates backwards compatibility if fields are added to B<BIO_MSG>. Callers
96*e7be843bSPierre Proncherymust zero-initialize B<BIO_MSG>.
97*e7be843bSPierre Pronchery
98*e7be843bSPierre ProncheryI<num_msg> should be sent to the maximum number of messages to send or receive,
99*e7be843bSPierre Proncherywhich is also the length of the array pointed to by I<msg>.
100*e7be843bSPierre Pronchery
101*e7be843bSPierre ProncheryI<msgs_processed> must be non-NULL and points to an integer written with the
102*e7be843bSPierre Proncherynumber of messages successfully processed; see the RETURN VALUES section for
103*e7be843bSPierre Proncheryfurther discussion.
104*e7be843bSPierre Pronchery
105*e7be843bSPierre ProncheryUnlike most BIO functions, these functions explicitly support multi-threaded
106*e7be843bSPierre Proncheryuse. Multiple concurrent writers and multiple concurrent readers of the same BIO
107*e7be843bSPierre Proncheryare permitted in any combination. As such, these functions do not clear, set, or
108*e7be843bSPierre Proncheryotherwise modify BIO retry flags. The return value must be used to determine
109*e7be843bSPierre Proncherywhether an operation should be retried; see below.
110*e7be843bSPierre Pronchery
111*e7be843bSPierre ProncheryThe support for concurrent use extends to BIO_sendmmsg() and BIO_recvmmsg()
112*e7be843bSPierre Proncheryonly, and no other function may be called on a given BIO while any call to
113*e7be843bSPierre ProncheryBIO_sendmmsg() or BIO_recvmmsg() is in progress, or vice versa.
114*e7be843bSPierre Pronchery
115*e7be843bSPierre ProncheryBIO_dgram_set_local_addr_enable() and BIO_dgram_get_local_addr_enable() control
116*e7be843bSPierre Proncherywhether local address support is enabled. To enable local address support, call
117*e7be843bSPierre ProncheryBIO_dgram_set_local_addr_enable() with an argument of 1. The call will fail if
118*e7be843bSPierre Proncherylocal address support is not available for the platform.
119*e7be843bSPierre ProncheryBIO_dgram_get_local_addr_enable() retrieves the value set by
120*e7be843bSPierre ProncheryBIO_dgram_set_local_addr_enable().
121*e7be843bSPierre Pronchery
122*e7be843bSPierre ProncheryBIO_dgram_get_local_addr_cap() determines if the B<BIO> is capable of supporting
123*e7be843bSPierre Proncherylocal addresses.
124*e7be843bSPierre Pronchery
125*e7be843bSPierre ProncheryBIO_err_is_non_fatal() determines if a packed error code represents an error
126*e7be843bSPierre Proncherywhich is transient in nature.
127*e7be843bSPierre Pronchery
128*e7be843bSPierre Pronchery=head1 NOTES
129*e7be843bSPierre Pronchery
130*e7be843bSPierre ProncherySome implementations of the BIO_sendmmsg() and BIO_recvmmsg() BIO methods might
131*e7be843bSPierre Proncheryalways process at most one message at a time, for example when OS-level
132*e7be843bSPierre Proncheryfunctionality to transmit or receive multiple messages at a time is not
133*e7be843bSPierre Proncheryavailable.
134*e7be843bSPierre Pronchery
135*e7be843bSPierre Pronchery=head1 RETURN VALUES
136*e7be843bSPierre Pronchery
137*e7be843bSPierre ProncheryOn success, the functions BIO_sendmmsg() and BIO_recvmmsg() return 1 and write
138*e7be843bSPierre Proncherythe number of messages successfully processed (which need not be nonzero) to
139*e7be843bSPierre ProncheryI<msgs_processed>. Where a positive value n is written to I<msgs_processed>, all
140*e7be843bSPierre Proncheryentries in the B<BIO_MSG> array from 0 through n-1 inclusive have their
141*e7be843bSPierre ProncheryI<data_len> and I<flags> fields updated with the results of the operation on
142*e7be843bSPierre Proncherythat message. If the call was to BIO_recvmmsg() and the I<peer> or I<local>
143*e7be843bSPierre Proncheryfields of that message are non-NULL, the B<BIO_ADDR> structures they point to
144*e7be843bSPierre Proncheryare written with the relevant address.
145*e7be843bSPierre Pronchery
146*e7be843bSPierre ProncheryOn failure, the functions BIO_sendmmsg() and BIO_recvmmsg() return 0 and write
147*e7be843bSPierre Proncheryzero to I<msgs_processed>. Thus I<msgs_processed> is always written regardless
148*e7be843bSPierre Proncheryof the outcome of the function call.
149*e7be843bSPierre Pronchery
150*e7be843bSPierre ProncheryIf BIO_sendmmsg() and BIO_recvmmsg() fail, they always raise an B<ERR_LIB_BIO>
151*e7be843bSPierre Proncheryerror using L<ERR_raise(3)>. Any error may be raised, but the following in
152*e7be843bSPierre Proncheryparticular may be noted:
153*e7be843bSPierre Pronchery
154*e7be843bSPierre Pronchery=over 2
155*e7be843bSPierre Pronchery
156*e7be843bSPierre Pronchery=item B<BIO_R_LOCAL_ADDR_NOT_AVAILABLE>
157*e7be843bSPierre Pronchery
158*e7be843bSPierre ProncheryThe I<local> field was set to a non-NULL value, but local address support is not
159*e7be843bSPierre Proncheryavailable or not enabled on the BIO.
160*e7be843bSPierre Pronchery
161*e7be843bSPierre Pronchery=item B<BIO_R_PEER_ADDR_NOT_AVAILABLE>
162*e7be843bSPierre Pronchery
163*e7be843bSPierre ProncheryThe I<peer> field was set to a non-NULL value, but peer address support is not
164*e7be843bSPierre Proncheryavailable on the BIO.
165*e7be843bSPierre Pronchery
166*e7be843bSPierre Pronchery=item B<BIO_R_UNSUPPORTED_METHOD>
167*e7be843bSPierre Pronchery
168*e7be843bSPierre ProncheryThe BIO_sendmmsg() or BIO_recvmmsg() method is not supported on the BIO.
169*e7be843bSPierre Pronchery
170*e7be843bSPierre Pronchery=item B<BIO_R_NON_FATAL>
171*e7be843bSPierre Pronchery
172*e7be843bSPierre ProncheryThe call failed due to a transient, non-fatal error (for example, because the
173*e7be843bSPierre ProncheryBIO is in nonblocking mode and the call would otherwise have blocked).
174*e7be843bSPierre Pronchery
175*e7be843bSPierre ProncheryImplementations of this interface which do not make system calls and thereby
176*e7be843bSPierre Proncherypass through system error codes using B<ERR_LIB_SYS> (for example, memory-based
177*e7be843bSPierre Proncheryimplementations) should issue this reason code to indicate a transient failure.
178*e7be843bSPierre ProncheryHowever, users of this interface should not test for this reason code directly,
179*e7be843bSPierre Proncheryas there are multiple possible packed error codes representing a transient
180*e7be843bSPierre Proncheryfailure; use BIO_err_is_non_fatal() instead (discussed below).
181*e7be843bSPierre Pronchery
182*e7be843bSPierre Pronchery=item Socket errors
183*e7be843bSPierre Pronchery
184*e7be843bSPierre ProncheryOS-level socket errors are reported using an error with library code
185*e7be843bSPierre ProncheryB<ERR_LIB_SYS>; for a packed error code B<errcode> where
186*e7be843bSPierre ProncheryC<ERR_SYSTEM_ERROR(errcode) == 1>, the OS-level socket error code can be
187*e7be843bSPierre Proncheryretrieved using C<ERR_GET_REASON(errcode)>. The packed error code can be
188*e7be843bSPierre Proncheryretrieved by calling L<ERR_peek_last_error(3)> after the call to BIO_sendmmsg()
189*e7be843bSPierre Proncheryor BIO_recvmmsg() returns 0.
190*e7be843bSPierre Pronchery
191*e7be843bSPierre Pronchery=item Non-fatal errors
192*e7be843bSPierre Pronchery
193*e7be843bSPierre ProncheryWhether an error is transient can be determined by passing the packed error code
194*e7be843bSPierre Proncheryto BIO_err_is_non_fatal(). Callers should do this instead of testing the reason
195*e7be843bSPierre Proncherycode directly, as there are many possible error codes which can indicate a
196*e7be843bSPierre Proncherytransient error, many of which are system specific.
197*e7be843bSPierre Pronchery
198*e7be843bSPierre Pronchery=back
199*e7be843bSPierre Pronchery
200*e7be843bSPierre ProncheryThird parties implementing custom BIOs supporting the BIO_sendmmsg() or
201*e7be843bSPierre ProncheryBIO_recvmmsg() methods should note that it is a required part of the API
202*e7be843bSPierre Proncherycontract that an error is always raised when either of these functions return 0.
203*e7be843bSPierre Pronchery
204*e7be843bSPierre ProncheryBIO_dgram_set_local_addr_enable() returns 1 if local address support was
205*e7be843bSPierre Proncherysuccessfully enabled or disabled and 0 otherwise.
206*e7be843bSPierre Pronchery
207*e7be843bSPierre ProncheryBIO_dgram_get_local_addr_enable() returns 1 if the local address support enable
208*e7be843bSPierre Proncheryflag was successfully retrieved.
209*e7be843bSPierre Pronchery
210*e7be843bSPierre ProncheryBIO_dgram_get_local_addr_cap() returns 1 if the B<BIO> can support local
211*e7be843bSPierre Proncheryaddresses.
212*e7be843bSPierre Pronchery
213*e7be843bSPierre ProncheryBIO_err_is_non_fatal() returns 1 if the passed packed error code represents an
214*e7be843bSPierre Proncheryerror which is transient in nature.
215*e7be843bSPierre Pronchery
216*e7be843bSPierre Pronchery=head1 HISTORY
217*e7be843bSPierre Pronchery
218*e7be843bSPierre ProncheryThese functions were added in OpenSSL 3.2.
219*e7be843bSPierre Pronchery
220*e7be843bSPierre Pronchery=head1 COPYRIGHT
221*e7be843bSPierre Pronchery
222*e7be843bSPierre ProncheryCopyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved.
223*e7be843bSPierre Pronchery
224*e7be843bSPierre ProncheryLicensed under the Apache License 2.0 (the "License").  You may not use
225*e7be843bSPierre Proncherythis file except in compliance with the License.  You can obtain a copy
226*e7be843bSPierre Proncheryin the file LICENSE in the source distribution or at
227*e7be843bSPierre ProncheryL<https://www.openssl.org/source/license.html>.
228*e7be843bSPierre Pronchery
229*e7be843bSPierre Pronchery=cut
230