libssh2_sftp_read(3)

💖 libssh2_sftp_read(3) 💖

okay bestie, welcome to the libssh2 manual page for libssh2_sftp_read — she's the one who pulls actual data out of your SFTP handle, and honestly? iconic. 🦋

✨ NAME ✨

libssh2_sftp_read — read data from an SFTP handle 🌸

✨ SYNOPSIS ✨

#include <libssh2.h>
#include <libssh2_sftp.h>

ssize_t
libssh2_sftp_read(LIBSSH2_SFTP_HANDLE *handle,
                  char *buffer, size_t buffer_maxlen);

✨ DESCRIPTION ✨

okay so. handle is the SFTP File Handle — the one you got handed back by libssh2_sftp_open_ex(3). 💅

buffer is a pointer to a pre-allocated buffer, and it needs to be at least

buffer_maxlen bytes big, because that's where the data's getting read into. no negotiating on that one, she needs the room. 🫶

So what does it do? It reads a block of data from an LIBSSH2_SFTP_HANDLE. This method is modelled after the POSIX read(2) function and uses the same calling semantics — literally the same energy, just SFTP-flavoured. 🎀

Here's the tea though: libssh2_sftp_read(3) will attempt to read as much as possible, however it may not fill all of buffer if the file pointer reaches the end, or if further reads would cause the socket to block. so like, don't come for her if you don't get a full buffer back, she's doing her best. 😭

✨ RETURN VALUE ✨

She returns the number of bytes actually populated into buffer. 📏

Or, negative on failure. 🙈

Specifically, it returns LIBSSH2_ERROR_EAGAIN when it would otherwise block. And this is the important bit bestie: while LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. it's giving "not right now, try again later", not "everything is on fire". ⭐

✨ ERRORS ✨

• LIBSSH2_ERROR_ALLOC — an internal memory allocation call failed. the allocator said no. 💀
• LIBSSH2_ERROR_SOCKET_SEND — unable to send data on socket. the socket ghosted us. 👻
• LIBSSH2_ERROR_SOCKET_TIMEOUT — (yes, that's it, that's the whole description in the original too. she's mysterious like that.) ⌛
• LIBSSH2_ERROR_SFTP_PROTOCOL — an invalid SFTP protocol response was received on the socket, or an SFTP operation caused an errorcode to be returned by the server. server said something unhinged. 🚩

✨ SEE ALSO ✨

• libssh2_sftp_open_ex(3)
• libssh2_sftp_read(3)

(yes she references herself in SEE ALSO. main character energy, we respect it. 👑)

and that's the whole page bestie!! 💖 this one's from libssh2 0.15, dated 1 Jun 2007 — vintage, but she still ate. 🎀✨🦋 periodt.