docs: Added All NetBSD Manuals

1 files changed, 430 insertions, 0 deletions

diff --git a/static/netbsd/man3/SSL_poll.3 b/static/netbsd/man3/SSL_poll.3
new file mode 100644
index 00000000..4453468a
--- /dev/null
+++ b/static/netbsd/man3/SSL_poll.3
@@ -0,0 +1,430 @@
+.\"	$NetBSD: SSL_poll.3,v 1.5 2026/04/08 17:06:48 christos Exp $
+.\"
+.\" -*- 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 "SSL_poll 3"
+.TH SSL_poll 3 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
+SSL_poll,
+SSL_POLL_EVENT_NONE,
+SSL_POLL_EVENT_F,
+SSL_POLL_EVENT_EL,
+SSL_POLL_EVENT_EC,
+SSL_POLL_EVENT_ECD,
+SSL_POLL_EVENT_ER,
+SSL_POLL_EVENT_EW,
+SSL_POLL_EVENT_R,
+SSL_POLL_EVENT_W,
+SSL_POLL_EVENT_IC,
+SSL_POLL_EVENT_ISB,
+SSL_POLL_EVENT_ISU,
+SSL_POLL_EVENT_OSB,
+SSL_POLL_EVENT_OSU,
+SSL_POLL_EVENT_RW,
+SSL_POLL_EVENT_RE,
+SSL_POLL_EVENT_WE,
+SSL_POLL_EVENT_RWE,
+SSL_POLL_EVENT_E,
+SSL_POLL_EVENT_IS,
+SSL_POLL_EVENT_ISE,
+SSL_POLL_EVENT_I,
+SSL_POLL_EVENT_OS,
+SSL_POLL_EVENT_OSE,
+SSL_POLL_FLAG_NO_HANDLE_EVENTS
+\&\- determine or await readiness conditions for one or more pollable objects
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 1
+\& #include <openssl/ssl.h>
+\&
+\& #define SSL_POLL_EVENT_NONE        0
+\&
+\& #define SSL_POLL_EVENT_F           /* F   (Failure) */
+\& #define SSL_POLL_EVENT_EL          /* EL  (Exception on Listener) */
+\& #define SSL_POLL_EVENT_EC          /* EC  (Exception on Conn) */
+\& #define SSL_POLL_EVENT_ECD         /* ECD (Exception on Conn Drained) */
+\& #define SSL_POLL_EVENT_ER          /* ER  (Exception on Read) */
+\& #define SSL_POLL_EVENT_EW          /* EW  (Exception on Write) */
+\& #define SSL_POLL_EVENT_R           /* R   (Readable) */
+\& #define SSL_POLL_EVENT_W           /* W   (Writable) */
+\& #define SSL_POLL_EVENT_IC          /* IC  (Incoming Connection) */
+\& #define SSL_POLL_EVENT_ISB         /* ISB (Incoming Stream: Bidi) */
+\& #define SSL_POLL_EVENT_ISU         /* ISU (Incoming Stream: Uni) */
+\& #define SSL_POLL_EVENT_OSB         /* OSB (Outgoing Stream: Bidi) */
+\& #define SSL_POLL_EVENT_OSU         /* OSU (Outgoing Stream: Uni) */
+\&
+\& #define SSL_POLL_EVENT_RW          /* R   | W               */
+\& #define SSL_POLL_EVENT_RE          /* R   | ER              */
+\& #define SSL_POLL_EVENT_WE          /* W   | EW              */
+\& #define SSL_POLL_EVENT_RWE         /* RE  | WE              */
+\& #define SSL_POLL_EVENT_E           /* EL  | EC  | ER  | EW  */
+\& #define SSL_POLL_EVENT_IS          /* ISB | ISU             */
+\& #define SSL_POLL_EVENT_ISE         /* IS  | EC              */
+\& #define SSL_POLL_EVENT_I           /* IS                    */
+\& #define SSL_POLL_EVENT_OS          /* OSB | OSU             */
+\& #define SSL_POLL_EVENT_OSE         /* OS  | EC              */
+\&
+\& typedef struct ssl_poll_item_st {
+\&     BIO_POLL_DESCRIPTOR desc;
+\&     uint64_t            events, revents;
+\& } SSL_POLL_ITEM;
+\&
+\& #define SSL_POLL_FLAG_NO_HANDLE_EVENTS
+\&
+\& int SSL_poll(SSL_POLL_ITEM         *items,
+\&              size_t                num_items,
+\&              size_t                stride,
+\&              const struct timeval  *timeout,
+\&              uint64_t              flags,
+\&              size_t                *result_count);
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+\&\fBSSL_poll()\fR allows the readiness conditions of the resources represented by one
+or more BIO_POLL_DESCRIPTOR structures to be determined. In particular, it can
+be used to query for readiness conditions on QUIC connection SSL objects and
+QUIC stream SSL objects in a single call. It can also be used to block until at
+least one of the given resources is ready.
+.PP
+A call to \fBSSL_poll()\fR specifies an array of \fBSSL_POLL_ITEM\fR structures, each of
+which designates a resource which is being polled for readiness, and a set of
+event flags which indicate the specific readiness events which the caller is
+interested in in relation to the specified resource.
+.PP
+The fields of \fBSSL_POLL_ITEM\fR are as follows:
+.IP \fIdesc\fR 4
+.IX Item "desc"
+The resource being polled for readiness, as represented by a
+\&\fBBIO_POLL_DESCRIPTOR\fR. Currently, this must be a poll descriptor of type
+\&\fBBIO_POLL_DESCRIPTOR_TYPE_SSL\fR, representing an SSL object pointer, and the SSL
+object must be a QUIC connection SSL object or QUIC stream SSL object.
+.Sp
+If a \fBSSL_POLL_ITEM\fR has a poll descriptor type of
+\&\fBBIO_POLL_DESCRIPTOR_TYPE_NONE\fR, or the SSL object pointer is NULL, the
+\&\fBSSL_POLL_ITEM\fR array entry is ignored and \fIrevents\fR will be set to 0 on
+return.
+.IP \fIevents\fR 4
+.IX Item "events"
+This is the set of zero or more events which the caller is interested in
+learning about in relation to the resource described by \fIdesc\fR. It is a
+collection of zero or more \fBSSL_POLL_EVENT\fR flags. See "EVENT TYPES" for a
+description of each of the event types.
+.IP \fIrevents\fR 4
+.IX Item "revents"
+After \fBSSL_poll()\fR returns, this is the set of zero or more events which are
+actually applicable to the resource described by \fIdesc\fR. As for \fIevents\fR,
+it is a collection of zero or more \fBSSL_POLL_EVENT\fR flags.
+.Sp
+\&\fIrevents\fR need not be a subset of the events specified in \fIevents\fR, as some
+event types are defined as always being enabled (non\-maskable). See "EVENT
+TYPES" for more information.
+.PP
+To use \fBSSL_poll()\fR, call it with an array of \fBSSL_POLL_ITEM\fR structures. The
+array need remain allocated only for the duration of the call. \fInum_items\fR must
+be set to the number of entries in the array, and \fIstride\fR must be set to
+\&\f(CWsizeof(SSL_POLL_ITEM)\fR.
+.PP
+The \fItimeout\fR argument specifies the timeout to use, and, implicitly, whether
+to use \fBSSL_poll()\fR in blocking or nonblocking mode:
+.IP \(bu 4
+If \fItimeout\fR is NULL, the function blocks indefinitely until at least one
+resource is ready.
+.IP \(bu 4
+If \fItimeout\fR is non\-NULL, and it points to a \fBstruct timeval\fR which is set to
+zero, the function operates in nonblocking mode and returns immediately with
+readiness information.
+.IP \(bu 4
+If \fItimeout\fR is non\-NULL, and it points to a \fBstruct timeval\fR which is set to
+a value other than zero, the function blocks for the specified interval or until
+at least one of the specified resources is ready, whichever comes first.
+.PP
+The present implementation of \fBSSL_poll()\fR is a subset of the functionality which
+will eventually be available. For more information, see "LIMITATIONS".
+.PP
+The following flags are currently defined for the \fIflags\fR argument:
+.IP \fBSSL_POLL_FLAG_NO_HANDLE_EVENTS\fR 4
+.IX Item "SSL_POLL_FLAG_NO_HANDLE_EVENTS"
+This flag indicates that internal state machine processing should not be
+performed in an attempt to generate new readiness events. Only existing
+readiness events will be reported.
+.Sp
+If this flag is used in nonblocking mode (with a timeout of zero), no internal
+state machine processing is performed.
+.Sp
+If this flag is used in blocking mode (for example, with \fItimeout\fR set to
+NULL), event processing does not occur unless the function blocks.
+.PP
+The \fIresult_count\fR argument is optional. If it is non\-NULL, it is used to
+output the number of entries in the array which have nonzero \fIrevents\fR fields
+when the call to \fBSSL_poll()\fR returns; see "RETURN VALUES" for details.
+.SH "EVENT TYPES"
+.IX Header "EVENT TYPES"
+The \fBSSL_poll()\fR interface reports zero or more event types on a given resource,
+represented by a bit mask.
+.PP
+All of the event types are level triggered and represent a readiness or
+permanent exception condition; as such, after an event has been reported by
+\&\fBSSL_poll()\fR for a resource, it will continue to be reported in future \fBSSL_poll()\fR
+calls until the condition ceases to be in effect. A caller must mask the given
+event type bit in future \fBSSL_poll()\fR calls if it does not wish to receive
+repeated notifications and has not caused the underlying readiness condition
+(for example, consuming all available data using \fBSSL_read_ex\fR\|(3) after
+\&\fBSSL_POLL_EVENT_R\fR is reported) to be deasserted.
+.PP
+Some event types do not make sense on a given kind of resource. In this case,
+specifying that event type in \fIevents\fR is a no\-op and will be ignored, and the
+given event will never be reported in \fIrevents\fR.
+.PP
+Failure of the polling mechanism itself is considered distinct from an exception
+condition on a resource which was successfully polled. See \fBSSL_POLL_EVENT_F\fR
+and "RETURN VALUES" for details.
+.PP
+In general, an application should always listen for the event types
+corresponding to exception conditions if it is listening to the corresponding
+non\-exception event types (e.g. \fBSSL_POLL_EVENT_EC\fR and \fBSSL_POLL_EVENT_ER\fR
+for \fBSSL_POLL_EVENT_R\fR), as not doing so is unlikely to be a sound design.
+.PP
+Some event types are non\-maskable and may be reported in \fIrevents\fR regardless
+of whether they were requested in \fIevents\fR.
+.PP
+The following event types are supported:
+.IP \fBSSL_POLL_EVENT_F\fR 4
+.IX Item "SSL_POLL_EVENT_F"
+Polling failure. This event is raised when a resource could not be polled. It is
+distinct from an exception condition reported on a resource which was
+successfully polled and represents a failure of the polling process itself in
+relation to a resource. This may mean that \fBSSL_poll()\fR does not support the kind
+of resource specified.
+.Sp
+Where this event is raised on at least one item in \fIitems\fR, \fBSSL_poll()\fR will
+return 0 and the ERR stack will contain information pertaining to the first item
+in \fIitems\fR with \fBSSL_POLL_EVENT_F\fR set. See "RETURN VALUES" for more
+information.
+.Sp
+This event type may be raised even if it was not requested in \fIevents\fR;
+specifying this event type in \fIevents\fR does nothing.
+.IP \fBSSL_POLL_EVENT_EL\fR 4
+.IX Item "SSL_POLL_EVENT_EL"
+Error at listener level. This event is raised when a listener has failed, for
+example if a network BIO has encountered a permanent error.
+.Sp
+This event is never raised on objects which are not listeners, but its
+occurrence will cause \fBSSL_POLL_EVENT_EC\fR to be raised on all dependent
+connections.
+.IP \fBSSL_POLL_EVENT_EC\fR 4
+.IX Item "SSL_POLL_EVENT_EC"
+Error at connection level. This event is raised when a connection has failed.
+In particular, it is raised when a connection begins terminating.
+.Sp
+This event is never raised on objects which are not connections.
+.IP \fBSSL_POLL_EVENT_ECD\fR 4
+.IX Item "SSL_POLL_EVENT_ECD"
+Error at connection level (drained). This event is raised when a connection has
+finished terminating, and has reached the terminated state. This event will
+generally occur after an interval of time passes after the \fBSSL_POLL_EVENT_EC\fR
+event is raised on a connection.
+.Sp
+This event is never raised on objects which are not connections.
+.IP \fBSSL_POLL_EVENT_ER\fR 4
+.IX Item "SSL_POLL_EVENT_ER"
+Error in read direction. For QUIC, this is raised only in the event that a
+stream has a read part and that read part has been reset by the peer (for
+example, using a \fBRESET_STREAM\fR frame).
+.IP \fBSSL_POLL_EVENT_EW\fR 4
+.IX Item "SSL_POLL_EVENT_EW"
+Error in write direction. For QUIC, this is raised only in the event that a
+stream has a write part and that write part has been reset by the peer using a
+\&\fBSTOP_SENDING\fR frame.
+.IP \fBSSL_POLL_EVENT_R\fR 4
+.IX Item "SSL_POLL_EVENT_R"
+Readable. This event is raised when a QUIC stream SSL object (or a QUIC
+connection SSL object with a default stream attached) has application data
+waiting to be read using \fBSSL_read_ex\fR\|(3), or a FIN event as represented by
+\&\fBSSL_ERROR_ZERO_RETURN\fR waiting to be read.
+.Sp
+It is not raised in the event of the receiving part of the QUIC stream being
+reset by the peer; see \fBSSL_POLL_EVENT_ER\fR.
+.IP \fBSSL_POLL_EVENT_W\fR 4
+.IX Item "SSL_POLL_EVENT_W"
+Writable. This event is raised when a QUIC stream SSL object (or a QUIC
+connection SSL object with a default stream attached) could accept more
+application data using \fBSSL_write_ex\fR\|(3).
+.Sp
+This event is never raised by a receive\-only stream.
+.Sp
+This event is never raised by a stream which has had its send part concluded
+normally (as with \fBSSL_stream_conclude\fR\|(3)) or locally reset (as with
+\&\fBSSL_stream_reset\fR\|(3)).
+.Sp
+This event does not guarantee that a subsequent call to \fBSSL_write_ex\fR\|(3) will
+succeed.
+.IP \fBSSL_POLL_EVENT_IC\fR 4
+.IX Item "SSL_POLL_EVENT_IC"
+This event, which is only raised by a QUIC listener SSL object, is raised when
+one or more incoming QUIC connections are available to be accepted using
+\&\fBSSL_accept_connection\fR\|(3).
+.IP \fBSSL_POLL_EVENT_ISB\fR 4
+.IX Item "SSL_POLL_EVENT_ISB"
+This event, which is only raised by a QUIC connection SSL object, is raised when
+one or more incoming bidirectional streams are available to be accepted using
+\&\fBSSL_accept_stream\fR\|(3).
+.IP \fBSSL_POLL_EVENT_ISU\fR 4
+.IX Item "SSL_POLL_EVENT_ISU"
+This event, which is only raised by a QUIC connection SSL object, is raised when
+one or more incoming unidirectional streams are available to be accepted using
+\&\fBSSL_accept_stream\fR\|(3).
+.IP \fBSSL_POLL_EVENT_OSB\fR 4
+.IX Item "SSL_POLL_EVENT_OSB"
+This event, which is only raised by a QUIC connection SSL object, is raised when
+QUIC stream creation flow control currently permits at least one additional
+bidirectional stream to be locally created.
+.IP \fBSSL_POLL_EVENT_OSU\fR 4
+.IX Item "SSL_POLL_EVENT_OSU"
+This event, which is only raised by a QUIC connection SSL object, is raised when
+QUIC stream creation flow control currently permits at least one additional
+unidirectional stream to be locally created.
+.SH LIMITATIONS
+.IX Header "LIMITATIONS"
+\&\fBSSL_poll()\fR as presently implemented has the following limitation:
+.IP \(bu 4
+Only \fBBIO_POLL_DESCRIPTOR\fR structures with type
+\&\fBBIO_POLL_DESCRIPTOR_TYPE_SSL\fR, referencing QUIC listener, connection or
+stream SSL objects, are supported.
+.PP
+This limitation may be revised in a future release of OpenSSL.
+.SH "RETURN VALUES"
+.IX Header "RETURN VALUES"
+\&\fBSSL_poll()\fR returns 1 on success and 0 on failure.
+.PP
+Unless the \fIitems\fR pointer itself is invalid, \fBSSL_poll()\fR will always initialise
+the \fIrevents\fR fields of all items in the input array upon returning, even if it
+returns failure.
+.PP
+If \fIresult_count\fR is non\-NULL, it is always written with the number of items in
+the array with nonzero \fIrevents\fR fields, even if the \fBSSL_poll()\fR call returns
+failure.
+.PP
+It is possible for \fIresult_count\fR to be written as 0 even if the \fBSSL_poll()\fR
+call returns success, namely if no events were output but the polling process
+was successful (e.g. in nonblocking usage) or timed out.
+.PP
+It is possible for \fIresult_count\fR to be written as a nonzero value if the
+\&\fBSSL_poll()\fR call returns failure, for example due to \fBSSL_POLL_EVENT_F\fR events,
+or because some events were detected and output before encountering a failure
+condition while processing a subsequent entry in the \fIitems\fR array.
+.PP
+If at least one \fBSSL_POLL_EVENT_F\fR event is output, \fBSSL_poll()\fR is guaranteed
+to return 0 and guaranteed to place at least one ERR on the error stack
+describing the first \fBSSL_POLL_EVENT_F\fR output. Detailed information on any
+additional \fBSSL_POLL_EVENT_F\fR events is not available. \fBSSL_poll()\fR may or may
+not return more than one \fBSSL_POLL_EVENT_F\fR event at once.
+.PP
+"Normal" events representing exceptional I/O conditions which do not
+constitute a failure of the \fBSSL_poll()\fR mechanism itself are not considered
+errors by \fBSSL_poll()\fR and are instead represented using their own event type; see
+"EVENT TYPES" for details.
+.PP
+The caller can establish the meaning of the \fBSSL_poll()\fR return and output values
+as follows:
+.IP \(bu 4
+If \fBSSL_poll()\fR returns 1 and \fIresult_count\fR is zero, the operation timed out
+before any resource was ready.
+.IP \(bu 4
+If \fBSSL_poll()\fR returns 1 and \fIresult_count\fR is nonzero, that many events were
+output.
+.IP \(bu 4
+If \fBSSL_poll()\fR returns 0 and \fIresult_count\fR is zero, the caller has made a basic
+usage error; check the ERR stack for details.
+.IP \(bu 4
+If \fBSSL_poll()\fR returns 0 and \fIresult_count\fR is nonzero, inspect the \fIitems\fR
+array for \fBSSL_POLL_ITEM\fR structures with the \fBSSL_POLL_EVENT_F\fR event type
+raised in \fIrevents\fR. The entries added to the ERR stack (of which there is
+guaranteed to be at least one) reflect the cause of the failure of the first
+item in \fIitems\fR with \fBSSL_POLL_EVENT_F\fR raised. Note that there may be events
+other than \fISSL_POLL_EVENT_F\fR output for items which come before the first
+item with \fBSSL_POLL_EVENT_F\fR raised, and additional \fBSSL_POLL_EVENT_F\fR
+events may or may not have been output, both of which which will be reflected in
+\&\fIresult_count\fR.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fBBIO_get_rpoll_descriptor\fR\|(3), \fBBIO_get_wpoll_descriptor\fR\|(3),
+\&\fBSSL_get_rpoll_descriptor\fR\|(3), \fBSSL_get_wpoll_descriptor\fR\|(3)
+.SH HISTORY
+.IX Header "HISTORY"
+\&\fBSSL_poll()\fR was added in OpenSSL 3.3.
+.PP
+Before 3.5, \fBSSL_poll()\fR did not support blocking operation and
+would fail if called with a NULL \fItimeout\fR parameter or a \fItimeout\fR parameter
+pointing to a \fBstruct timeval\fR which was not zero.
+.PP
+Before 3.5, the \fBSSL_POLL_EVENT_EL\fR and \fBSSL_POLL_EVENT_IC\fR
+event types were not present.
+.SH COPYRIGHT
+.IX Header "COPYRIGHT"
+Copyright 2024\-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>.