libssh2_sftp_stat_ex(3)

💅 libssh2_sftp_stat_ex — get status about an SFTP file

okay bestie, so this is a page from the libssh2 manual, and it's literally about peeking at (or setting) the metadata of a file chilling on a remote SFTP server. it's giving detective energy 🔍✨. come sit with me, i got you.

✨ SYNOPSIS ✨

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

int
libssh2_sftp_stat_ex(LIBSSH2_SFTP *sftp, const char *path,
                     unsigned int path_len, int stat_type,
                     LIBSSH2_SFTP_ATTRIBUTES *attrs);

🎀 DESCRIPTION 🎀

here's the whole cast of characters, one by one:

• sftp — the SFTP instance, as handed to you by libssh2_sftp_init(3). she's the whole vibe, your connection to the server.
• path — the remote filesystem object you wanna stat / lstat / setstat. yep, that's the target. 🎯
• path_len — the length of the name of that remote filesystem object you're stat / lstat / setstat-ing. like, the actual character count. don't sleep on it.
• stat_type — this is the main character of the whole function ngl. it's one of three constants that decide what kind of stat operation happens:
  • LIBSSH2_SFTP_STAT: does a stat(2) operation
  • LIBSSH2_SFTP_LSTAT: does an lstat(2) operation
  • LIBSSH2_SFTP_SETSTAT: does the operation that sets stat info on the file
• attrs — a pointer to a LIBSSH2_SFTP_ATTRIBUTES structure. depending on what stat_type is, you're either pulling file metadata into it or pushing metadata out of it. it's a two-way street bestie 🫶

so, the tea: this function gets or sets statbuf type data on a remote filesystem object. and when you're getting statbuf data, the difference matters, okay? libssh2_sftp_stat(3) will follow all symlinks — she's nosy like that, she goes all the way to the end. meanwhile libssh2_sftp_lstat(3) will return data about the object actually encountered, even if that object happens to be a symlink. like, she reports on the link herself, no chasing. periodt. 🔗

the LIBSSH2_SFTP_ATTRIBUTES struct looks exactly like this, no cap:

struct LIBSSH2_SFTP_ATTRIBUTES {
    /* If flags & ATTR_* bit is set, then the value in this struct will be
     * meaningful Otherwise it should be ignored
     */
    unsigned long flags;

    libssh2_uint64_t filesize;
    unsigned long uid;
    unsigned long gid;
    unsigned long permissions;
    unsigned long atime;
    unsigned long mtime;
};

okay important: if flags & ATTR_* bit is set, then the value in that struct is meaningful. otherwise? ignore it. she's not telling you anything, don't read into it. 🙈

🔥 RETURN VALUE 🔥

returns 0 on success, or negative on failure. it returns LIBSSH2_ERROR_EAGAIN when it would otherwise block. and yeah, LIBSSH2_ERROR_EAGAIN is a negative number, but it's not really a failure per se — it's more like "bestie i'm busy, try again in a sec" energy. don't panic. 💀

😭 ERRORS 😭

• LIBSSH2_ERROR_ALLOC — an internal memory allocation call failed. the memory said no. tragic.
• LIBSSH2_ERROR_SOCKET_SEND — unable to send data on socket. the socket ghosted you.
• LIBSSH2_ERROR_SOCKET_TIMEOUT — (yeah that's it, that's the description. iconic of them honestly.)
• 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. so either the server sent nonsense back, or the server itself said "error". either way, not it. 💀

👀 SEE ALSO 👀

• libssh2_sftp_init(3)

that's the whole page bestie, you ate it. this one's from the libssh2 manual, version 0.15, dated 1 Jun 2007 — yeah she's vintage but she still slays. now go stat something. 💖🦋✨