doc/man3/BIO_socket_wait.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 BIO_socket_wait,
   6 BIO_wait,
   7 BIO_do_connect_retry
   8 - BIO connection 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 nap_milliseconds);
  18  int BIO_do_connect_retry(BIO *bio, int timeout, int nap_milliseconds);
  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 (typically socket-based)
  27 B<bio>, for reading if B<bio> is supposed to read, else for writing.
  28 It is used by BIO_do_connect_retry() and can be used together L<BIO_read(3)>.
  29 It succeeds immediately if B<max_time> == 0 (which means no timeout given).
  30 If sockets are not available it supports polling by succeeding after sleeping
  31 at most the given B<nap_milliseconds> in order to avoid a tight busy loop.
  32 Via B<nap_milliseconds> the caller determines the polling granularity.
  33
  34 BIO_do_connect_retry() connects via the given B<bio>.
  35 It retries BIO_do_connect() as far as needed to reach a definite outcome,
  36 i.e., connection succeeded, timeout has been reached, or an error occurred.
  37 For nonblocking and potentially even non-socket BIOs it polls
  38 every B<nap_milliseconds> and sleeps in between using BIO_wait().
  39 If B<nap_milliseconds> is < 0 then a default value of 100 ms is used.
  40 If the B<timeout> parameter is > 0 this indicates the maximum number of seconds
  41 to wait until the connection is established or a definite error occurred.
  42 A value of 0 enables waiting indefinitely (i.e, no timeout),
  43 while a value < 0 means that BIO_do_connect() is tried only once.
  44 The function may, directly or indirectly, invoke ERR_clear_error().
  45
  46 =head1 RETURN VALUES
  47
  48 BIO_socket_wait(), BIO_wait(), and BIO_do_connect_retry()
  49 return -1 on error, 0 on timeout, and 1 on success.
  50
  51 =head1 SEE ALSO
  52
  53 L<BIO_do_connect(3)>, L<BIO_read(3)>
  54
  55 =head1 HISTORY
  56
  57 BIO_socket_wait(), BIO_wait(), and BIO_do_connect_retry()
  58 were added in OpenSSL 3.0.
  59
  60 =head1 COPYRIGHT
  61
  62 Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.
  63
  64 Licensed under the Apache License 2.0 (the "License").  You may not use
  65 this file except in compliance with the License.  You can obtain a copy
  66 in the file LICENSE in the source distribution or at
  67 L<https://www.openssl.org/source/license.html>.
  68
  69 =cut