1e71b7053SJung-uk Kim=pod 2e71b7053SJung-uk Kim 3e71b7053SJung-uk Kim=head1 NAME 4e71b7053SJung-uk Kim 5e71b7053SJung-uk KimSSL_waiting_for_async, 6e71b7053SJung-uk KimSSL_get_all_async_fds, 7e71b7053SJung-uk KimSSL_get_changed_async_fds 8e71b7053SJung-uk Kim- manage asynchronous operations 9e71b7053SJung-uk Kim 10e71b7053SJung-uk Kim=head1 SYNOPSIS 11e71b7053SJung-uk Kim 12*b077aed3SPierre Pronchery=for openssl multiple includes 13e71b7053SJung-uk Kim 14e71b7053SJung-uk Kim #include <openssl/async.h> 15e71b7053SJung-uk Kim #include <openssl/ssl.h> 16e71b7053SJung-uk Kim 17e71b7053SJung-uk Kim int SSL_waiting_for_async(SSL *s); 18e71b7053SJung-uk Kim int SSL_get_all_async_fds(SSL *s, OSSL_ASYNC_FD *fd, size_t *numfds); 19e71b7053SJung-uk Kim int SSL_get_changed_async_fds(SSL *s, OSSL_ASYNC_FD *addfd, size_t *numaddfds, 20e71b7053SJung-uk Kim OSSL_ASYNC_FD *delfd, size_t *numdelfds); 21e71b7053SJung-uk Kim 22e71b7053SJung-uk Kim=head1 DESCRIPTION 23e71b7053SJung-uk Kim 24e71b7053SJung-uk KimSSL_waiting_for_async() determines whether an SSL connection is currently 25*b077aed3SPierre Proncherywaiting for asynchronous operations to complete (see the B<SSL_MODE_ASYNC> mode 26*b077aed3SPierre Proncheryin L<SSL_CTX_set_mode(3)>). 27e71b7053SJung-uk Kim 28e71b7053SJung-uk KimSSL_get_all_async_fds() returns a list of file descriptor which can be used in a 29e71b7053SJung-uk Kimcall to select() or poll() to determine whether the current asynchronous 30e71b7053SJung-uk Kimoperation has completed or not. A completed operation will result in data 31e71b7053SJung-uk Kimappearing as "read ready" on the file descriptor (no actual data should be read 32*b077aed3SPierre Proncheryfrom the file descriptor). This function should only be called if the B<SSL> 33*b077aed3SPierre Proncheryobject is currently waiting for asynchronous work to complete (i.e. 34*b077aed3SPierre ProncheryB<SSL_ERROR_WANT_ASYNC> has been received - see L<SSL_get_error(3)>). Typically 35*b077aed3SPierre Proncherythe list will only contain one file descriptor. However, if multiple asynchronous 36e71b7053SJung-uk Kimcapable engines are in use then more than one is possible. The number of file 37*b077aed3SPierre Proncherydescriptors returned is stored in I<*numfds> and the file descriptors themselves 38*b077aed3SPierre Proncheryare in I<*fds>. The I<fds> parameter may be NULL in which case no file 39*b077aed3SPierre Proncherydescriptors are returned but I<*numfds> is still populated. It is the callers 40*b077aed3SPierre Proncheryresponsibility to ensure sufficient memory is allocated at I<*fds> so typically 41*b077aed3SPierre Proncherythis function is called twice (once with a NULL I<fds> parameter and once 42e71b7053SJung-uk Kimwithout). 43e71b7053SJung-uk Kim 44e71b7053SJung-uk KimSSL_get_changed_async_fds() returns a list of the asynchronous file descriptors 45e71b7053SJung-uk Kimthat have been added and a list that have been deleted since the last 46*b077aed3SPierre ProncheryB<SSL_ERROR_WANT_ASYNC> was received (or since the B<SSL> object was created if 47*b077aed3SPierre Proncheryno B<SSL_ERROR_WANT_ASYNC> has been received). Similar to SSL_get_all_async_fds() 48*b077aed3SPierre Proncheryit is the callers responsibility to ensure that I<*addfd> and I<*delfd> have 49e71b7053SJung-uk Kimsufficient memory allocated, although they may be NULL. The number of added fds 50*b077aed3SPierre Proncheryand the number of deleted fds are stored in I<*numaddfds> and I<*numdelfds> 51e71b7053SJung-uk Kimrespectively. 52e71b7053SJung-uk Kim 53e71b7053SJung-uk Kim=head1 RETURN VALUES 54e71b7053SJung-uk Kim 55e71b7053SJung-uk KimSSL_waiting_for_async() will return 1 if the current SSL operation is waiting 56e71b7053SJung-uk Kimfor an async operation to complete and 0 otherwise. 57e71b7053SJung-uk Kim 58e71b7053SJung-uk KimSSL_get_all_async_fds() and SSL_get_changed_async_fds() return 1 on success or 59e71b7053SJung-uk Kim0 on error. 60e71b7053SJung-uk Kim 61e71b7053SJung-uk Kim=head1 NOTES 62e71b7053SJung-uk Kim 63*b077aed3SPierre ProncheryOn Windows platforms the F<< <openssl/async.h> >> header is dependent on some 64*b077aed3SPierre Proncheryof the types customarily made available by including F<< <windows.h> >>. The 65e71b7053SJung-uk Kimapplication developer is likely to require control over when the latter 6658f35182SJung-uk Kimis included, commonly as one of the first included headers. Therefore, 67e71b7053SJung-uk Kimit is defined as an application developer's responsibility to include 68*b077aed3SPierre ProncheryF<< <windows.h> >> prior to F<< <openssl/async.h> >>. 69e71b7053SJung-uk Kim 70e71b7053SJung-uk Kim=head1 SEE ALSO 71e71b7053SJung-uk Kim 72*b077aed3SPierre ProncheryL<ssl(7)>, 73e71b7053SJung-uk KimL<SSL_get_error(3)>, L<SSL_CTX_set_mode(3)> 74e71b7053SJung-uk Kim 75e71b7053SJung-uk Kim=head1 HISTORY 76e71b7053SJung-uk Kim 776935a639SJung-uk KimThe SSL_waiting_for_async(), SSL_get_all_async_fds() 786935a639SJung-uk Kimand SSL_get_changed_async_fds() functions were added in OpenSSL 1.1.0. 79e71b7053SJung-uk Kim 80e71b7053SJung-uk Kim=head1 COPYRIGHT 81e71b7053SJung-uk Kim 82*b077aed3SPierre ProncheryCopyright 2016-2021 The OpenSSL Project Authors. All Rights Reserved. 83e71b7053SJung-uk Kim 84*b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 85e71b7053SJung-uk Kimthis file except in compliance with the License. You can obtain a copy 86e71b7053SJung-uk Kimin the file LICENSE in the source distribution or at 87e71b7053SJung-uk KimL<https://www.openssl.org/source/license.html>. 88e71b7053SJung-uk Kim 89e71b7053SJung-uk Kim=cut 90