doc/man3/BIO_get_rpoll_descriptor.pod

   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      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
  26 BIO_get_rpoll_descriptor() and BIO_get_wpoll_descriptor(), on success, fill
  27 I<*desc> with a poll descriptor. A poll descriptor is a tagged union structure
  28 which represents some kind of OS or non-OS resource which can be used to
  29 synchronise on I/O availability events.
  30
  31 BIO_get_rpoll_descriptor() outputs a descriptor which can be used to determine
  32 when the BIO can (potentially) next be read, and BIO_get_wpoll_descriptor()
  33 outputs a descriptor which can be used to determine when the BIO can
  34 (potentially) next be written.
  35
  36 It is permissible for BIO_get_rpoll_descriptor() and BIO_get_wpoll_descriptor()
  37 to output the same descriptor.
  38
  39 Poll descriptors can represent different kinds of information. A typical kind of
  40 resource which might be represented by a poll descriptor is an OS file
  41 descriptor which can be used with APIs such as select().
  42
  43 The kinds of poll descriptor defined by OpenSSL are:
  44
  45 =over 4
  46
  47 =item BIO_POLL_DESCRIPTOR_TYPE_NONE
  48
  49 Represents the absence of a valid poll descriptor. It may be used by
  50 BIO_get_rpoll_descriptor() or BIO_get_wpoll_descriptor() to indicate that the
  51 BIO is not pollable for readability or writeability respectively.
  52
  53 For this type, no field within the I<value> field of the B<BIO_POLL_DESCRIPTOR>
  54 is valid.
  55
  56 =item BIO_POLL_DESCRIPTOR_TYPE_SOCK_FD
  57
  58 The poll descriptor represents an OS socket resource. The field I<value.fd>
  59 in the B<BIO_POLL_DESCRIPTOR> is valid if it is not set to -1.
  60
  61 The resource is whatever kind of handle is used by a given OS to represent
  62 sockets, which may vary by OS. For example, on Windows, the value is a B<SOCKET>
  63 for use with the Winsock API. On POSIX-like platforms, it is a file descriptor.
  64
  65 Where a poll descriptor of this type is output by BIO_get_rpoll_descriptor(), it
  66 should be polled for readability to determine when the BIO might next be able to
  67 successfully complete a BIO_read() operation; likewise, where a poll descriptor
  68 of this type is output by BIO_get_wpoll_descriptor(), it should be polled for
  69 writeability to determine when the BIO might next be able to successfully
  70 complete a BIO_write() operation.
  71
  72 =item BIO_POLL_DESCRIPTOR_CUSTOM_START
  73
  74 Type values beginning with this value (inclusive) are reserved for application
  75 allocation for custom poll descriptor types. Any of the definitions in the union
  76 field I<value> can be used by the application arbitrarily as opaque values.
  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
  89 These functions are permitted to succeed and initialise I<*desc> with a poll
  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_handle_events(3)>, L<SSL_get_event_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
 105 Copyright 2022 The OpenSSL Project Authors. All Rights Reserved.
 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