xref: /freebsd-src/crypto/openssl/doc/man3/SSL_get_all_async_fds.pod (revision b077aed33b7b6aefca7b17ddb250cf521f938613)
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