Debian Codegraph @

upstream/debian-unstable/man3/BIO_get_rpoll_descriptor.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "BIO_GET_RPOLL_DESCRIPTOR 3SSL"
58 .TH BIO_GET_RPOLL_DESCRIPTOR 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 BIO_get_rpoll_descriptor, BIO_get_wpoll_descriptor \- obtain a structure which
65 can be used to determine when a BIO object can next be read or written
66 .SH SYNOPSIS
67 .IX Header "SYNOPSIS"
68 .Vb 1
69 \& #include <openssl/bio.h>
70 \&
71 \& typedef struct bio_poll_descriptor_st {
72 \& uint32_t type;
73 \& union {
74 \& int fd;
75 \& void *custom;
76 \& uintptr_t custom_ui;
77 \& } value;
78 \& } BIO_POLL_DESCRIPTOR;
79 \&
80 \& int BIO_get_rpoll_descriptor(BIO *b, BIO_POLL_DESCRIPTOR *desc);
81 \& int BIO_get_wpoll_descriptor(BIO *b, BIO_POLL_DESCRIPTOR *desc);
82 .Ve
83 .SH DESCRIPTION
84 .IX Header "DESCRIPTION"
85 \&\fBBIO_get_rpoll_descriptor()\fR and \fBBIO_get_wpoll_descriptor()\fR, on success, fill
86 \&\fI*desc\fR with a poll descriptor. A poll descriptor is a tagged union structure
87 which represents some kind of OS or non-OS resource which can be used to
88 synchronise on I/O availability events.
89 .PP
90 \&\fBBIO_get_rpoll_descriptor()\fR outputs a descriptor which can be used to determine
91 when the BIO can (potentially) next be read, and \fBBIO_get_wpoll_descriptor()\fR
92 outputs a descriptor which can be used to determine when the BIO can
93 (potentially) next be written.
94 .PP
95 It is permissible for \fBBIO_get_rpoll_descriptor()\fR and \fBBIO_get_wpoll_descriptor()\fR
96 to output the same descriptor.
97 .PP
98 Poll descriptors can represent different kinds of information. A typical kind of
99 resource which might be represented by a poll descriptor is an OS file
100 descriptor which can be used with APIs such as \fBselect()\fR.
101 .PP
102 The kinds of poll descriptor defined by OpenSSL are:
103 .IP BIO_POLL_DESCRIPTOR_TYPE_NONE 4
104 .IX Item "BIO_POLL_DESCRIPTOR_TYPE_NONE"
105 Represents the absence of a valid poll descriptor. It may be used by
106 \&\fBBIO_get_rpoll_descriptor()\fR or \fBBIO_get_wpoll_descriptor()\fR to indicate that the
107 BIO is not pollable for readability or writeability respectively.
108 .Sp
109 For this type, no field within the \fIvalue\fR field of the \fBBIO_POLL_DESCRIPTOR\fR
110 is valid.
111 .IP BIO_POLL_DESCRIPTOR_TYPE_SOCK_FD 4
112 .IX Item "BIO_POLL_DESCRIPTOR_TYPE_SOCK_FD"
113 The poll descriptor represents an OS socket resource. The field \fIvalue.fd\fR
114 in the \fBBIO_POLL_DESCRIPTOR\fR is valid if it is not set to \-1.
115 .Sp
116 The resource is whatever kind of handle is used by a given OS to represent
117 sockets, which may vary by OS. For example, on Windows, the value is a \fBSOCKET\fR
118 for use with the Winsock API. On POSIX-like platforms, it is a file descriptor.
119 .Sp
120 Where a poll descriptor of this type is output by \fBBIO_get_rpoll_descriptor()\fR, it
121 should be polled for readability to determine when the BIO might next be able to
122 successfully complete a \fBBIO_read()\fR operation; likewise, where a poll descriptor
123 of this type is output by \fBBIO_get_wpoll_descriptor()\fR, it should be polled for
124 writeability to determine when the BIO might next be able to successfully
125 complete a \fBBIO_write()\fR operation.
126 .IP BIO_POLL_DESCRIPTOR_CUSTOM_START 4
127 .IX Item "BIO_POLL_DESCRIPTOR_CUSTOM_START"
128 Type values beginning with this value (inclusive) are reserved for application
129 allocation for custom poll descriptor types. Any of the definitions in the union
130 field \fIvalue\fR can be used by the application arbitrarily as opaque values.
131 .PP
132 Because poll descriptors are a tagged union structure, they can represent
133 different kinds of information. New types of poll descriptor may be defined,
134 including by applications, according to their needs.
135 .SH "RETURN VALUES"
136 .IX Header "RETURN VALUES"
137 The functions \fBBIO_get_rpoll_descriptor()\fR and \fBBIO_get_wpoll_descriptor()\fR return 1
138 on success and 0 on failure.
139 .PP
140 These functions are permitted to succeed and initialise \fI*desc\fR with a poll
141 descriptor of type \fBBIO_POLL_DESCRIPTOR_TYPE_NONE\fR to indicate that the BIO is
142 not pollable for readability or writeability respectively.
143 .SH "SEE ALSO"
144 .IX Header "SEE ALSO"
145 \&\fBSSL_handle_events\fR\|(3), \fBSSL_get_event_timeout\fR\|(3), \fBSSL_get_rpoll_descriptor\fR\|(3),
146 \&\fBSSL_get_wpoll_descriptor\fR\|(3), \fBbio\fR\|(7)
147 .SH HISTORY
148 .IX Header "HISTORY"
149 The \fBBIO_get_rpoll_descriptor()\fR and \fBBIO_get_wpoll_descriptor()\fR functions were
150 added in OpenSSL 3.2.
151 .SH COPYRIGHT
152 .IX Header "COPYRIGHT"
153 Copyright 2022\-2024 The OpenSSL Project Authors. All Rights Reserved.
154 .PP
155 Licensed under the Apache License 2.0 (the "License"). You may not use
156 this file except in compliance with the License. You can obtain a copy
157 in the file LICENSE in the source distribution or at
158 <https://www.openssl.org/source/license.html>.