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