1=pod 2 3=head1 NAME 4 5BIO_set_flags, BIO_clear_flags, BIO_test_flags, BIO_get_flags, 6BIO_set_retry_read, BIO_set_retry_write, BIO_set_retry_special, 7BIO_clear_retry_flags, BIO_get_retry_flags 8- manipulate and interpret BIO flags 9 10=head1 SYNOPSIS 11 12 #include <openssl/bio.h> 13 14 void BIO_set_flags(BIO *b, int flags); 15 void BIO_clear_flags(BIO *b, int flags); 16 int BIO_test_flags(const BIO *b, int flags); 17 int BIO_get_flags(const BIO *b); 18 19 void BIO_set_retry_read(BIO *b); 20 void BIO_set_retry_write(BIO *b); 21 void BIO_set_retry_special(BIO *b); 22 void BIO_clear_retry_flags(BIO *b); 23 int BIO_get_retry_flags(BIO *b); 24 25=head1 DESCRIPTION 26 27A B<BIO> has an internal set of bit flags that describe its state. These 28functions and macros are used primarily by B<BIO> implementations and by code 29that builds B<BIO> chains to manipulate those flags. 30 31BIO_set_flags() sets the bits given in I<flags> in the B<BIO> I<b>. Any bits 32already set in the B<BIO>'s flag word remain set. 33 34BIO_clear_flags() clears the bits given in I<flags> from the B<BIO> I<b>. Any 35other bits in the flag word are left unchanged. 36 37BIO_test_flags() tests the bits given in I<flags> in the B<BIO> I<b> and 38returns a nonzero value if any of them are currently set and zero 39otherwise. 40 41BIO_get_flags() returns the current flag word from the B<BIO> I<b>. This is 42equivalent to testing for all bits and returning the result. 43 44The following convenience macros are built on top of these primitives and are 45used to maintain the retry state of a BIO: 46 47BIO_set_retry_read() marks the B<BIO> I<b> as being in a retryable state 48by setting the B<BIO_FLAGS_SHOULD_RETRY> flag. In addition, it sets the 49B<BIO_FLAGS_READ> flag to indicate that the retry condition is 50associated with a read operation. 51 52BIO_set_retry_write() marks the B<BIO> I<b> as being in a retryable state 53by setting the B<BIO_FLAGS_SHOULD_RETRY> flag. In addition, it sets the 54B<BIO_FLAGS_WRITE> flag to indicate that the retry condition is 55associated with a write operation. 56 57BIO_set_retry_special() marks the B<BIO> I<b> as being in a retryable state 58by setting the B<BIO_FLAGS_SHOULD_RETRY> flag. In addition, it sets the 59B<BIO_FLAGS_IO_SPECIAL> flag to indicate that the retry condition is 60associated with a read operation some "special" condition. 61The precise meaning of this condition depends on the B<BIO> type. 62 63BIO_clear_retry_flags() clears all retry-related bits from I<b>, i.e. 64B<BIO_FLAGS_READ>, B<BIO_FLAGS_WRITE>, B<BIO_FLAGS_IO_SPECIAL>, and 65B<BIO_FLAGS_SHOULD_RETRY>. 66 67BIO_get_retry_flags() returns retry-related bits that are 68currently set in I<b>. The result is a subset of 69B<BIO_FLAGS_RWS|BIO_FLAGS_SHOULD_RETRY>. 70 71The retry bits are interpreted by the higher level macros 72BIO_should_read(), BIO_should_write(), BIO_should_io_special(), 73BIO_retry_type() and BIO_should_retry(), as documented in 74L<BIO_should_retry(3)>. Application code will typically use those macros 75rather than manipulate the underlying flags directly. 76 77The following flag bits are currently defined for use with BIO_set_flags(), 78BIO_clear_flags() and BIO_test_flags(): 79 80=over 4 81 82=item B<BIO_FLAGS_READ> 83 84The last I/O operation should be retried when the B<BIO> becomes readable. 85This flag is normally set by the B<BIO> implementation via BIO_set_retry_read() 86after a failed read operation. 87 88=item B<BIO_FLAGS_WRITE> 89 90The last I/O operation should be retried when the B<BIO> becomes writable. 91This flag is normally set by the B<BIO> implementation via BIO_set_retry_write() 92after a failed write operation. 93 94=item B<BIO_FLAGS_IO_SPECIAL> 95 96The last I/O operation should be retried when some "special" condition 97becomes true. The precise meaning of this condition depends on the B<BIO> 98type and is usually obtained via BIO_get_retry_BIO() and 99BIO_get_retry_reason() as described in L<BIO_should_retry(3)>. 100This flag is normally set by the B<BIO> implementation via 101BIO_set_retry_special(). 102 103=item B<BIO_FLAGS_RWS> 104 105The bitwise OR of B<BIO_FLAGS_READ>, B<BIO_FLAGS_WRITE> and 106B<BIO_FLAGS_IO_SPECIAL>. This mask is used when clearing or extracting 107the retry-direction bits. 108 109=item B<BIO_FLAGS_SHOULD_RETRY> 110 111Set if the last I/O operation on the B<BIO> should be retried at a later time. 112If this bit is not set then the condition is treated as an error. 113This flag is normally set by the B<BIO> implementation. 114 115=item B<BIO_FLAGS_BASE64_NO_NL> 116 117When set on a base64 filter B<BIO> this flag disables the generation of 118newline characters in the encoded output and causes newlines to be ignored 119in the input. See also L<BIO_f_base64(3)>. 120The flag has no effect on any other built-in B<BIO> types. 121 122=item B<BIO_FLAGS_MEM_RDONLY> 123 124When set on a memory B<BIO> this flag indicates that the underlying buffer is 125read only. Attempts to write to such a B<BIO> will fail. 126The flag has no effect on any other built-in B<BIO> types. 127 128=item B<BIO_FLAGS_NONCLEAR_RST> 129 130On a memory B<BIO> this flag modifies the behaviour of BIO_reset(). When it 131is set, resetting the B<BIO> does not clear the underlying buffer but only 132resets the current read position. 133The flag has no effect on any other built-in B<BIO> types. 134 135=item B<BIO_FLAGS_IN_EOF> 136 137This flag may be used by a B<BIO> implementation to indicate that the end 138of the input stream has been reached. However, B<BIO> types are not 139required to use this flag to signal end-of-file conditions; they may rely 140on other mechanisms such as system calls or by querying the next B<BIO> in a 141chain. Applications must therefore not test this flag directly to 142determine whether EOF has been reached, and must use BIO_eof() instead. 143 144=back 145 146A range of additional flag values is reserved for internal use by OpenSSL 147to track kernel TLS (KTLS) state. This range and the corresponding flag 148macros are not part of the public API and must not be used by applications. 149 150=head1 RETURN VALUES 151 152BIO_get_flags() returns a bit mask of the flags currently set on the B<BIO>. 153 154BIO_test_flags() returns a bit mask consisting of those flags from the 155argument that are currently set in the B<BIO>. Consequently, it returns a 156nonzero value if and only if at least one of the requested flags is set. 157 158BIO_get_retry_flags() returns a bit mask consisting of those flags from 159B<BIO_FLAGS_READ>, B<BIO_FLAGS_WRITE>, B<BIO_FLAGS_IO_SPECIAL>, and 160B<BIO_FLAGS_SHOULD_RETRY> that are currently set in the I<BIO>. 161 162=head1 NOTES 163 164Ordinary application code will rarely need to call BIO_set_flags(), 165BIO_clear_flags() or BIO_test_flags() directly. They are intended for B<BIO> 166implementations and for code that forwards retry state from one B<BIO> in a 167chain to another. 168After a failed I/O operation, applications should normally use 169BIO_should_retry() and related macros as described in 170L<BIO_should_retry(3)> instead of inspecting the flags directly. 171 172These functions and macros are not thread-safe. If a single B<BIO> 173is accessed from multiple threads, the caller must provide appropriate 174external synchronisation. 175 176=head1 SEE ALSO 177 178L<BIO_should_retry(3)>, L<BIO_f_base64(3)>, L<bio(7)> 179 180=head1 HISTORY 181 182The functions and macros described here have been available in OpenSSL since 183at least 1.1.0 (B<BIO_FLAGS_IN_EOF> since 1.1.1). 184 185=head1 COPYRIGHT 186 187Copyright 2025 The OpenSSL Project Authors. All Rights Reserved. 188 189Licensed under the Apache License 2.0 (the "License"). You may not use 190this file except in compliance with the License. You can obtain a copy 191in the file LICENSE in the source distribution or at 192L<https://www.openssl.org/source/license.html>. 193 194=cut 195