libssh2_session_disconnect_ex(3)

💖 libssh2_session_disconnect_ex — bestie's guide to saying bye 👋

okay so this is one of the libssh2 manual pages (that's the manual name btw, libssh2, we're in the big leagues) and it's literally just about hanging up on the other end of your SSH connection. gracefully. with manners. ✨

🌸 NAME 🌸

libssh2_session_disconnect_ex — terminate transport layer

like... end the convo. close the door. exit the chat. no ghosting, we do this properly. 💅

🎀 SYNOPSIS 🎀

#include <libssh2.h>

int
libssh2_session_disconnect_ex(LIBSSH2_SESSION *session, int reason,
                              const char *description,
                              const char *lang);

int
libssh2_session_disconnect(LIBSSH2_SESSION *session,
                           const char *description);

yes bestie there are two of them, one is the whole deluxe version and one is the little convenience macro, we'll get to that 🫶

🦋 DESCRIPTION 🦋

okay so here's the tea, parameter by parameter, no skips:

• session — the Session instance you got back from libssh2_session_init_ex(3). that's your whole connection babe, you can't just say bye into the void.
• reason — one of the Disconnect Reason constants. pick your vibe.
• description — a human readable reason for disconnection. like actually explain yourself, in words.
• lang — a localization string describing the language/encoding of the description you just provided. yes it needs to know what language you're being dramatic in.

so what does it do? it sends a disconnect message to the remote host associated with session, and it brings along a reason symbol and a verbose description. the full package. 📦✨

and then, as a little convenience treat, there's the macro libssh2_session_disconnect(3). it's giving "we did the work so you don't have to" — it just calls libssh2_session_disconnect_ex(3) for you with reason set to SSH_DISCONNECT_BY_APPLICATION and lang set to an empty string. lowkey the move if you don't care about customizing your goodbye. 🌈

👑 RETURN VALUE 👑

• returns 0 on success — slay, you disconnected 🎉
• returns negative on failure — the goodbye did not land 😭
• it returns LIBSSH2_ERROR_EAGAIN when it would otherwise block.

and okay, important nuance because the way people read this matters: while LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. it's not the situation being broken, it's just "not right now bestie, come back later". do not panic. do not spiral. 💀

🌟 SEE ALSO 🌟

• libssh2_session_init_ex(3) — the origin story, where your session came from 💜

and that's the whole page fr fr. this one's from libssh2 version 0.15, dated 1 Jun 2007 — vintage but iconic, we stan a classic. bye bestie, disconnect responsibly 🧚💖