BIO_SOCKET_WAIT(3ssl)

📦 version 4.1.0, in nixos 26.05, nixpkgs unstable

💅 BIO_SOCKET_WAIT(3ssl) — like, the OpenSSL manual page, but make it make sense 🫶

okay so bestie, this is a page from the OpenSSL manual set — the 3ssl section, which is where all the library-function lore lives. buckle up, we're talking about socket waiting and connection retries and honestly it's giving "quietly load-bearing utility functions" ✨

🌸 NAME 🌸

BIO_socket_wait, BIO_socket_ready, BIO_wait, BIO_do_connect_retry — these are the BIO connection utility functions. tiny little helpers, but they do a LOT of the emotional labor of getting a connection up 💅

✨ SYNOPSIS ✨

#include <openssl/bio.h>

#ifndef OPENSSL_NO_SOCK
int BIO_socket_wait(int fd, int for_read, time_t max_time);
int BIO_socket_ready(int fd, int for_read);
#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);

note the #ifndef OPENSSL_NO_SOCK guard around the first two — if sockets aren't compiled in, those two just don't exist for you, sorry not sorry 😭 the other two are always around 🧚

🦋 DESCRIPTION 🦋

BIO_socket_wait ⏳

BIO_socket_wait() waits on the socket fd — like, it literally sits there and chills. if for_read is not 0 it's waiting for reading, otherwise it's waiting for writing, and it waits at most until max_time.

big mood: if max_time == 0 (which means no timeout given) it succeeds immediately. no waiting, no drama, instant slay 🎀

💫 BIO_socket_ready

BIO_socket_ready() is the non-blocking icon. it checks whether the socket fd is ready for reading (if for_read is not 0) or else for writing — without blocking. it does not wait, it just peeks.

this one is genuinely useful for polling a socket to figure out if an I/O operation can be performed immediately without waiting. vibe check on the socket, basically 👑

🌈 BIO_wait

BIO_wait() waits at most until max_time on the given bio (typically socket-based) — for reading if bio is supposed to read, else for writing.

  • it's used by BIO_do_connect_retry(), and
  • you can use it together with BIO_read(3) 🫶

again: it succeeds immediately if max_time == 0 (which means no timeout given).

and here's the cute part — if sockets are not available, it supports polling by succeeding after sleeping at most the given nap_milliseconds, specifically so you don't get a tight busy loop 🌀 via nap_milliseconds the caller decides the polling granularity. you're the boss of how often it wakes up 💅

🧚 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:

  • 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() 😴

the numbers, exactly:

  • if nap_milliseconds is < 0 then a default value of 100 ms is used
  • if the timeout parameter is > 0 this indicates 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 if you were emotionally attached to whatever was sitting in the error queue, it might get swept out from under you 😭

🍓 RETURN VALUES 🍓

BIO_socket_wait(), BIO_socket_ready(), BIO_wait(), and BIO_do_connect_retry() all return:

  • -1 on error 💀
  • 0 on timeout (or not ready, in the case of BIO_socket_ready())
  • 1 on success (or ready, in the case of BIO_socket_ready()) ✅

so it's a cute little -1 / 0 / 1 trio. iykyk 🌟

👀 SEE ALSO 👀

go read those too, they're the main characters of this friend group 💜

🕰️ HISTORY 🕰️

  • BIO_socket_wait(), BIO_wait(), and BIO_do_connect_retry() were added in OpenSSL 3.0 ✨
  • BIO_socket_ready() was added in OpenSSL 4.1 — a newer addition, freshly iconic 🎀

Copyright 2019-2026 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>.

okay that's the whole page, no cap 💖 this was OpenSSL 4.1.0, dated 2026-10-23 — so if you're reading this from the future, hi, hope your sockets were ready 🌈✨💅

📦 where this page comes from