libssh2\_sftp\_fstat\_ex(3) libssh2 libssh2\_sftp\_fstat\_ex(3)

# [NAME](#NAME)

libssh2\_sftp\_fstat\_ex - get or set attributes on an SFTP file handle

# [SYNOPSIS](#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)
```

# [DESCRIPTION](#DESCRIPTION)

*handle* - SFTP File Handle as returned by [**libssh2\_sftp\_open\_ex(3)**](/man/os/libssh2/libssh2_sftp_open_ex.3)

*attrs* - Pointer to an LIBSSH2\_SFTP\_ATTRIBUTES structure to set file metadata from or into depending on the value of setstat.

*setstat* - When non-zero, the file's metadata will be updated with the data found in attrs according to the values of attrs-&gt;flags and other relevant member attributes.

Get or Set statbuf type data for a given LIBSSH2\_SFTP\_HANDLE instance.

# [DATA TYPES](#DATA_TYPES)

LIBSSH2\_SFTP\_ATTRIBUTES is a typedefed struct that is defined as below

```
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 will find a full set of defines and macros to identify flags and permissions on the **libssh2\_sftp.h** header file, but some of the most common ones are:

To check for specific user permissions, the set of defines are in the pattern LIBSSH2\_SFTP\_S\_I&lt;action&gt;&lt;who&gt; where &lt;action&gt; is R, W or X for read, write and executable and &lt;who&gt; is USR, GRP and OTH for user, group and other. So, you check for a user readable file, use the bit *LIBSSH2\_SFTP\_S\_IRUSR* while you want to see if it is executable for other, you use *LIBSSH2\_SFTP\_S\_IXOTH* and so on.

To check for specific file types, you would previously (before libssh2 1.2.5) use 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](#LIBSSH2_SFTP_S_ISLNK)

Test for a symbolic link

[LIBSSH2\_SFTP\_S\_ISREG](#LIBSSH2_SFTP_S_ISREG)

Test for a regular file

[LIBSSH2\_SFTP\_S\_ISDIR](#LIBSSH2_SFTP_S_ISDIR)

Test for a directory

[LIBSSH2\_SFTP\_S\_ISCHR](#LIBSSH2_SFTP_S_ISCHR)

Test for a character special file

[LIBSSH2\_SFTP\_S\_ISBLK](#LIBSSH2_SFTP_S_ISBLK)

Test for a block special file

[LIBSSH2\_SFTP\_S\_ISFIFO](#LIBSSH2_SFTP_S_ISFIFO)

Test for a pipe or FIFO special file

[LIBSSH2\_SFTP\_S\_ISSOCK](#LIBSSH2_SFTP_S_ISSOCK)

Test for a socket

# [RETURN VALUE](#RETURN_VALUE)

Return 0 on success or negative on failure. It returns LIBSSH2\_ERROR\_EAGAIN when it would otherwise block. While LIBSSH2\_ERROR\_EAGAIN is a negative number, it is not really a failure per se.

# [ERRORS](#ERRORS)

*LIBSSH2\_ERROR\_ALLOC* - An internal memory allocation call failed.

*LIBSSH2\_ERROR\_SOCKET\_SEND* - Unable to send data on socket.

*LIBSSH2\_ERROR\_SOCKET\_TIMEOUT* -

*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](#AVAILABILITY)

This function has been around since forever, 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.

# [SEE ALSO](#SEE_ALSO)

[**libssh2\_sftp\_open\_ex(3)**](/man/os/libssh2/libssh2_sftp_open_ex.3)

1 Jun 2007 libssh2 0.15

---

Document: libssh2_sftp_fstat_ex(3) from libssh2 1.11.1-r10 (Chainguard OS)
Source: https://github.com/libssh2/libssh2.git