Enji Cooper
5254e16213
A new manpage and any associated links will be added in the next commit.
MFC after: 1 day (the security issues warrant a quick backport).
MFC with: 10a428653e
237 lines
9.8 KiB
Plaintext
237 lines
9.8 KiB
Plaintext
.\" -*- 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>.
|