.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    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 turned on, 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
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BIO_GET_RPOLL_DESCRIPTOR 3ossl"
.TH BIO_GET_RPOLL_DESCRIPTOR 3ossl "2024-06-04" "3.3.1" "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_get_rpoll_descriptor, BIO_get_wpoll_descriptor \- obtain a structure which
can be used to determine when a BIO object can next be read or written
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/bio.h>
\&
\& typedef struct bio_poll_descriptor_st {
\&     uint32_t type;
\&     union {
\&         int        fd;
\&         void       *custom;
\&         uintptr_t  custom_ui;
\&     } value;
\& } BIO_POLL_DESCRIPTOR;
\&
\& int BIO_get_rpoll_descriptor(BIO *b, BIO_POLL_DESCRIPTOR *desc);
\& int BIO_get_wpoll_descriptor(BIO *b, BIO_POLL_DESCRIPTOR *desc);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fIBIO_get_rpoll_descriptor()\fR and \fIBIO_get_wpoll_descriptor()\fR, on success, fill
\&\fI*desc\fR with a poll descriptor. A poll descriptor is a tagged union structure
which represents some kind of \s-1OS\s0 or non-OS resource which can be used to
synchronise on I/O availability events.
.PP
\&\fIBIO_get_rpoll_descriptor()\fR outputs a descriptor which can be used to determine
when the \s-1BIO\s0 can (potentially) next be read, and \fIBIO_get_wpoll_descriptor()\fR
outputs a descriptor which can be used to determine when the \s-1BIO\s0 can
(potentially) next be written.
.PP
It is permissible for \fIBIO_get_rpoll_descriptor()\fR and \fIBIO_get_wpoll_descriptor()\fR
to output the same descriptor.
.PP
Poll descriptors can represent different kinds of information. A typical kind of
resource which might be represented by a poll descriptor is an \s-1OS\s0 file
descriptor which can be used with APIs such as \fIselect()\fR.
.PP
The kinds of poll descriptor defined by OpenSSL are:
.IP "\s-1BIO_POLL_DESCRIPTOR_TYPE_NONE\s0" 4
.IX Item "BIO_POLL_DESCRIPTOR_TYPE_NONE"
Represents the absence of a valid poll descriptor. It may be used by
\&\fIBIO_get_rpoll_descriptor()\fR or \fIBIO_get_wpoll_descriptor()\fR to indicate that the
\&\s-1BIO\s0 is not pollable for readability or writeability respectively.
.Sp
For this type, no field within the \fIvalue\fR field of the \fB\s-1BIO_POLL_DESCRIPTOR\s0\fR
is valid.
.IP "\s-1BIO_POLL_DESCRIPTOR_TYPE_SOCK_FD\s0" 4
.IX Item "BIO_POLL_DESCRIPTOR_TYPE_SOCK_FD"
The poll descriptor represents an \s-1OS\s0 socket resource. The field \fIvalue.fd\fR
in the \fB\s-1BIO_POLL_DESCRIPTOR\s0\fR is valid if it is not set to \-1.
.Sp
The resource is whatever kind of handle is used by a given \s-1OS\s0 to represent
sockets, which may vary by \s-1OS.\s0 For example, on Windows, the value is a \fB\s-1SOCKET\s0\fR
for use with the Winsock \s-1API.\s0 On POSIX-like platforms, it is a file descriptor.
.Sp
Where a poll descriptor of this type is output by \fIBIO_get_rpoll_descriptor()\fR, it
should be polled for readability to determine when the \s-1BIO\s0 might next be able to
successfully complete a \fIBIO_read()\fR operation; likewise, where a poll descriptor
of this type is output by \fIBIO_get_wpoll_descriptor()\fR, it should be polled for
writeability to determine when the \s-1BIO\s0 might next be able to successfully
complete a \fIBIO_write()\fR operation.
.IP "\s-1BIO_POLL_DESCRIPTOR_CUSTOM_START\s0" 4
.IX Item "BIO_POLL_DESCRIPTOR_CUSTOM_START"
Type values beginning with this value (inclusive) are reserved for application
allocation for custom poll descriptor types. Any of the definitions in the union
field \fIvalue\fR can be used by the application arbitrarily as opaque values.
.PP
Because poll descriptors are a tagged union structure, they can represent
different kinds of information. New types of poll descriptor may be defined,
including by applications, according to their needs.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
The functions \fIBIO_get_rpoll_descriptor()\fR and \fIBIO_get_wpoll_descriptor()\fR return 1
on success and 0 on failure.
.PP
These functions are permitted to succeed and initialise \fI*desc\fR with a poll
descriptor of type \fB\s-1BIO_POLL_DESCRIPTOR_TYPE_NONE\s0\fR to indicate that the \s-1BIO\s0 is
not pollable for readability or writeability respectively.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fISSL_handle_events\fR\|(3), \fISSL_get_event_timeout\fR\|(3), \fISSL_get_rpoll_descriptor\fR\|(3),
\&\fISSL_get_wpoll_descriptor\fR\|(3), \fIbio\fR\|(7)
.SH "HISTORY"
.IX Header "HISTORY"
The \fISSL_get_rpoll_descriptor()\fR and \fISSL_get_wpoll_descriptor()\fR functions were
added in OpenSSL 3.2.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2022\-2023 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (the \*(L"License\*(R").  You may not use
this file except in compliance with the License.  You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.