mirror of
https://github.com/openssl/openssl.git
synced 2024-12-27 06:21:43 +08:00
117 lines
4.2 KiB
Plaintext
117 lines
4.2 KiB
Plaintext
|
=pod
|
||
|
|
|
||
|
|
=head1 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
|
||
|
|
|
||
|
|
=head1 SYNOPSIS
|
||
|
|
|
||
|
|
#include <openssl/bio.h>
|
||
|
|
|
||
|
|
typedef struct bio_poll_descriptor_st {
|
||
|
|
int type;
|
||
|
|
union {
|
||
|
|
int fd;
|
||
|
|
union {
|
||
|
|
void *ptr;
|
||
|
|
uint64_t u64;
|
||
|
|
} custom[BIO_POLL_DESCRIPTOR_NUM_CUSTOM];
|
||
|
|
} value;
|
||
|
|
} BIO_POLL_DESCRIPTOR;
|
||
|
|
|
||
|
|
__owur int BIO_get_rpoll_descriptor(BIO *b, BIO_POLL_DESCRIPTOR *desc);
|
||
|
|
__owur int BIO_get_wpoll_descriptor(BIO *b, BIO_POLL_DESCRIPTOR *desc);
|
||
|
|
|
||
|
|
=head1 DESCRIPTION
|
||
|
|
|
||
|
|
BIO_get_rpoll_descriptor() and BIO_get_wpoll_descriptor(), on success, fill
|
||
|
|
B<*desc> with a poll descriptor. A poll descriptor is a tagged union structure
|
||
|
|
which represents some kind of OS or non-OS resource which can be used to
|
||
|
|
synchronise on I/O availability events.
|
||
|
|
|
||
|
|
BIO_get_rpoll_descriptor() outputs a descriptor which can be used to determine
|
||
|
|
when the BIO can (potentially) next be read, and BIO_get_wpoll_descriptor()
|
||
|
|
outputs a descriptor which can be used to determine when the BIO can
|
||
|
|
(potentially) next be written.
|
||
|
|
|
||
|
|
It is permissible for BIO_get_rpoll_descriptor() and BIO_get_wpoll_descriptor()
|
||
|
|
to output the same descriptor.
|
||
|
|
|
||
|
|
Poll descriptors can represent different kinds of information. A typical kind of
|
||
|
|
resource which might be represented by a poll descriptor is an OS file
|
||
|
|
descriptor which can be used with APIs such as select().
|
||
|
|
|
||
|
|
The kinds of poll descriptor defined by OpenSSL are:
|
||
|
|
|
||
|
|
=over 4
|
||
|
|
|
||
|
|
=item BIO_POLL_DESCRIPTOR_TYPE_NONE
|
||
|
|
|
||
|
|
Represents the absence of a valid poll descriptor. It may be used by
|
||
|
|
BIO_get_rpoll_descriptor() or BIO_get_wpoll_descriptor() to indicate that the
|
||
|
|
BIO is not pollable for readability or writeability respectively.
|
||
|
|
|
||
|
|
For this type, no field within the B<value> field of the B<BIO_POLL_DESCRIPTOR>
|
||
|
|
is valid.
|
||
|
|
|
||
|
|
=item BIO_POLL_DESCRIPTOR_TYPE_SOCK_FD
|
||
|
|
|
||
|
|
The poll descriptor represents an OS socket resource. The field B<value.fd>
|
||
|
|
in the B<BIO_POLL_DESCRIPTOR> is valid if it is not set to -1.
|
||
|
|
|
||
|
|
The resource is whatever kind of handle is used by a given OS to represent
|
||
|
|
sockets, which may vary by OS. For example, on Windows, the value is a B<SOCKET>
|
||
|
|
for use with the Winsock API. On POSIX-like platforms, it is a file descriptor.
|
||
|
|
|
||
|
|
Where a poll descriptor of this type is output by BIO_get_rpoll_descriptor(), it
|
||
|
|
should be polled for readability to determine when the BIO might next be able to
|
||
|
|
successfully complete a BIO_read() operation; likewise, where a poll descriptor
|
||
|
|
of this type is output by BIO_get_wpoll_descriptor(), it should be polled for
|
||
|
|
writeability to determine when the BIO might next be able to successfully
|
||
|
|
complete a BIO_write() operation.
|
||
|
|
|
||
|
|
=item BIO_POLL_DESCRIPTOR_CUSTOM_START
|
||
|
|
|
||
|
|
Type values beginning with this value (inclusive) are reserved for application
|
||
|
|
allocation for custom poll descriptor types. The field B<value.custom> in the
|
||
|
|
B<BIO_POLL_DESCRIPTOR> is an array of length B<BIO_POLL_DESCRIPTOR_NUM_CUSTOM>.
|
||
|
|
Each entry in this array can store a void pointer or a B<uint64_t> and can be
|
||
|
|
used by the application arbitrarily.
|
||
|
|
|
||
|
|
=back
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
=head1 RETURN VALUES
|
||
|
|
|
||
|
|
The functions BIO_get_rpoll_descriptor() and BIO_get_wpoll_descriptor() return 1
|
||
|
|
on success and 0 on failure.
|
||
|
|
|
||
|
|
These functions are permitted to succeed and initialise B<*desc> with a poll
|
||
|
|
descriptor of type B<BIO_POLL_DESCRIPTOR_TYPE_NONE> to indicate that the BIO is
|
||
|
|
not pollable for readability or writeability respectively.
|
||
|
|
|
||
|
|
=head1 SEE ALSO
|
||
|
|
|
||
|
|
L<SSL_tick(3)>, L<SSL_get_tick_timeout(3)>, L<SSL_get_rpoll_descriptor(3)>,
|
||
|
|
L<SSL_get_wpoll_descriptor(3)>, L<bio(7)>
|
||
|
|
|
||
|
|
=head1 HISTORY
|
||
|
|
|
||
|
|
The SSL_get_rpoll_descriptor() and SSL_get_wpoll_descriptor() functions were
|
||
|
|
added in OpenSSL 3.2.
|
||
|
|
|
||
|
|
=head1 COPYRIGHT
|
||
|
|
|
||
|
|
Copyright 2000-2022 The OpenSSL Project Authors. All Rights Reserved.
|
||
|
|
|
||
|
|
Licensed under the Apache License 2.0 (the "License"). You may not use
|
||
|
|
this file except in compliance with the License. You can obtain a copy
|
||
|
|
in the file LICENSE in the source distribution or at
|
||
|
|
L<https://www.openssl.org/source/license.html>.
|
||
|
|
|
||
|
|
=cut
|