libssh2_sftp_readdir_ex(3)

💖 libssh2_sftp_readdir_ex(3) 💖

okay bestie, welcome to the libssh2 manual, and specifically the page for libssh2_sftp_readdir_ex — the girl whose whole job is reading directory entries off an SFTP handle. she's giving ✨filesystem tour guide✨ energy and honestly? we're obsessed.

🌸 NAME 🌸

libssh2_sftp_readdir_ex — read directory data from an SFTP handle

🦋 SYNOPSIS 🦋

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

int
libssh2_sftp_readdir_ex(LIBSSH2_SFTP_HANDLE *handle,
                        char *buffer, size_t buffer_maxlen,
                        char *longentry, size_t longentry_maxlen,
                        LIBSSH2_SFTP_ATTRIBUTES *attrs);

🎀 DESCRIPTION 🎀

So like, what does she actually do? She reads a block of data from a LIBSSH2_SFTP_HANDLE and hands you back the file entry info for the next entry, if there even is one. That's it, that's the gig. 💅

Now let's meet the cast, because there are a lot of them:

• handle — the SFTP File Handle, as returned by libssh2_sftp_open_ex(3). it's your ticket, don't lose it.
• buffer — a pointer to a pre-allocated buffer of at least buffer_maxlen bytes that we read data into.
• buffer_maxlen — the length of buffer, in bytes. and bestie, listen: if the filename is longer than the space you gave it in buffer_maxlen, it's gonna get truncated to fit. no cap. it just gets chopped.
• longentry — a pointer to a pre-allocated buffer of at least longentry_maxlen bytes to read data into. and here's the thing: the format of the longname field is unspecified by the SFTP protocol. it MUST be suitable for use in the output of a directory listing command (fr fr, the recommended move for a directory listing command is literally to just display this data as-is).
• longentry_maxlen — the length of longentry in bytes. same deal as before: if the full directory entry is longer than the space in longentry_maxlen, it gets truncated to fit. 😭
• attrs — a pointer to LIBSSH2_SFTP_ATTRIBUTES storage, where she'll populate statbuf-style data for you.

✨ RETURN VALUE ✨

She returns the number of bytes actually populated into buffer — and no, that does not count the terminating zero, she's precise like that. 👑

Or, you know, negative on failure. And if she would otherwise block, she returns LIBSSH2_ERROR_EAGAIN. now here's the plot twist: even though LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. it's giving "girl, try again later" not "girl, we're done." 🙈

💀 BUG 💀

okay so this one's important, bestie, sit down. if you pass in a too small buffer for buffer or longentry when receiving data, then in libssh2 1.2.7 or earlier the only thing that happens is that she doesn't copy the entire data amount — and it is not possible for the application to tell when it happens! 💀 like, no error, no warning, nothing. you just silently get less than you asked for. terrifying. iconic in the worst way.

🌈 ERRORS 🌈

• LIBSSH2_ERROR_ALLOC — an internal memory allocation call failed.
• LIBSSH2_ERROR_SOCKET_SEND — unable to send data on socket.
• LIBSSH2_ERROR_SOCKET_TIMEOUT — (that's it, that's the whole description in the original, she just left it blank bestie, we don't invent lore)
• 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.

And from 1.2.8 onward? 🫶 LIBSSH2_ERROR_BUFFER_TOO_SMALL is returned if any of the given buffer or longentry buffers are too small to fit the requested object name. so yes, they fixed the silent-truncation nightmare above. slay.

👑 SEE ALSO 👑

• libssh2_sftp_open_ex(3)
• libssh2_sftp_close_handle(3)

and that's the whole page, bestie!! 💜 this was libssh2 0.15, dated 1 Jun 2007, and no I will not be explaining why a 2007 manpage has this much drama in it. go read some directories, stay hydrated, and please pass buffers that are big enough. mwah. 🎀🦋💖