SSL_WANT(3)

🌸 NAME 🌸

okay so welcome to SSL_WANT(3), bestie — this is the Library Functions Manual page for the little crew of functions that obtain state information about a TLS/SSL I/O operation. The squad is:

• SSL_want, SSL_want_nothing, SSL_want_read, SSL_want_write, SSL_want_x509_lookup — obtain state information about a TLS/SSL I/O operation. yes, all of them, and they’re all about that state-info life. 💅

✨ SYNOPSIS ✨

library “libssl” libcrypto #include <openssl/ssl.h>

int
SSL_want(const SSL *ssl);

int
SSL_want_nothing(const SSL *ssl);

int
SSL_want_read(const SSL *ssl);

int
SSL_want_write(const SSL *ssl);

int
SSL_want_x509_lookup(const SSL *ssl);

💅 DESCRIPTION 💅

okay so SSL_want() returns state information for the SSL object ssl. that’s the main character of this whole page. ✨

The other SSL_want_*() calls are shortcuts for the possible states returned by SSL_want(). lowkey just convenience wrappers, highkey the same info. 🫶

SSL_want() examines the internal state information of the SSL object. Its return values are similar to those of SSL_get_error(3). but bestie, the way it gets them is different: unlike SSL_get_error(3), which also evaluates the error queue, the results are obtained by examining an internal state flag only. so the information must therefore only be used for normal operation under non-blocking I/O. 🦋

Error conditions are not handled and must be treated using SSL_get_error(3). do not try to make SSL_want() do error-queue detective work, because it will not. 🙈

The result returned by SSL_want() should always be consistent with the result of SSL_get_error(3). periodt. consistency is the moment. 💖

🔥 RETURN VALUES 🔥

The following return values can currently occur for SSL_want():

• SSL_NOTHING — there is no data to be written or to be read. literally nothing on the I/O agenda. 😌
• SSL_WRITING — there are data in the SSL buffer that must be written to the underlying BIO layer in order to complete the actual SSL_*() operation. A call to SSL_get_error(3) should return SSL_ERROR_WANT_WRITE. it’s giving “write me to the BIO layer so we can finish” energy. ✍️
• SSL_READING — more data must be read from the underlying BIO layer in order to complete the actual SSL_*() operation. A call to SSL_get_error(3) should return SSL_ERROR_WANT_READ. read era, no cap. 📖
• SSL_X509_LOOKUP — the operation did not complete because an application callback set by SSL_CTX_set_client_cert_cb(3) has asked to be called again. A call to SSL_get_error(3) should return SSL_ERROR_WANT_X509_LOOKUP. callback said “run me back,” and honestly? iconic. 🔁

SSL_want_nothing(), SSL_want_read(), SSL_want_write(), and SSL_want_x509_lookup() return 1 when the corresponding condition is true or 0 otherwise. simple as that. 💯

🦋 SEE ALSO 🦋

Go be nosy, bestie: err(3), ssl(3), SSL_get_error(3). all the related lore is right there. 📚

🎀 HISTORY 🎀

history lesson but make it cute: SSL_want(), SSL_want_nothing(), SSL_want_read(), and SSL_want_write() first appeared in SSLeay 0.5.2. SSL_want_x509_lookup() first appeared in SSLeay 0.6.0. These functions have been available since OpenBSD 2.4. so they’ve been around for a minute. ⭐

mwah 💋 — this page comes from Debian, dated June 8, 2025. now go handle your non-blocking I/O, bestie 🫶✨