Debian Codegraph @

upstream/debian-unstable/man3/BIO_set_flags.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_SET_FLAGS 3SSL"
58 .TH BIO_SET_FLAGS 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_set_flags, BIO_clear_flags, BIO_test_flags, BIO_get_flags,
65 BIO_set_retry_read, BIO_set_retry_write, BIO_set_retry_special,
66 BIO_clear_retry_flags, BIO_get_retry_flags
67 \&\- manipulate and interpret BIO flags
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& #include <openssl/bio.h>
72 \&
73 \& void BIO_set_flags(BIO *b, int flags);
74 \& void BIO_clear_flags(BIO *b, int flags);
75 \& int BIO_test_flags(const BIO *b, int flags);
76 \& int BIO_get_flags(const BIO *b);
77 \&
78 \& void BIO_set_retry_read(BIO *b);
79 \& void BIO_set_retry_write(BIO *b);
80 \& void BIO_set_retry_special(BIO *b);
81 \& void BIO_clear_retry_flags(BIO *b);
82 \& int BIO_get_retry_flags(BIO *b);
83 .Ve
84 .SH DESCRIPTION
85 .IX Header "DESCRIPTION"
86 A \fBBIO\fR has an internal set of bit flags that describe its state. These
87 functions and macros are used primarily by \fBBIO\fR implementations and by code
88 that builds \fBBIO\fR chains to manipulate those flags.
89 .PP
90 \&\fBBIO_set_flags()\fR sets the bits given in \fIflags\fR in the \fBBIO\fR \fIb\fR. Any bits
91 already set in the \fBBIO\fR's flag word remain set.
92 .PP
93 \&\fBBIO_clear_flags()\fR clears the bits given in \fIflags\fR from the \fBBIO\fR \fIb\fR. Any
94 other bits in the flag word are left unchanged.
95 .PP
96 \&\fBBIO_test_flags()\fR tests the bits given in \fIflags\fR in the \fBBIO\fR \fIb\fR and
97 returns a nonzero value if any of them are currently set and zero
98 otherwise.
99 .PP
100 \&\fBBIO_get_flags()\fR returns the current flag word from the \fBBIO\fR \fIb\fR. This is
101 equivalent to testing for all bits and returning the result.
102 .PP
103 The following convenience macros are built on top of these primitives and are
104 used to maintain the retry state of a BIO:
105 .PP
106 \&\fBBIO_set_retry_read()\fR marks the \fBBIO\fR \fIb\fR as being in a retryable state
107 by setting the \fBBIO_FLAGS_SHOULD_RETRY\fR flag. In addition, it sets the
108 \&\fBBIO_FLAGS_READ\fR flag to indicate that the retry condition is
109 associated with a read operation.
110 .PP
111 \&\fBBIO_set_retry_write()\fR marks the \fBBIO\fR \fIb\fR as being in a retryable state
112 by setting the \fBBIO_FLAGS_SHOULD_RETRY\fR flag. In addition, it sets the
113 \&\fBBIO_FLAGS_WRITE\fR flag to indicate that the retry condition is
114 associated with a write operation.
115 .PP
116 \&\fBBIO_set_retry_special()\fR marks the \fBBIO\fR \fIb\fR as being in a retryable state
117 by setting the \fBBIO_FLAGS_SHOULD_RETRY\fR flag. In addition, it sets the
118 \&\fBBIO_FLAGS_IO_SPECIAL\fR flag to indicate that the retry condition is
119 associated with a read operation some "special" condition.
120 The precise meaning of this condition depends on the \fBBIO\fR type.
121 .PP
122 \&\fBBIO_clear_retry_flags()\fR clears all retry-related bits from \fIb\fR, i.e.
123 \&\fBBIO_FLAGS_READ\fR, \fBBIO_FLAGS_WRITE\fR, \fBBIO_FLAGS_IO_SPECIAL\fR, and
124 \&\fBBIO_FLAGS_SHOULD_RETRY\fR.
125 .PP
126 \&\fBBIO_get_retry_flags()\fR returns retry-related bits that are
127 currently set in \fIb\fR. The result is a subset of
128 \&\fBBIO_FLAGS_RWS|BIO_FLAGS_SHOULD_RETRY\fR.
129 .PP
130 The retry bits are interpreted by the higher level macros
131 \&\fBBIO_should_read()\fR, \fBBIO_should_write()\fR, \fBBIO_should_io_special()\fR,
132 \&\fBBIO_retry_type()\fR and \fBBIO_should_retry()\fR, as documented in
133 \&\fBBIO_should_retry\fR\|(3). Application code will typically use those macros
134 rather than manipulate the underlying flags directly.
135 .PP
136 The following flag bits are currently defined for use with \fBBIO_set_flags()\fR,
137 \&\fBBIO_clear_flags()\fR and \fBBIO_test_flags()\fR:
138 .IP \fBBIO_FLAGS_READ\fR 4
139 .IX Item "BIO_FLAGS_READ"
140 The last I/O operation should be retried when the \fBBIO\fR becomes readable.
141 This flag is normally set by the \fBBIO\fR implementation via \fBBIO_set_retry_read()\fR
142 after a failed read operation.
143 .IP \fBBIO_FLAGS_WRITE\fR 4
144 .IX Item "BIO_FLAGS_WRITE"
145 The last I/O operation should be retried when the \fBBIO\fR becomes writable.
146 This flag is normally set by the \fBBIO\fR implementation via \fBBIO_set_retry_write()\fR
147 after a failed write operation.
148 .IP \fBBIO_FLAGS_IO_SPECIAL\fR 4
149 .IX Item "BIO_FLAGS_IO_SPECIAL"
150 The last I/O operation should be retried when some "special" condition
151 becomes true. The precise meaning of this condition depends on the \fBBIO\fR
152 type and is usually obtained via \fBBIO_get_retry_BIO()\fR and
153 \&\fBBIO_get_retry_reason()\fR as described in \fBBIO_should_retry\fR\|(3).
154 This flag is normally set by the \fBBIO\fR implementation via
155 \&\fBBIO_set_retry_special()\fR.
156 .IP \fBBIO_FLAGS_RWS\fR 4
157 .IX Item "BIO_FLAGS_RWS"
158 The bitwise OR of \fBBIO_FLAGS_READ\fR, \fBBIO_FLAGS_WRITE\fR and
159 \&\fBBIO_FLAGS_IO_SPECIAL\fR. This mask is used when clearing or extracting
160 the retry-direction bits.
161 .IP \fBBIO_FLAGS_SHOULD_RETRY\fR 4
162 .IX Item "BIO_FLAGS_SHOULD_RETRY"
163 Set if the last I/O operation on the \fBBIO\fR should be retried at a later time.
164 If this bit is not set then the condition is treated as an error.
165 This flag is normally set by the \fBBIO\fR implementation.
166 .IP \fBBIO_FLAGS_BASE64_NO_NL\fR 4
167 .IX Item "BIO_FLAGS_BASE64_NO_NL"
168 When set on a base64 filter \fBBIO\fR this flag disables the generation of
169 newline characters in the encoded output and causes newlines to be ignored
170 in the input. See also \fBBIO_f_base64\fR\|(3).
171 The flag has no effect on any other built-in \fBBIO\fR types.
172 .IP \fBBIO_FLAGS_MEM_RDONLY\fR 4
173 .IX Item "BIO_FLAGS_MEM_RDONLY"
174 When set on a memory \fBBIO\fR this flag indicates that the underlying buffer is
175 read only. Attempts to write to such a \fBBIO\fR will fail.
176 The flag has no effect on any other built-in \fBBIO\fR types.
177 .IP \fBBIO_FLAGS_NONCLEAR_RST\fR 4
178 .IX Item "BIO_FLAGS_NONCLEAR_RST"
179 On a memory \fBBIO\fR this flag modifies the behaviour of \fBBIO_reset()\fR. When it
180 is set, resetting the \fBBIO\fR does not clear the underlying buffer but only
181 resets the current read position.
182 The flag has no effect on any other built-in \fBBIO\fR types.
183 .IP \fBBIO_FLAGS_IN_EOF\fR 4
184 .IX Item "BIO_FLAGS_IN_EOF"
185 This flag may be used by a \fBBIO\fR implementation to indicate that the end
186 of the input stream has been reached. However, \fBBIO\fR types are not
187 required to use this flag to signal end-of-file conditions; they may rely
188 on other mechanisms such as system calls or by querying the next \fBBIO\fR in a
189 chain. Applications must therefore not test this flag directly to
190 determine whether EOF has been reached, and must use \fBBIO_eof()\fR instead.
191 .PP
192 A range of additional flag values is reserved for internal use by OpenSSL
193 to track kernel TLS (KTLS) state. This range and the corresponding flag
194 macros are not part of the public API and must not be used by applications.
195 .SH "RETURN VALUES"
196 .IX Header "RETURN VALUES"
197 \&\fBBIO_get_flags()\fR returns a bit mask of the flags currently set on the \fBBIO\fR.
198 .PP
199 \&\fBBIO_test_flags()\fR returns a bit mask consisting of those flags from the
200 argument that are currently set in the \fBBIO\fR. Consequently, it returns a
201 nonzero value if and only if at least one of the requested flags is set.
202 .PP
203 \&\fBBIO_get_retry_flags()\fR returns a bit mask consisting of those flags from
204 \&\fBBIO_FLAGS_READ\fR, \fBBIO_FLAGS_WRITE\fR, \fBBIO_FLAGS_IO_SPECIAL\fR, and
205 \&\fBBIO_FLAGS_SHOULD_RETRY\fR that are currently set in the \fIBIO\fR.
206 .SH NOTES
207 .IX Header "NOTES"
208 Ordinary application code will rarely need to call \fBBIO_set_flags()\fR,
209 \&\fBBIO_clear_flags()\fR or \fBBIO_test_flags()\fR directly. They are intended for \fBBIO\fR
210 implementations and for code that forwards retry state from one \fBBIO\fR in a
211 chain to another.
212 After a failed I/O operation, applications should normally use
213 \&\fBBIO_should_retry()\fR and related macros as described in
214 \&\fBBIO_should_retry\fR\|(3) instead of inspecting the flags directly.
215 .PP
216 These functions and macros are not thread-safe. If a single \fBBIO\fR
217 is accessed from multiple threads, the caller must provide appropriate
218 external synchronisation.
219 .SH "SEE ALSO"
220 .IX Header "SEE ALSO"
221 \&\fBBIO_should_retry\fR\|(3), \fBBIO_f_base64\fR\|(3), \fBbio\fR\|(7)
222 .SH HISTORY
223 .IX Header "HISTORY"
224 The functions and macros described here have been available in OpenSSL since
225 at least 1.1.0 (\fBBIO_FLAGS_IN_EOF\fR since 1.1.1).
226 .SH COPYRIGHT
227 .IX Header "COPYRIGHT"
228 Copyright 2025 The OpenSSL Project Authors. All Rights Reserved.
229 .PP
230 Licensed under the Apache License 2.0 (the "License"). You may not use
231 this file except in compliance with the License. You can obtain a copy
232 in the file LICENSE in the source distribution or at
233 <https://www.openssl.org/source/license.html>.