From: Igor Ustinov Date: Thu, 4 Dec 2025 16:05:59 +0000 (+0100) Subject: Documentation for BIO flags and related functions. X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=004299c56eac58dd05a7caabf53b7876cb5138a5;p=thirdparty%2Fopenssl.git Documentation for BIO flags and related functions. Reviewed-by: Frederik Wedel-Heinen Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/29311) (cherry picked from commit e12870deb022555dd15678ff745c33ff19b65dfe) --- diff --git a/doc/build.info b/doc/build.info index 229d1d4b4f2..18a33bd3685 100644 --- a/doc/build.info +++ b/doc/build.info @@ -707,6 +707,10 @@ DEPEND[html/man3/BIO_set_callback.html]=man3/BIO_set_callback.pod GENERATE[html/man3/BIO_set_callback.html]=man3/BIO_set_callback.pod DEPEND[man/man3/BIO_set_callback.3]=man3/BIO_set_callback.pod GENERATE[man/man3/BIO_set_callback.3]=man3/BIO_set_callback.pod +DEPEND[html/man3/BIO_set_flags.html]=man3/BIO_set_flags.pod +GENERATE[html/man3/BIO_set_flags.html]=man3/BIO_set_flags.pod +DEPEND[man/man3/BIO_set_flags.3]=man3/BIO_set_flags.pod +GENERATE[man/man3/BIO_set_flags.3]=man3/BIO_set_flags.pod DEPEND[html/man3/BIO_should_retry.html]=man3/BIO_should_retry.pod GENERATE[html/man3/BIO_should_retry.html]=man3/BIO_should_retry.pod DEPEND[man/man3/BIO_should_retry.3]=man3/BIO_should_retry.pod @@ -3236,6 +3240,7 @@ html/man3/BIO_s_null.html \ html/man3/BIO_s_socket.html \ html/man3/BIO_sendmmsg.html \ html/man3/BIO_set_callback.html \ +html/man3/BIO_set_flags.html \ html/man3/BIO_should_retry.html \ html/man3/BIO_socket_wait.html \ html/man3/BN_BLINDING_new.html \ @@ -3910,6 +3915,7 @@ man/man3/BIO_s_null.3 \ man/man3/BIO_s_socket.3 \ man/man3/BIO_sendmmsg.3 \ man/man3/BIO_set_callback.3 \ +man/man3/BIO_set_flags.3 \ man/man3/BIO_should_retry.3 \ man/man3/BIO_socket_wait.3 \ man/man3/BN_BLINDING_new.3 \ diff --git a/doc/man3/BIO_set_flags.pod b/doc/man3/BIO_set_flags.pod new file mode 100644 index 00000000000..7899cc3e575 --- /dev/null +++ b/doc/man3/BIO_set_flags.pod @@ -0,0 +1,194 @@ +=pod + +=head1 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 + +=head1 SYNOPSIS + + #include + + 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); + +=head1 DESCRIPTION + +A B has an internal set of bit flags that describe its state. These +functions and macros are used primarily by B implementations and by code +that builds B chains to manipulate those flags. + +BIO_set_flags() sets the bits given in I in the B I. Any bits +already set in the B's flag word remain set. + +BIO_clear_flags() clears the bits given in I from the B I. Any +other bits in the flag word are left unchanged. + +BIO_test_flags() tests the bits given in I in the B I and +returns a nonzero value if any of them are currently set and zero +otherwise. + +BIO_get_flags() returns the current flag word from the B I. This is +equivalent to testing for all bits and returning the result. + +The following convenience macros are built on top of these primitives and are +used to maintain the retry state of a BIO: + +BIO_set_retry_read() marks the B I as being in a retryable state +by setting the B flag. In addition, it sets the +B flag to indicate that the retry condition is +associated with a read operation. + +BIO_set_retry_write() marks the B I as being in a retryable state +by setting the B flag. In addition, it sets the +B flag to indicate that the retry condition is +associated with a write operation. + +BIO_set_retry_special() marks the B I as being in a retryable state +by setting the B flag. In addition, it sets the +B 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 B type. + +BIO_clear_retry_flags() clears all retry-related bits from I, i.e. +B, B, B, and +B. + +BIO_get_retry_flags() returns retry-related bits that are +currently set in I. The result is a subset of +B. + +The retry bits are interpreted by the higher level macros +BIO_should_read(), BIO_should_write(), BIO_should_io_special(), +BIO_retry_type() and BIO_should_retry(), as documented in +L. Application code will typically use those macros +rather than manipulate the underlying flags directly. + +The following flag bits are currently defined for use with BIO_set_flags(), +BIO_clear_flags() and BIO_test_flags(): + +=over 4 + +=item B + +The last I/O operation should be retried when the B becomes readable. +This flag is normally set by the B implementation via BIO_set_retry_read() +after a failed read operation. + +=item B + +The last I/O operation should be retried when the B becomes writable. +This flag is normally set by the B implementation via BIO_set_retry_write() +after a failed write operation. + +=item B + +The last I/O operation should be retried when some "special" condition +becomes true. The precise meaning of this condition depends on the B +type and is usually obtained via BIO_get_retry_BIO() and +BIO_get_retry_reason() as described in L. +This flag is normally set by the B implementation via +BIO_set_retry_special(). + +=item B + +The bitwise OR of B, B and +B. This mask is used when clearing or extracting +the retry-direction bits. + +=item B + +Set if the last I/O operation on the B 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 B implementation. + +=item B + +When set on a base64 filter B this flag disables the generation of +newline characters in the encoded output and causes newlines to be ignored +in the input. See also L. +The flag has no effect on any other built-in B types. + +=item B + +When set on a memory B this flag indicates that the underlying buffer is +read only. Attempts to write to such a B will fail. +The flag has no effect on any other built-in B types. + +=item B + +On a memory B this flag modifies the behaviour of BIO_reset(). When it +is set, resetting the B does not clear the underlying buffer but only +resets the current read position. +The flag has no effect on any other built-in B types. + +=item B + +This flag may be used by a B implementation to indicate that the end +of the input stream has been reached. However, B 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 B in a +chain. Applications must therefore not test this flag directly to +determine whether EOF has been reached, and must use BIO_eof() instead. + +=back + +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. + +=head1 RETURN VALUES + +BIO_get_flags() returns a bit mask of the flags currently set on the B. + +BIO_test_flags() returns a bit mask consisting of those flags from the +argument that are currently set in the B. Consequently, it returns a +nonzero value if and only if at least one of the requested flags is set. + +BIO_get_retry_flags() returns a bit mask consisting of those flags from +B, B, B, and +B that are currently set in the I. + +=head1 NOTES + +Ordinary application code will rarely need to call BIO_set_flags(), +BIO_clear_flags() or BIO_test_flags() directly. They are intended for B +implementations and for code that forwards retry state from one B in a +chain to another. +After a failed I/O operation, applications should normally use +BIO_should_retry() and related macros as described in +L instead of inspecting the flags directly. + +These functions and macros are not thread-safe. If a single B +is accessed from multiple threads, the caller must provide appropriate +external synchronisation. + +=head1 SEE ALSO + +L, L, L + +=head1 HISTORY + +The functions and macros described here have been available in OpenSSL since +at least 1.1.0 (B since 1.1.1). + +=head1 COPYRIGHT + +Copyright 2025 The OpenSSL Project Authors. All Rights Reserved. + +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 +L. + +=cut diff --git a/util/missingcrypto.txt b/util/missingcrypto.txt index 9e6ce68e802..a6666f14e72 100644 --- a/util/missingcrypto.txt +++ b/util/missingcrypto.txt @@ -170,7 +170,6 @@ BIO_asn1_get_prefix(3) BIO_asn1_get_suffix(3) BIO_asn1_set_prefix(3) BIO_asn1_set_suffix(3) -BIO_clear_flags(3) BIO_copy_next_retry(3) BIO_dgram_is_sctp(3) BIO_dgram_non_fatal_error(3) @@ -208,7 +207,6 @@ BIO_nwrite(3) BIO_nwrite0(3) BIO_s_datagram_sctp(3) BIO_s_log(3) -BIO_set_flags(3) BIO_set_tcp_ndelay(3) BIO_sock_error(3) BIO_sock_info(3) @@ -217,7 +215,6 @@ BIO_sock_non_fatal_error(3) BIO_sock_should_retry(3) BIO_socket_ioctl(3) BIO_socket_nbio(3) -BIO_test_flags(3) BN_GF2m_add(3) BN_GF2m_arr2poly(3) BN_GF2m_mod(3) diff --git a/util/other.syms b/util/other.syms index 80488efa10b..66635d79b24 100644 --- a/util/other.syms +++ b/util/other.syms @@ -220,6 +220,8 @@ BIO_get_conn_port define BIO_get_conn_ip_family define BIO_get_conn_mode define BIO_get_fd define +BIO_get_flags define +BIO_get_retry_flags define BIO_get_fp define BIO_get_indent define BIO_get_info_callback define @@ -254,6 +256,12 @@ BIO_set_conn_port define BIO_set_conn_ip_family define BIO_set_conn_mode define BIO_set_fd define +BIO_set_flags define +BIO_set_retry_read define +BIO_set_retry_write define +BIO_set_retry_special define +BIO_clear_flags define +BIO_clear_retry_flags define BIO_set_fp define BIO_set_indent define BIO_set_info_callback define