BIO_SOCKET_WAIT(3SSL)

📦
version 4.0.3 · 13 versions
, in ubuntu stonking

💖 BIO_SOCKET_WAIT(3SSL) 💖

okay bestie so this is a page from the OpenSSL manual, section 3SSL, and we're talking about the BIO connection utility functions: BIO_socket_wait, BIO_wait, and BIO_do_connect_retry. pull up a chair, grab a matcha, we're doing sockets today 🍓

✨ NAME ✨

BIO_socket_wait, BIO_wait, BIO_do_connect_retry — the BIO connection utility functions, aka the little trio that waits around for your sockets so you don't have to. 💅

🌸 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 nap_milliseconds);
int BIO_do_connect_retry(BIO *bio, int timeout, int nap_milliseconds);

see how BIO_socket_wait is wrapped in that #ifndef OPENSSL_NO_SOCK? yeah. if you compiled without sockets, that one literally does not exist. no cap. 🙈

🦋 DESCRIPTION 🦋

BIO_socket_wait 🌈

BIO_socket_wait() waits on the socket fd — for reading if for_read is not 0, otherwise for writing — and it waits at most until max_time. and here's the slay detail: it succeeds immediately if max_time == 0, because that means no timeout was given. so 0 is not "wait zero seconds", it's "bestie I'm not putting a clock on this". ⭐

BIO_wait 💜

BIO_wait() waits at most until max_time on the given bio — typically a socket-based one — for reading if the bio is supposed to read, else for writing. it's the engine inside BIO_do_connect_retry(), and you can also pair it up with BIO_read(3). same energy as above: it succeeds immediately if max_time == 0 (that means no timeout given). 🫶

and if sockets are not available? it still supports polling — it succeeds after sleeping at most the given nap_milliseconds, specifically so you don't end up in a tight busy loop burning your CPU for no reason. 😭 via nap_milliseconds the caller decides the polling granularity. your nap, your rules. 😴

BIO_do_connect_retry 👑

BIO_do_connect_retry() connects via the given bio. it retries BIO_do_connect() as far as needed to reach a definite outcome, i.e. one of these three iconic endings:

  • connection succeeded ✨
  • timeout has been reached ⏰
  • an error occurred 💀

for nonblocking and potentially even non-socket BIOs, it polls every nap_milliseconds and sleeps in between using BIO_wait(). if nap_milliseconds is < 0, then a default value of 100 ms is used. 🌸

now the timeout parameter, listen closely:

  • if timeout is > 0, that's the maximum number of seconds to wait until the connection is established or a definite error occurred.
  • a value of 0 enables waiting indefinitely (i.e, no timeout).
  • a value < 0 means that BIO_do_connect() is tried only once.
⚠️ heads up bestie: the function may, directly or indirectly, invoke ERR_clear_error(). so don't be gagged when your error queue comes back looking different. 👀

💅 RETURN VALUES 💅

BIO_socket_wait(), BIO_wait(), and BIO_do_connect_retry() all use the same little report card:

  • -1 — error 😭
  • 0 — timeout ⏰
  • 1 — success ✨

three values, three moods. periodt.

🌟 SEE ALSO 🌟

go read those next, iykyk 📚

🎀 HISTORY 🎀

BIO_socket_wait(), BIO_wait(), and BIO_do_connect_retry() were added in OpenSSL 3.0. so if you're on something older... bestie. upgrade. 💀

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 <https://www.openssl.org/source/license.html>.

and that's the whole page, babe 🫶 this was OpenSSL 4.0.3, dated 2026-09-29, filed under BIO_SOCKET_WAIT(3SSL). go forth and connect responsibly 💖✨🌸

📦 where this page comes from