[thirdparty/openssl.git] / doc / man3 / BIO_socket_wait.pod

=pod

=head1 NAME

BIO_socket_wait,
BIO_wait,
BIO_connect_retry
- BIO socket utility functions

=head1 SYNOPSIS

 #include <openssl/bio.h>

 #ifndef OPENSSL_NO_SOCK
 int BIO_socket_wait(int fd, int for_read, time_t max_time);
 #endif
 int BIO_wait(BIO *bio, time_t max_time, unsigned int milliseconds);
 int BIO_connect_retry(BIO *bio, long timeout);

=head1 DESCRIPTION

BIO_socket_wait() waits on the socket B<fd> for reading if B<for_read> is not 0,
else for writing, at most until B<max_time>.
It succeeds immediately if B<max_time> == 0 (which means no timeout given).

BIO_wait() waits at most until B<max_time> on the given B<bio>,
which is typically socket-based,
for reading if B<bio> is supposed to read, else for writing.
It succeeds immediately if B<max_time> == 0 (which means no timeout given).
If sockets are not available it succeeds after waiting at most given
B<milliseconds> in order to help avoiding a tight busy loop at the caller.

BIO_connect_retry() connects via the given B<bio>, retrying BIO_do_connect()
until success or a timeout or error condition is reached.
If the B<timeout> parameter is > 0 this indicates the maximum number of seconds
to wait until the connection is established. A value of 0 enables waiting
indefinitely, while a value < 0 immediately leads to a timeout condition.

=head1 RETURN VALUES

BIO_socket_wait(), BIO_wait(), and BIO_connect_retry()
return -1 on error, 0 on timeout, and 1 on success.

=head1 HISTORY

BIO_socket_wait(), BIO_wait(), and BIO_connect_retry()
were added in OpenSSL 3.0.

=head1 COPYRIGHT

Copyright 2019-2020 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
Commit	Line	Data
	1	=pod
	2
	3	=head1 NAME
	4
	5	BIO_socket_wait,
	6	BIO_wait,
	7	BIO_connect_retry
	8	- BIO socket utility functions
	9
	10	=head1 SYNOPSIS
	11
	12	#include <openssl/bio.h>
	13
	14	#ifndef OPENSSL_NO_SOCK
	15	int BIO_socket_wait(int fd, int for_read, time_t max_time);
	16	#endif
	17	int BIO_wait(BIO *bio, time_t max_time, unsigned int milliseconds);
	18	int BIO_connect_retry(BIO *bio, long timeout);
	19
	20	=head1 DESCRIPTION
	21
	22	BIO_socket_wait() waits on the socket B<fd> for reading if B<for_read> is not 0,
	23	else for writing, at most until B<max_time>.
	24	It succeeds immediately if B<max_time> == 0 (which means no timeout given).
	25
	26	BIO_wait() waits at most until B<max_time> on the given B<bio>,
	27	which is typically socket-based,
	28	for reading if B<bio> is supposed to read, else for writing.
	29	It succeeds immediately if B<max_time> == 0 (which means no timeout given).
	30	If sockets are not available it succeeds after waiting at most given
	31	B<milliseconds> in order to help avoiding a tight busy loop at the caller.
	32
	33	BIO_connect_retry() connects via the given B<bio>, retrying BIO_do_connect()
	34	until success or a timeout or error condition is reached.
	35	If the B<timeout> parameter is > 0 this indicates the maximum number of seconds
	36	to wait until the connection is established. A value of 0 enables waiting
	37	indefinitely, while a value < 0 immediately leads to a timeout condition.
	38
	39	=head1 RETURN VALUES
	40
	41	BIO_socket_wait(), BIO_wait(), and BIO_connect_retry()
	42	return -1 on error, 0 on timeout, and 1 on success.
	43
	44	=head1 HISTORY
	45
	46	BIO_socket_wait(), BIO_wait(), and BIO_connect_retry()
	47	were added in OpenSSL 3.0.
	48
	49	=head1 COPYRIGHT
	50
	51	Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.
	52
	53	Licensed under the Apache License 2.0 (the "License"). You may not use
	54	this file except in compliance with the License. You can obtain a copy
	55	in the file LICENSE in the source distribution or at
	56	L<https://www.openssl.org/source/license.html>.
	57
	58	=cut