1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
|
.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Required to disable full justification in groff 1.23.0.
.if n .ds AD l
.\" ========================================================================
.\"
.IX Title "BIO_SET_FLAGS 3ossl"
.TH BIO_SET_FLAGS 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
.nh
.SH NAME
BIO_set_flags, BIO_clear_flags, BIO_test_flags, BIO_get_flags,
BIO_set_retry_read, BIO_set_retry_write, BIO_set_retry_special,
BIO_clear_retry_flags, BIO_get_retry_flags
\&\- manipulate and interpret BIO flags
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bio.h>
\&
\& void BIO_set_flags(BIO *b, int flags);
\& void BIO_clear_flags(BIO *b, int flags);
\& int BIO_test_flags(const BIO *b, int flags);
\& int BIO_get_flags(const BIO *b);
\&
\& void BIO_set_retry_read(BIO *b);
\& void BIO_set_retry_write(BIO *b);
\& void BIO_set_retry_special(BIO *b);
\& void BIO_clear_retry_flags(BIO *b);
\& int BIO_get_retry_flags(BIO *b);
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
A \fBBIO\fR has an internal set of bit flags that describe its state. These
functions and macros are used primarily by \fBBIO\fR implementations and by code
that builds \fBBIO\fR chains to manipulate those flags.
.PP
\&\fBBIO_set_flags()\fR sets the bits given in \fIflags\fR in the \fBBIO\fR \fIb\fR. Any bits
already set in the \fBBIO\fR\*(Aqs flag word remain set.
.PP
\&\fBBIO_clear_flags()\fR clears the bits given in \fIflags\fR from the \fBBIO\fR \fIb\fR. Any
other bits in the flag word are left unchanged.
.PP
\&\fBBIO_test_flags()\fR tests the bits given in \fIflags\fR in the \fBBIO\fR \fIb\fR and
returns a nonzero value if any of them are currently set and zero
otherwise.
.PP
\&\fBBIO_get_flags()\fR returns the current flag word from the \fBBIO\fR \fIb\fR. This is
equivalent to testing for all bits and returning the result.
.PP
The following convenience macros are built on top of these primitives and are
used to maintain the retry state of a BIO:
.PP
\&\fBBIO_set_retry_read()\fR marks the \fBBIO\fR \fIb\fR as being in a retryable state
by setting the \fBBIO_FLAGS_SHOULD_RETRY\fR flag. In addition, it sets the
\&\fBBIO_FLAGS_READ\fR flag to indicate that the retry condition is
associated with a read operation.
.PP
\&\fBBIO_set_retry_write()\fR marks the \fBBIO\fR \fIb\fR as being in a retryable state
by setting the \fBBIO_FLAGS_SHOULD_RETRY\fR flag. In addition, it sets the
\&\fBBIO_FLAGS_WRITE\fR flag to indicate that the retry condition is
associated with a write operation.
.PP
\&\fBBIO_set_retry_special()\fR marks the \fBBIO\fR \fIb\fR as being in a retryable state
by setting the \fBBIO_FLAGS_SHOULD_RETRY\fR flag. In addition, it sets the
\&\fBBIO_FLAGS_IO_SPECIAL\fR flag to indicate that the retry condition is
associated with a read operation some "special" condition.
The precise meaning of this condition depends on the \fBBIO\fR type.
.PP
\&\fBBIO_clear_retry_flags()\fR clears all retry\-related bits from \fIb\fR, i.e.
\&\fBBIO_FLAGS_READ\fR, \fBBIO_FLAGS_WRITE\fR, \fBBIO_FLAGS_IO_SPECIAL\fR, and
\&\fBBIO_FLAGS_SHOULD_RETRY\fR.
.PP
\&\fBBIO_get_retry_flags()\fR returns retry\-related bits that are
currently set in \fIb\fR. The result is a subset of
\&\fBBIO_FLAGS_RWS|BIO_FLAGS_SHOULD_RETRY\fR.
.PP
The retry bits are interpreted by the higher level macros
\&\fBBIO_should_read()\fR, \fBBIO_should_write()\fR, \fBBIO_should_io_special()\fR,
\&\fBBIO_retry_type()\fR and \fBBIO_should_retry()\fR, as documented in
\&\fBBIO_should_retry\fR\|(3). Application code will typically use those macros
rather than manipulate the underlying flags directly.
.PP
The following flag bits are currently defined for use with \fBBIO_set_flags()\fR,
\&\fBBIO_clear_flags()\fR and \fBBIO_test_flags()\fR:
.IP \fBBIO_FLAGS_READ\fR 4
.IX Item "BIO_FLAGS_READ"
The last I/O operation should be retried when the \fBBIO\fR becomes readable.
This flag is normally set by the \fBBIO\fR implementation via \fBBIO_set_retry_read()\fR
after a failed read operation.
.IP \fBBIO_FLAGS_WRITE\fR 4
.IX Item "BIO_FLAGS_WRITE"
The last I/O operation should be retried when the \fBBIO\fR becomes writable.
This flag is normally set by the \fBBIO\fR implementation via \fBBIO_set_retry_write()\fR
after a failed write operation.
.IP \fBBIO_FLAGS_IO_SPECIAL\fR 4
.IX Item "BIO_FLAGS_IO_SPECIAL"
The last I/O operation should be retried when some "special" condition
becomes true. The precise meaning of this condition depends on the \fBBIO\fR
type and is usually obtained via \fBBIO_get_retry_BIO()\fR and
\&\fBBIO_get_retry_reason()\fR as described in \fBBIO_should_retry\fR\|(3).
This flag is normally set by the \fBBIO\fR implementation via
\&\fBBIO_set_retry_special()\fR.
.IP \fBBIO_FLAGS_RWS\fR 4
.IX Item "BIO_FLAGS_RWS"
The bitwise OR of \fBBIO_FLAGS_READ\fR, \fBBIO_FLAGS_WRITE\fR and
\&\fBBIO_FLAGS_IO_SPECIAL\fR. This mask is used when clearing or extracting
the retry\-direction bits.
.IP \fBBIO_FLAGS_SHOULD_RETRY\fR 4
.IX Item "BIO_FLAGS_SHOULD_RETRY"
Set if the last I/O operation on the \fBBIO\fR should be retried at a later time.
If this bit is not set then the condition is treated as an error.
This flag is normally set by the \fBBIO\fR implementation.
.IP \fBBIO_FLAGS_BASE64_NO_NL\fR 4
.IX Item "BIO_FLAGS_BASE64_NO_NL"
When set on a base64 filter \fBBIO\fR this flag disables the generation of
newline characters in the encoded output and causes newlines to be ignored
in the input. See also \fBBIO_f_base64\fR\|(3).
The flag has no effect on any other built\-in \fBBIO\fR types.
.IP \fBBIO_FLAGS_MEM_RDONLY\fR 4
.IX Item "BIO_FLAGS_MEM_RDONLY"
When set on a memory \fBBIO\fR this flag indicates that the underlying buffer is
read only. Attempts to write to such a \fBBIO\fR will fail.
The flag has no effect on any other built\-in \fBBIO\fR types.
.IP \fBBIO_FLAGS_NONCLEAR_RST\fR 4
.IX Item "BIO_FLAGS_NONCLEAR_RST"
On a memory \fBBIO\fR this flag modifies the behaviour of \fBBIO_reset()\fR. When it
is set, resetting the \fBBIO\fR does not clear the underlying buffer but only
resets the current read position.
The flag has no effect on any other built\-in \fBBIO\fR types.
.IP \fBBIO_FLAGS_IN_EOF\fR 4
.IX Item "BIO_FLAGS_IN_EOF"
This flag may be used by a \fBBIO\fR implementation to indicate that the end
of the input stream has been reached. However, \fBBIO\fR types are not
required to use this flag to signal end\-of\-file conditions; they may rely
on other mechanisms such as system calls or by querying the next \fBBIO\fR in a
chain. Applications must therefore not test this flag directly to
determine whether EOF has been reached, and must use \fBBIO_eof()\fR instead.
.PP
A range of additional flag values is reserved for internal use by OpenSSL
to track kernel TLS (KTLS) state. This range and the corresponding flag
macros are not part of the public API and must not be used by applications.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBBIO_get_flags()\fR returns a bit mask of the flags currently set on the \fBBIO\fR.
.PP
\&\fBBIO_test_flags()\fR returns a bit mask consisting of those flags from the
argument that are currently set in the \fBBIO\fR. Consequently, it returns a
nonzero value if and only if at least one of the requested flags is set.
.PP
\&\fBBIO_get_retry_flags()\fR returns a bit mask consisting of those flags from
\&\fBBIO_FLAGS_READ\fR, \fBBIO_FLAGS_WRITE\fR, \fBBIO_FLAGS_IO_SPECIAL\fR, and
\&\fBBIO_FLAGS_SHOULD_RETRY\fR that are currently set in the \fIBIO\fR.
.SH NOTES
.IX Header "NOTES"
Ordinary application code will rarely need to call \fBBIO_set_flags()\fR,
\&\fBBIO_clear_flags()\fR or \fBBIO_test_flags()\fR directly. They are intended for \fBBIO\fR
implementations and for code that forwards retry state from one \fBBIO\fR in a
chain to another.
After a failed I/O operation, applications should normally use
\&\fBBIO_should_retry()\fR and related macros as described in
\&\fBBIO_should_retry\fR\|(3) instead of inspecting the flags directly.
.PP
These functions and macros are not thread\-safe. If a single \fBBIO\fR
is accessed from multiple threads, the caller must provide appropriate
external synchronisation.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBBIO_should_retry\fR\|(3), \fBBIO_f_base64\fR\|(3), \fBbio\fR\|(7)
.SH HISTORY
.IX Header "HISTORY"
The functions and macros described here have been available in OpenSSL since
at least 1.1.0 (\fBBIO_FLAGS_IN_EOF\fR since 1.1.1).
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright 2025 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
<https://www.openssl.org/source/license.html>.
|
