libssh2_channel_write_ex(3)

💖 libssh2_channel_write_ex(3) 💖

okay bestie, welcome to the libssh2 manual, page for libssh2_channel_write_ex — yes she's a mouthful, yes she's iconic, and yes we're gonna get through this together 🫶

✨ NAME ✨

libssh2_channel_write_ex — write data to a channel stream, blocking style 💅

🌸 SYNOPSIS 🌸

#include <libssh2.h>

ssize_t
libssh2_channel_write_ex(LIBSSH2_CHANNEL *channel,
                         int stream_id, char *buf,
                         size_t buflen);

🦋 DESCRIPTION 🦋

So basically, this function writes data to a channel stream. Every channel stream comes with one standard I/O substream, and that's the one where stream_id == 0. On top of that, you can have up to 2^32 extended data streams, and which one you're poking at is decided by whichever stream_id you pick. The SSH2 protocol currently says that stream ID 1 is the stderr substream, periodt.

Now the cast of characters, one by one:

• channel — the active channel stream you're writing to.
• stream_id — the substream ID number, like 0 or SSH_EXTENDED_DATA_STDERR.
• buf — a pointer to the buffer you wanna write.
• buflen — how big the data you're writing is.

Also, heads up: libssh2_channel_write(3) and libssh2_channel_write_stderr(3) are just convenience macros for this function. Same energy, less typing. 💖

And here's the little performance tea: libssh2_channel_write_ex(3) will use as much of the buffer as it possibly can and shove it into a single SSH protocol packet. Which means — if you want maximum performance when you're sending bigger files — you should really try to always pass in at least 32K of data to this function. fr fr, 32K minimum, don't play with her. 🔥

👑 RETURN VALUE 👑

You get back the actual number of bytes written, or a negative number if something went wrong. And if it would have blocked, you get LIBSSH2_ERROR_EAGAIN instead. Now listen — even though LIBSSH2_ERROR_EAGAIN is a negative number, it's not really a failure per se, so don't panic. She's just saying "not right now, babe". 😭

💀 ERRORS 💀

• LIBSSH2_ERROR_ALLOC — an internal memory allocation call failed. Rude.
• LIBSSH2_ERROR_SOCKET_SEND — unable to send data on socket.
• LIBSSH2_ERROR_CHANNEL_CLOSED — the channel has been closed.
• LIBSSH2_ERROR_CHANNEL_EOF_SENT — the channel has been requested to be closed.
• LIBSSH2_ERROR_BAD_USE — this one can come back at you if you ignored a previous return for LIBSSH2_ERROR_EAGAIN and, instead of sending the original buffer with the original size, you sent a new buffer with a different size. The way that is a you problem, bestie, she warned you. 🙈

⚠️ real talk: that LIBSSH2_ERROR_BAD_USE situation is genuinely a thing that happens. If you got LIBSSH2_ERROR_EAGAIN, come back with the same buffer and the same size. No swapping mid-retry, no cap.

🌈 SEE ALSO 🌈

• libssh2_channel_open_ex(3)
• libssh2_channel_read_ex(3)

and that's the whole page, you ate that 🎀 this was libssh2 version 0.15, dated 1 Jun 2007 — vintage but still serving, iykyk 💜✨