SSL_GET_EVENT_TIMEOUT(3ossl)

📦
version 3.5.9 · 8 versions
, in fedora 43, fedora 44

💅 SSL_GET_EVENT_TIMEOUT(3ossl) — the OpenSSL girlies' guide

okay so bestie, you're in the 3ossl section, this is an OpenSSL page, and we're talking about SSL_get_event_timeout. it's giving "when do I need to come back and deal with you" energy ✨

🌸 NAME

SSL_get_event_timeout — figure out when an SSL object next needs to have its events handled 👑

🎀 SYNOPSIS

#include <openssl/ssl.h>

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

🦋 DESCRIPTION

so SSL_get_event_timeout() figures out when your SSL object next needs to do its internal processing, just because time keeps passing like it always does. no cap. ⏰

every single argument is required, okay?? tv and is_infinite must be non-NULL. not optional, not "I'll fill it in later". required. periodt.

when SSL_get_event_timeout() returns successfully, exactly one of these three situations is happening:

  • the SSL object has events that need to be handled right now, immediately. the fields of *tv are set to 0 and *is_infinite is set to 0. go go go 🏃♀️
  • the SSL object has events that need to be handled after some amount of time (measured relative to the time at which SSL_get_event_timeout() was called, fyi). *tv is set to the amount of time after which SSL_handle_events(3) should be called, and *is_infinite is set to 0. so like, set a little timer bestie ⏳
  • there are currently no timer events that need handling in the future. in that case the value of *tv is unspecified (don't look at it, it's not for you 🙈) and *is_infinite is set to 1. eternal peace. iconic.

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 that's considered a success condition, so don't stress 💖

for DTLS, you can use this function instead of the older DTLSv1_get_timeout(3) function. but heads up: this function differs from DTLSv1_get_timeout(3) in that the case where no timeout is active is considered a success condition. lowkey a glow-up.

also note that the value output by a call to SSL_get_event_timeout() may change as a result of other calls to the SSL object. it's a living document fr fr.

once the timeout expires, SSL_handle_events(3) should be called to handle any internal processing which is due; for more information, see SSL_handle_events(3). 👈 read that one too.

and also: SSL_get_event_timeout() supersedes the older DTLSv1_get_timeout(3) function for all use cases. all of them. it ate and left no crumbs. 🔥

⚠️ 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 don't trust them after a failure, bestie. that's just how it is 💀

⭐ RETURN VALUES

returns 1 on success and 0 on failure. simple as that, no plot twist 🫶

🌈 SEE ALSO

✨ HISTORY

the SSL_get_event_timeout() function was added in OpenSSL 3.2. a relatively recent queen 👑

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>.

okay that's the whole page, you're so welcome 💖 this was version 3.5.9, dated 2026-09-29, and yes the manual name is SSL_GET_EVENT_TIMEOUT(3ossl) in case you forgot already. mwah, go handle your events 🎀✨

📦 where this page comes from