Debian Codegraph @

upstream/debian-unstable/man3/BIO_s_dgram_pair.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_S_DGRAM_PAIR 3SSL"
58 .TH BIO_S_DGRAM_PAIR 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_s_dgram_pair, BIO_new_bio_dgram_pair, BIO_dgram_set_no_trunc,
65 BIO_dgram_get_no_trunc, BIO_dgram_get_effective_caps, BIO_dgram_get_caps,
66 BIO_dgram_set_caps, BIO_dgram_set_mtu, BIO_dgram_get_mtu,
67 BIO_dgram_set0_local_addr \- datagram pair BIO
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& #include <openssl/bio.h>
72 \&
73 \& const BIO_METHOD *BIO_s_dgram_pair(void);
74 \&
75 \& int BIO_new_bio_dgram_pair(BIO **bio1, size_t writebuf1,
76 \& BIO **bio2, size_t writebuf2);
77 \& int BIO_dgram_set_no_trunc(BIO *bio, int enable);
78 \& int BIO_dgram_get_no_trunc(BIO *bio);
79 \& uint32_t BIO_dgram_get_effective_caps(BIO *bio);
80 \& uint32_t BIO_dgram_get_caps(BIO *bio);
81 \& int BIO_dgram_set_caps(BIO *bio, uint32_t caps);
82 \& int BIO_dgram_set_mtu(BIO *bio, unsigned int mtu);
83 \& unsigned int BIO_dgram_get_mtu(BIO *bio);
84 \& int BIO_dgram_set0_local_addr(BIO *bio, BIO_ADDR *addr);
85 .Ve
86 .SH DESCRIPTION
87 .IX Header "DESCRIPTION"
88 \&\fBBIO_s_dgram_pair()\fR returns the method for a BIO datagram pair. A BIO datagram
89 pair is similar to a BIO pair (see \fBBIO_s_bio\fR\|(3)) but has datagram semantics.
90 Broadly, this means that the length of the buffer passed to a write call will
91 match that retrieved by a read call. If the buffer passed to a read call is too
92 short, the datagram is truncated or the read fails, depending on how the BIO is
93 configured.
94 .PP
95 The BIO datagram pair attaches certain metadata to each write, such as source
96 and destination addresses. This information may be retrieved on read.
97 .PP
98 A typical application of a BIO datagram pair is to allow an application to keep
99 all datagram network I/O requested by libssl under application control.
100 .PP
101 The BIO datagram pair is designed to support multithreaded use where certain
102 restrictions are observed; see THREADING.
103 .PP
104 The BIO datagram pair allows each half of a pair to signal to the other half
105 whether they support certain capabilities; see CAPABILITY INDICATION.
106 .PP
107 \&\fBBIO_new_bio_dgram_pair()\fR combines the calls to \fBBIO_new\fR\|(3),
108 \&\fBBIO_make_bio_pair\fR\|(3) and \fBBIO_set_write_buf_size\fR\|(3) to create a connected
109 pair of BIOs \fBbio1\fR, \fBbio2\fR with write buffer sizes \fBwritebuf1\fR and
110 \&\fBwritebuf2\fR. If either size is zero then the default size is used.
111 .PP
112 \&\fBBIO_make_bio_pair\fR\|(3) may be used to join two datagram pair BIOs into a pair.
113 The two BIOs must both use the method returned by \fBBIO_s_dgram_pair()\fR and neither
114 of the BIOs may currently be associated in a pair.
115 .PP
116 \&\fBBIO_destroy_bio_pair\fR\|(3) destroys the association between two connected BIOs.
117 Freeing either half of the pair will automatically destroy the association.
118 .PP
119 \&\fBBIO_reset\fR\|(3) clears any data in the write buffer of the given BIO. This means
120 that the opposite BIO in the pair will no longer have any data waiting to be
121 read.
122 .PP
123 The BIO maintains a fixed size internal write buffer. When the buffer is full,
124 further writes will fail until the buffer is drained via calls to
125 \&\fBBIO_read\fR\|(3). The size of the buffer can be changed using
126 \&\fBBIO_set_write_buf_size\fR\|(3) and queried using \fBBIO_get_write_buf_size\fR\|(3).
127 .PP
128 Note that the write buffer is partially consumed by metadata stored internally
129 which is attached to each datagram, such as source and destination addresses.
130 The size of this overhead is undefined and may change between releases.
131 .PP
132 The standard \fBBIO_ctrl_pending\fR\|(3) call has modified behaviour and returns the
133 size of the next datagram waiting to be read in bytes. An application can use
134 this function to ensure it provides an adequate buffer to a subsequent read
135 call. If no datagram is waiting to be read, zero is returned.
136 .PP
137 This BIO does not support sending or receiving zero-length datagrams. Passing a
138 zero-length buffer to BIO_write is treated as a no-op.
139 .PP
140 \&\fBBIO_eof\fR\|(3) returns 1 only if the given BIO datagram pair BIO is not currently
141 connected to a peer BIO.
142 .PP
143 \&\fBBIO_get_write_guarantee\fR\|(3) and \fBBIO_ctrl_get_write_guarantee\fR\|(3) return how
144 large a datagram the next call to \fBBIO_write\fR\|(3) can accept. If there is not
145 enough space in the write buffer to accept another datagram equal in size to the
146 configured MTU, zero is returned (see below). This is intended to avoid a
147 situation where an application attempts to read a datagram from a network
148 intending to write it to a BIO datagram pair, but where the received datagram
149 ends up being too large to write to the BIO datagram pair.
150 .PP
151 \&\fBBIO_dgram_set_no_trunc()\fR and \fBBIO_ctrl_get_no_trunc()\fR set and retrieve the
152 truncation mode for the given half of a BIO datagram pair. When no-truncate mode
153 is enabled, \fBBIO_read()\fR will fail if the buffer provided is inadequate to hold
154 the next datagram to be read. If no-truncate mode is disabled (the default), the
155 datagram will be silently truncated. This default behaviour maintains
156 compatibility with the semantics of the Berkeley sockets API.
157 .PP
158 \&\fBBIO_dgram_set_mtu()\fR and \fBBIO_dgram_get_mtu()\fR may be used to set an informational
159 MTU value on the BIO datagram pair. If \fBBIO_dgram_set_mtu()\fR is used on a BIO
160 which is currently part of a BIO datagram pair, the MTU value is set on both
161 halves of the pair. The value does not affect the operation of the BIO datagram
162 pair (except for \fBBIO_get_write_guarantee()\fR; see above) but may be used by other
163 code to determine a requested MTU. When a BIO datagram pair BIO is created, the
164 MTU is set to an unspecified but valid value.
165 .PP
166 \&\fBBIO_dgram_set0_local_addr()\fR can be used to set the local BIO_ADDR to be used
167 when sending a datagram via a BIO datagram pair. This becomes the peer address
168 when receiving on the other half of the pair. If the BIO is used in a call to
169 \&\fBBIO_sendmmsg\fR\|(3) and a local address is explicitly specified, then the
170 explicitly specified local address takes precedence. The reference to the
171 BIO_ADDR is passed to the BIO by this call and will be freed automatically when
172 the BIO is freed.
173 .PP
174 \&\fBBIO_flush\fR\|(3) is a no-op.
175 .SH NOTES
176 .IX Header "NOTES"
177 The halves of a BIO datagram pair have independent lifetimes and must be
178 separately freed.
179 .SH THREADING
180 .IX Header "THREADING"
181 \&\fBBIO_recvmmsg\fR\|(3), \fBBIO_sendmmsg\fR\|(3), \fBBIO_read\fR\|(3), \fBBIO_write\fR\|(3),
182 \&\fBBIO_pending\fR\|(3), \fBBIO_get_write_guarantee\fR\|(3) and \fBBIO_flush\fR\|(3) may be used
183 by multiple threads simultaneously on the same BIO datagram pair. Specific
184 \&\fBBIO_ctrl\fR\|(3) operations (namely BIO_CTRL_PENDING, BIO_CTRL_FLUSH and
185 BIO_C_GET_WRITE_GUARANTEE) may also be used. Invoking any other BIO call, or any
186 other \fBBIO_ctrl\fR\|(3) operation, on either half of a BIO datagram pair while any
187 other BIO call is also in progress to either half of the same BIO datagram pair
188 results in undefined behaviour.
189 .SH "CAPABILITY INDICATION"
190 .IX Header "CAPABILITY INDICATION"
191 The BIO datagram pair can be used to enqueue datagrams which have source and
192 destination addresses attached. It is important that the component consuming one
193 side of a BIO datagram pair understand whether the other side of the pair will
194 honour any source and destination addresses it attaches to each datagram. For
195 example, if datagrams are queued with destination addresses set but simply read
196 by simple calls to \fBBIO_read\fR\|(3), the destination addresses will be discarded.
197 .PP
198 Each half of a BIO datagram pair can have capability flags set on it which
199 indicate whether source and destination addresses will be honoured by the reader
200 and whether they will be provided by the writer. These capability flags should
201 be set via a call to \fBBIO_dgram_set_caps()\fR, and these capabilities will be
202 reflected in the value returned by \fBBIO_dgram_get_effective_caps()\fR on the
203 opposite BIO. If necessary, the capability value previously set can be retrieved
204 using \fBBIO_dgram_get_caps()\fR. Note that \fBBIO_dgram_set_caps()\fR on a given BIO
205 controls the capabilities advertised to the peer, and
206 \&\fBBIO_dgram_get_effective_caps()\fR on a given BIO determines the capabilities
207 advertised by the peer of that BIO.
208 .PP
209 The following capabilities are available:
210 .IP \fBBIO_DGRAM_CAP_HANDLES_SRC_ADDR\fR 4
211 .IX Item "BIO_DGRAM_CAP_HANDLES_SRC_ADDR"
212 The user of the datagram pair BIO promises to honour source addresses provided
213 with datagrams written to the BIO pair.
214 .IP \fBBIO_DGRAM_CAP_HANDLES_DST_ADDR\fR 4
215 .IX Item "BIO_DGRAM_CAP_HANDLES_DST_ADDR"
216 The user of the datagram pair BIO promises to honour destination addresses provided
217 with datagrams written to the BIO pair.
218 .IP \fBBIO_DGRAM_CAP_PROVIDES_SRC_ADDR\fR 4
219 .IX Item "BIO_DGRAM_CAP_PROVIDES_SRC_ADDR"
220 The user of the datagram pair BIO advertises the fact that it will provide source
221 addressing information with future writes to the BIO pair, where available.
222 .IP \fBBIO_DGRAM_CAP_PROVIDES_DST_ADDR\fR 4
223 .IX Item "BIO_DGRAM_CAP_PROVIDES_DST_ADDR"
224 The user of the datagram pair BIO advertises the fact that it will provide
225 destination addressing information with future writes to the BIO pair, where
226 available.
227 .PP
228 If a caller attempts to specify a destination address (for example, using
229 \&\fBBIO_sendmmsg\fR\|(3)) and the peer has not advertised the
230 \&\fBBIO_DGRAM_CAP_HANDLES_DST_ADDR\fR capability, the operation fails. Thus,
231 capability negotiation is mandatory.
232 .PP
233 If a caller attempts to specify a source address when writing, or requests a
234 destination address when receiving, and local address support has not been
235 enabled, the operation fails; see \fBBIO_dgram_set_local_addr_enable\fR\|(3).
236 .PP
237 If a caller attempts to enable local address support using
238 \&\fBBIO_dgram_set_local_addr_enable\fR\|(3) and \fBBIO_dgram_get_local_addr_cap\fR\|(3)
239 does not return 1 (meaning that the peer has not advertised both the
240 \&\fBBIO_DGRAM_CAP_HANDLES_SRC_ADDR\fR and the \fBBIO_DGRAM_CAP_PROVIDES_DST_ADDR\fR
241 capability), the operation fails.
242 .PP
243 \&\fBBIO_DGRAM_CAP_PROVIDES_SRC_ADDR\fR and \fBBIO_DGRAM_CAP_PROVIDES_DST_ADDR\fR
244 indicate that the application using that half of a BIO datagram pair promises to
245 provide source and destination addresses respectively when writing datagrams to
246 that half of the BIO datagram pair. However, these capability flags do not
247 affect the behaviour of the BIO datagram pair.
248 .SH "RETURN VALUES"
249 .IX Header "RETURN VALUES"
250 \&\fBBIO_new_bio_dgram_pair()\fR returns 1 on success, with the new BIOs available in
251 \&\fBbio1\fR and \fBbio2\fR, or 0 on failure, with NULL pointers stored into the
252 locations for \fBbio1\fR and \fBbio2\fR. Check the error stack for more information.
253 .PP
254 \&\fBBIO_dgram_set_no_trunc()\fR, \fBBIO_dgram_set_caps()\fR and \fBBIO_dgram_set_mtu()\fR return 1
255 on success and 0 on failure.
256 .PP
257 \&\fBBIO_dgram_get_no_trunc()\fR returns 1 if no-truncate mode is enabled on a BIO, or 0
258 if no-truncate mode is not enabled or not supported on a given BIO.
259 .PP
260 \&\fBBIO_dgram_get_effective_caps()\fR and \fBBIO_dgram_get_caps()\fR return zero if no
261 capabilities are supported.
262 .PP
263 \&\fBBIO_dgram_get_mtu()\fR returns the MTU value configured on the BIO, or zero if the
264 operation is not supported.
265 .PP
266 \&\fBBIO_dgram_set0_local_addr()\fR returns 1 on success and <= 0 otherwise.
267 .SH "SEE ALSO"
268 .IX Header "SEE ALSO"
269 \&\fBBIO_s_bio\fR\|(3), \fBbio\fR\|(7)
270 .SH HISTORY
271 .IX Header "HISTORY"
272 \&\fBBIO_s_dgram_pair()\fR, \fBBIO_new_bio_dgram_pair()\fR,
273 \&\fBBIO_dgram_get_caps()\fR, \fBBIO_dgram_get_effective_caps()\fR,
274 \&\fBBIO_dgram_get_no_trunc()\fR, \fBBIO_dgram_set_caps()\fR,
275 \&\fBBIO_dgram_set_mtu()\fR, \fBBIO_dgram_set_no_trunc()\fR were added in OpenSSL 3.2.
276 .PP
277 \&\fBBIO_dgram_set0_local_addr()\fR was added in OpenSSL 3.5.
278 .SH COPYRIGHT
279 .IX Header "COPYRIGHT"
280 Copyright 2022\-2025 The OpenSSL Project Authors. All Rights Reserved.
281 .PP
282 Licensed under the Apache License 2.0 (the "License"). You may not use
283 this file except in compliance with the License. You can obtain a copy
284 in the file LICENSE in the source distribution or at
285 <https://www.openssl.org/source/license.html>.