libssh2_sftp_fstat_ex(3)

💖 libssh2_sftp_fstat_ex(3) — the libssh2 manual, but make it cute 💖

okay bestie, sit down, hydrate, because we're learning about libssh2_sftp_fstat_ex from the libssh2 manual and honestly? it's giving ✨file handle metadata✨ and I'm obsessed.

---

🌸 NAME 🌸

libssh2_sftp_fstat_ex — get or set attributes on an SFTP file handle 🫶

---

✨ SYNOPSIS ✨

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

int
libssh2_sftp_fstat_ex(LIBSSH2_SFTP_HANDLE *handle,
                      LIBSSH2_SFTP_ATTRIBUTES *attrs, int setstat)

#define libssh2_sftp_fstat(handle, attrs) \
    libssh2_sftp_fstat_ex((handle), (attrs), 0)
#define libssh2_sftp_fsetstat(handle, attrs) \
    libssh2_sftp_fstat_ex((handle), (attrs), 1)

like. the macros are literally just this one function with a 0 or a 1 tacked on. no cap. 🎀

---

💅 DESCRIPTION 💅

• handle — the SFTP File Handle, as returned by libssh2_sftp_open_ex(3) 🦋
• attrs — a pointer to an LIBSSH2_SFTP_ATTRIBUTES structure, which is where file metadata gets read from or written into, depending on what setstat says 💫
• setstat — when this is non-zero, the file's metadata gets updated with the data found in attrs, following the values of attrs->flags and the other relevant member attributes. when it's zero, we're just reading, bestie 🙈

so basically: get or set statbuf type data for a given LIBSSH2_SFTP_HANDLE instance. iconic. no notes. 👑

---

🧚 DATA TYPES 🧚

LIBSSH2_SFTP_ATTRIBUTES is a typedefed struct, and here's exactly what it looks like:

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;

    /* size of file, in bytes */
    libssh2_uint64_t filesize;

    /* numerical representation of the user and group owner of
     * the file
     */
    unsigned long uid, gid;

    /* bitmask of permissions */
    unsigned long permissions;

    /* access time and modified time of file */
    unsigned long atime, mtime;
};

you'll find a whole full set of defines and macros for identifying flags and permissions over in the libssh2_sftp.h header file, but here are some of the most common ones, bestie, because I got you 💖

---

🔐 Permission checks 🔐

to check for specific user permissions, the set of defines follows the pattern LIBSSH2_SFTP_S_I<action><who> — where <action> is R, W or X for read, write and executable, and <who> is USR, GRP and OTH for user, group and other. so if you wanna check for a user readable file, you use the bit LIBSSH2_SFTP_S_IRUSR, and if you wanna see whether it's executable for other, you use LIBSSH2_SFTP_S_IXOTH, and so on and so on. periodt. ✨

---

📁 File type checks 📁

to check for specific file types, you previously (as in, before libssh2 1.2.5) used the standard posix S_IS***() macros. but since 1.2.5, libssh2 offers its own set of macros for this functionality:

• LIBSSH2_SFTP_S_ISLNK — test for a symbolic link 🔗
• LIBSSH2_SFTP_S_ISREG — test for a regular file 📄
• LIBSSH2_SFTP_S_ISDIR — test for a directory 📁
• LIBSSH2_SFTP_S_ISCHR — test for a character special file 🎭
• LIBSSH2_SFTP_S_ISBLK — test for a block special file 🧱
• LIBSSH2_SFTP_S_ISFIFO — test for a pipe or FIFO special file 🚰
• LIBSSH2_SFTP_S_ISSOCK — test for a socket 🔌

---

🌈 RETURN VALUE 🌈

returns 0 on success, or a negative number on failure. it returns LIBSSH2_ERROR_EAGAIN when it would otherwise block. and okay, important note bestie: while LIBSSH2_ERROR_EAGAIN is a negative number, it's not really a failure per se. it's just doing its little thing. don't panic. 💜

---

💀 ERRORS 💀

• LIBSSH2_ERROR_ALLOC — an internal memory allocation call failed 😭
• LIBSSH2_ERROR_SOCKET_SEND — unable to send data on socket 📡
• LIBSSH2_ERROR_SOCKET_TIMEOUT — (no description given, it'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 🚨

---

⭐ AVAILABILITY ⭐

this function has been around since forever, fr fr. but most of the LIBSSH2_SFTP_S_* defines were introduced in libssh2 0.14, and the LIBSSH2_SFTP_S_IS***() macros were introduced in libssh2 1.2.5. so if you're on something ancient, vibe check your version first. 👑

---

🦋 SEE ALSO 🦋

• libssh2_sftp_open_ex(3) 💖

---

and that's the whole page, bestie!! this little cutie comes to you from libssh2 0.15, dated 1 Jun 2007 — yeah, she's vintage, she's iconic, she ate and left no crumbs 👑✨ mwah, go write some SFTP code, you've got this 💅💖🌸