SSL_SET_BLOCKING_MODE(3ossl)

📦 version 15.1, in freebsd 15.1

💅 SSL_SET_BLOCKING_MODE(3ossl) — the blocking-mode glow-up for QUIC ✨

Okay so bestie, this is one of those pages from the OpenSSL manual (that's the 3ossl manual, iykyk) and honestly it's lowkey iconic — it's all about telling a QUIC SSL object whether it should wait for stuff or just ✨move on✨. Let's get into it fr fr.

🌸 NAME 🌸

SSL_set_blocking_mode, SSL_get_blocking_mode — the two functions that let you configure blocking mode for a QUIC SSL object. One sets it, one gets it. Simple. Slay.

🎀 SYNOPSIS 🎀

#include <openssl/ssl.h>

int SSL_set_blocking_mode(SSL *s, int blocking);
int SSL_get_blocking_mode(SSL *s);

That's the whole vibe. Two little functions, one big personality.

💖 DESCRIPTION 💖

So here's the tea: SSL_set_blocking_mode() is what you call to enable or disable blocking mode on a QUIC connection SSL object. And the default? Blocking is on — enabled — unless your SSL object is set up to use an underlying read or write BIO that can't give you a poll descriptor (peep BIO_get_rpoll_descriptor(3) for that one), because no cap, blocking mode literally cannot be supported in that case. 🫶

Wanna turn blocking mode on? Call SSL_set_blocking_mode() with blocking set to 1. Wanna turn it off? Call it with blocking set to 0. That's it. That's the whole trick. 🦋

Wanna know what mode you're currently in? Call SSL_get_blocking_mode() and it'll tell you. Main character energy: you ask, it answers. ✨

Now what does "blocking mode" actually mean? It means calls like SSL_read() and SSL_write() will block until the requested operation can actually be performed. Like, they'll sit there and wait. Patiently. 🧚 In nonblocking mode, those same calls will just fail if the requested operation can't be performed immediately — no waiting around — and you go check SSL_get_error(3) to find out what happened.

Heads up bestie: these functions only apply to QUIC connection SSL objects. Periodt. Other kinds of SSL object, like the TLS ones, automatically do blocking or nonblocking mode based on whether the underlying network read and write BIOs handed to the SSL object are themselves configured in nonblocking mode. So they don't need you micromanaging them. 💅

And if you're using a QUIC connection SSL object in nonblocking mode? That's on you, babe — the application is responsible for making sure the SSL object gets ticked regularly. Go read SSL_handle_events(3) for that. 🕐

One more thing (important, ngl): blocking mode gets disabled automatically if the application gives a QUIC connection SSL object a network BIO that can't support blocking mode. 😭 And if you want to re-enable blocking mode after that happens? You gotta do two things: set a network BIO that can support blocking mode, and then explicitly call SSL_set_blocking_mode(). It won't just come back on its own, okay? You have to ask. 🙈

🔥 RETURN VALUES 🔥

  • SSL_set_blocking_mode() returns 1 on success and 0 on failure. 💀 It fails if you call it on an SSL object that doesn't represent a QUIC connection, or if blocking mode can't be used for the given connection. Know your limits, function.
  • SSL_get_blocking_mode() returns 1 if blocking is currently enabled. It returns -1 if you call it on an unsupported SSL object. Rude, but fair.

🌈 SEE ALSO 🌈

Go give these a read, bestie, they're all part of the same friend group:

👑 HISTORY 👑

The SSL_set_blocking_mode() and SSL_get_blocking_mode() functions were added in OpenSSL 3.2. So if you're on something older, sorry babe, they're not there yet. 💜

Copyright 2022-2025 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, bestie. This was SSL_SET_BLOCKING_MODE(3ossl) from OpenSSL 3.5.6, dated 2026-04-07 — go forth and block (or don't) responsibly. Mwah. 💖✨

📦 where this page comes from