1*b077aed3SPierre Pronchery=pod 2*b077aed3SPierre Pronchery 3*b077aed3SPierre Pronchery=head1 NAME 4*b077aed3SPierre Pronchery 5*b077aed3SPierre ProncheryBIO_socket_wait, 6*b077aed3SPierre ProncheryBIO_wait, 7*b077aed3SPierre ProncheryBIO_do_connect_retry 8*b077aed3SPierre Pronchery- BIO connection utility functions 9*b077aed3SPierre Pronchery 10*b077aed3SPierre Pronchery=head1 SYNOPSIS 11*b077aed3SPierre Pronchery 12*b077aed3SPierre Pronchery #include <openssl/bio.h> 13*b077aed3SPierre Pronchery 14*b077aed3SPierre Pronchery #ifndef OPENSSL_NO_SOCK 15*b077aed3SPierre Pronchery int BIO_socket_wait(int fd, int for_read, time_t max_time); 16*b077aed3SPierre Pronchery #endif 17*b077aed3SPierre Pronchery int BIO_wait(BIO *bio, time_t max_time, unsigned int nap_milliseconds); 18*b077aed3SPierre Pronchery int BIO_do_connect_retry(BIO *bio, int timeout, int nap_milliseconds); 19*b077aed3SPierre Pronchery 20*b077aed3SPierre Pronchery=head1 DESCRIPTION 21*b077aed3SPierre Pronchery 22*b077aed3SPierre ProncheryBIO_socket_wait() waits on the socket B<fd> for reading if B<for_read> is not 0, 23*b077aed3SPierre Proncheryelse for writing, at most until B<max_time>. 24*b077aed3SPierre ProncheryIt succeeds immediately if B<max_time> == 0 (which means no timeout given). 25*b077aed3SPierre Pronchery 26*b077aed3SPierre ProncheryBIO_wait() waits at most until B<max_time> on the given (typically socket-based) 27*b077aed3SPierre ProncheryB<bio>, for reading if B<bio> is supposed to read, else for writing. 28*b077aed3SPierre ProncheryIt is used by BIO_do_connect_retry() and can be used together L<BIO_read(3)>. 29*b077aed3SPierre ProncheryIt succeeds immediately if B<max_time> == 0 (which means no timeout given). 30*b077aed3SPierre ProncheryIf sockets are not available it supports polling by succeeding after sleeping 31*b077aed3SPierre Proncheryat most the given B<nap_milliseconds> in order to avoid a tight busy loop. 32*b077aed3SPierre ProncheryVia B<nap_milliseconds> the caller determines the polling granularity. 33*b077aed3SPierre Pronchery 34*b077aed3SPierre ProncheryBIO_do_connect_retry() connects via the given B<bio>. 35*b077aed3SPierre ProncheryIt retries BIO_do_connect() as far as needed to reach a definite outcome, 36*b077aed3SPierre Proncheryi.e., connection succeeded, timeout has been reached, or an error occurred. 37*b077aed3SPierre ProncheryFor nonblocking and potentially even non-socket BIOs it polls 38*b077aed3SPierre Proncheryevery B<nap_milliseconds> and sleeps in between using BIO_wait(). 39*b077aed3SPierre ProncheryIf B<nap_milliseconds> is < 0 then a default value of 100 ms is used. 40*b077aed3SPierre ProncheryIf the B<timeout> parameter is > 0 this indicates the maximum number of seconds 41*b077aed3SPierre Proncheryto wait until the connection is established or a definite error occurred. 42*b077aed3SPierre ProncheryA value of 0 enables waiting indefinitely (i.e, no timeout), 43*b077aed3SPierre Proncherywhile a value < 0 means that BIO_do_connect() is tried only once. 44*b077aed3SPierre ProncheryThe function may, directly or indirectly, invoke ERR_clear_error(). 45*b077aed3SPierre Pronchery 46*b077aed3SPierre Pronchery=head1 RETURN VALUES 47*b077aed3SPierre Pronchery 48*b077aed3SPierre ProncheryBIO_socket_wait(), BIO_wait(), and BIO_do_connect_retry() 49*b077aed3SPierre Proncheryreturn -1 on error, 0 on timeout, and 1 on success. 50*b077aed3SPierre Pronchery 51*b077aed3SPierre Pronchery=head1 SEE ALSO 52*b077aed3SPierre Pronchery 53*b077aed3SPierre ProncheryL<BIO_do_connect(3)>, L<BIO_read(3)> 54*b077aed3SPierre Pronchery 55*b077aed3SPierre Pronchery=head1 HISTORY 56*b077aed3SPierre Pronchery 57*b077aed3SPierre ProncheryBIO_socket_wait(), BIO_wait(), and BIO_do_connect_retry() 58*b077aed3SPierre Proncherywere added in OpenSSL 3.0. 59*b077aed3SPierre Pronchery 60*b077aed3SPierre Pronchery=head1 COPYRIGHT 61*b077aed3SPierre Pronchery 62*b077aed3SPierre ProncheryCopyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved. 63*b077aed3SPierre Pronchery 64*b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 65*b077aed3SPierre Proncherythis file except in compliance with the License. You can obtain a copy 66*b077aed3SPierre Proncheryin the file LICENSE in the source distribution or at 67*b077aed3SPierre ProncheryL<https://www.openssl.org/source/license.html>. 68*b077aed3SPierre Pronchery 69*b077aed3SPierre Pronchery=cut 70