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