SSL_GET_EVENT_TIMEOUT(3SSL)

📦
version 4.0.3 · 6 versions
, in ubuntu stonking

💖 SSL_GET_EVENT_TIMEOUT 💖

okay so bestie, we're in SSL_GET_EVENT_TIMEOUT(3SSL) territory and it's giving ✨time management✨ for your SSL objects. like, when does this thing need attention next? that's the whole vibe.

🌸 NAME 🌸

SSL_get_event_timeout — figures out when an SSL object next needs to have events handled 💅

🦋 SYNOPSIS 🦋

#include <openssl/ssl.h>

int SSL_get_event_timeout(SSL *s, struct timeval *tv, int *is_infinite);

✨ DESCRIPTION ✨

SSL_get_event_timeout() is literally the function that tells you when the SSL object next needs to perform internal processing due to the passage of time. like, time keeps passing, bestie, and somebody's gotta notice. 🕰️

All arguments are required, no cap. tv and is_infinite must be non-NULL. don't try to be cute and pass nothing, it will not slay.

When SSL_get_event_timeout() returns successfully, one of these three situations is what you're in:

  • 🚨 The SSL object has events that need to be handled right now, immediately, this second. The fields of *tv are set to 0 and *is_infinite is set to 0.
  • ⏳ The SSL object has events that need to be handled after some amount of time (relative to the time at which SSL_get_event_timeout() was called). *tv gets set to the amount of time after which SSL_handle_events(3) should be called, and *is_infinite is set to 0.
  • 🌈 There are currently no timer events which require handling in the future. The value of *tv is unspecified and *is_infinite is set to 1.

ngl, this function is currently applicable only to DTLS and QUIC connection SSL objects. if you call it on any other kind of SSL object, it always outputs infinity. and the way that… that's considered a success condition 🫶. not a bug, not a fail, just infinity, iconic.

For DTLS, you can use this instead of the older DTLSv1_get_timeout(3) function. the key difference, and this is the part i need you to remember: this function differs from DTLSv1_get_timeout(3) in that the case where no timeout is active is considered a success condition. yes queen, no timeout is a good thing here.

Also lowkey important: the value output by a call to SSL_get_event_timeout() may change as a result of other calls to the SSL object. so don't stash it somewhere forever like it's gospel, bestie, it's a snapshot 📸.

Once the timeout expires, SSL_handle_events(3) should be called to handle any internal processing which is due. for more info, go read SSL_handle_events(3). like actually read it.

And, note: SSL_get_event_timeout() supersedes the older DTLSv1_get_timeout(3) function for all use cases. periodt. old one is retired, new one eats 💅

⚠️ If the call to SSL_get_event_timeout() fails, the values of *tv and *is_infinite may still be changed and their values become unspecified. so basically, don't trust them after a fail. it's giving chaos, and not the cute kind 💀

🔥 RETURN VALUES 🔥

  • Returns 1 on success ✅
  • Returns 0 on failure 😭

👑 SEE ALSO 👑

🎀 HISTORY 🎀

The SSL_get_event_timeout() function was added in OpenSSL 3.2. so if you're on something older, it's not there, sorry babe 🙈

Copyright 2022-2023 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, bestie 🫶 this was version 4.0.3, dated 2026-09-29, and it's the SSL_GET_EVENT_TIMEOUT(3SSL) manual — go handle your events, mwah 💖✨🌈

📦 where this page comes from