1=pod
2
3=head1 NAME
4
5BIO_get_rpoll_descriptor, BIO_get_wpoll_descriptor - obtain a structure which
6can be used to determine when a BIO object can next be read or written
7
8=head1 SYNOPSIS
9
10 #include <openssl/bio.h>
11
12 typedef struct bio_poll_descriptor_st {
13     uint32_t type;
14     union {
15         int        fd;
16         void       *custom;
17         uintptr_t  custom_ui;
18     } value;
19 } BIO_POLL_DESCRIPTOR;
20
21 int BIO_get_rpoll_descriptor(BIO *b, BIO_POLL_DESCRIPTOR *desc);
22 int BIO_get_wpoll_descriptor(BIO *b, BIO_POLL_DESCRIPTOR *desc);
23
24=head1 DESCRIPTION
25
26BIO_get_rpoll_descriptor() and BIO_get_wpoll_descriptor(), on success, fill
27I<*desc> with a poll descriptor. A poll descriptor is a tagged union structure
28which represents some kind of OS or non-OS resource which can be used to
29synchronise on I/O availability events.
30
31BIO_get_rpoll_descriptor() outputs a descriptor which can be used to determine
32when the BIO can (potentially) next be read, and BIO_get_wpoll_descriptor()
33outputs a descriptor which can be used to determine when the BIO can
34(potentially) next be written.
35
36It is permissible for BIO_get_rpoll_descriptor() and BIO_get_wpoll_descriptor()
37to output the same descriptor.
38
39Poll descriptors can represent different kinds of information. A typical kind of
40resource which might be represented by a poll descriptor is an OS file
41descriptor which can be used with APIs such as select().
42
43The kinds of poll descriptor defined by OpenSSL are:
44
45=over 4
46
47=item BIO_POLL_DESCRIPTOR_TYPE_NONE
48
49Represents the absence of a valid poll descriptor. It may be used by
50BIO_get_rpoll_descriptor() or BIO_get_wpoll_descriptor() to indicate that the
51BIO is not pollable for readability or writeability respectively.
52
53For this type, no field within the I<value> field of the B<BIO_POLL_DESCRIPTOR>
54is valid.
55
56=item BIO_POLL_DESCRIPTOR_TYPE_SOCK_FD
57
58The poll descriptor represents an OS socket resource. The field I<value.fd>
59in the B<BIO_POLL_DESCRIPTOR> is valid if it is not set to -1.
60
61The resource is whatever kind of handle is used by a given OS to represent
62sockets, which may vary by OS. For example, on Windows, the value is a B<SOCKET>
63for use with the Winsock API. On POSIX-like platforms, it is a file descriptor.
64
65Where a poll descriptor of this type is output by BIO_get_rpoll_descriptor(), it
66should be polled for readability to determine when the BIO might next be able to
67successfully complete a BIO_read() operation; likewise, where a poll descriptor
68of this type is output by BIO_get_wpoll_descriptor(), it should be polled for
69writeability to determine when the BIO might next be able to successfully
70complete a BIO_write() operation.
71
72=item BIO_POLL_DESCRIPTOR_CUSTOM_START
73
74Type values beginning with this value (inclusive) are reserved for application
75allocation for custom poll descriptor types. Any of the definitions in the union
76field I<value> can be used by the application arbitrarily as opaque values.
77
78=back
79
80Because poll descriptors are a tagged union structure, they can represent
81different kinds of information. New types of poll descriptor may be defined,
82including by applications, according to their needs.
83
84=head1 RETURN VALUES
85
86The functions BIO_get_rpoll_descriptor() and BIO_get_wpoll_descriptor() return 1
87on success and 0 on failure.
88
89These functions are permitted to succeed and initialise I<*desc> with a poll
90descriptor of type B<BIO_POLL_DESCRIPTOR_TYPE_NONE> to indicate that the BIO is
91not pollable for readability or writeability respectively.
92
93=head1 SEE ALSO
94
95L<SSL_handle_events(3)>, L<SSL_get_event_timeout(3)>, L<SSL_get_rpoll_descriptor(3)>,
96L<SSL_get_wpoll_descriptor(3)>, L<bio(7)>
97
98=head1 HISTORY
99
100The SSL_get_rpoll_descriptor() and SSL_get_wpoll_descriptor() functions were
101added in OpenSSL 3.2.
102
103=head1 COPYRIGHT
104
105Copyright 2022-2023 The OpenSSL Project Authors. All Rights Reserved.
106
107Licensed under the Apache License 2.0 (the "License").  You may not use
108this file except in compliance with the License.  You can obtain a copy
109in the file LICENSE in the source distribution or at
110L<https://www.openssl.org/source/license.html>.
111
112=cut
113