diff options
Diffstat (limited to 'static/freebsd/man3/BIO_set_flags.3')
| -rw-r--r-- | static/freebsd/man3/BIO_set_flags.3 | 236 |
1 files changed, 236 insertions, 0 deletions
diff --git a/static/freebsd/man3/BIO_set_flags.3 b/static/freebsd/man3/BIO_set_flags.3 new file mode 100644 index 00000000..918d9ec6 --- /dev/null +++ b/static/freebsd/man3/BIO_set_flags.3 @@ -0,0 +1,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>. |