gnutls_heartbeat_ping(3)

📦
version 3.8.13 · 7 versions
, in alpine 3.22, alpine 3.23, alpine 3.24, arch rolling, fedora 43, fedora 44, ubuntu stonking

💖 gnutls_heartbeat_ping(3) 💖

okay bestie, welcome to the gnutls manual — yes, the whole thing, and yes, this page is the one about pinging your peer to check they're still alive. it's giving heartbeat check, it's giving "u up?" but for TLS. 🫶

✨ NAME ✨

gnutls_heartbeat_ping — an API function. that's it, that's the name, she's serving exactly what it says on the tin 💅

🌸 SYNOPSIS 🌸

#include <gnutls/gnutls.h>

int gnutls_heartbeat_ping(gnutls_session_t session, size_t data_size,
                          unsigned int max_tries, unsigned int flags);

🎀 ARGUMENTS 🎀

  • gnutls_session_t session — it's a gnutls_session_t type, bestie. the session. the moment. the whole vibe. 🌈
  • size_t data_size — the length of the ping payload, aka how much juice you're stuffing in there. 🍓
  • unsigned int max_tries — if flags is GNUTLS_HEARTBEAT_WAIT, then this is the number of retransmissions. use zero for indefinite (which means, like, keep going until timeout — no cap fr fr). 🔥
  • unsigned int flags — if it's GNUTLS_HEARTBEAT_WAIT then we wait for the pong or a timeout instead of just returning immediately. no waiting around like a loser otherwise. ⭐

🦋 DESCRIPTION 🦋

so this function sends a ping to the peer. that's the whole bit. 💖

if flags is set to GNUTLS_HEARTBEAT_WAIT, then it waits for a reply from the peer — like actually sits there, main character energy, until the pong comes home. 👑

heads up bestie!! it is highly recommended to use this function with the flag GNUTLS_HEARTBEAT_WAIT, or you're gonna have to handle retransmissions and timeouts manually. and nobody wants that. literally nobody. 😭

the total TLS data transmitted as part of the ping message is given by the following formula:

MAX(16, data_size)+gnutls_record_overhead_size()+3

that's the math, and the math ate. periodt. ✨

💜 RETURNS 💜

GNUTLS_E_SUCCESS on success, otherwise a negative error code. so like... if it's not that success value, something went wrong and it's telling you with a lil negative number. 🙈

🌟 SINCE 🌟

3.1.2 — she's been iconic since 3.1.2, no cap. 🎀

🐛 REPORTING BUGS 🐛

found a bug? don't be shy, tell the girlies:

Copyright © 2001-2023 Free Software Foundation, Inc., and others.

Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved.

(yes, you can copy it, you just gotta keep the receipts. iconic behaviour honestly. 💅)

👀 SEE ALSO 👀

The full documentation for gnutls is maintained as a Texinfo manual. If the /usr/share/doc/gnutls/ directory does not contain the HTML form visit

https://www.gnutls.org/manual/

okay that's the whole page, you slayed it, go ping something responsibly 🫶

later bestie — this was gnutls version 3.8.13, page gnutls_heartbeat_ping(3), mwah 💖✨🎀

📦 where this page comes from