From 2386a5a21c9e786a0dfbe1fb544cead619352445 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 11 Apr 2010 11:26:16 +0200 Subject: [PATCH] Added LIBSSH2_SFTP_S_IS***() macros and updated docs libssh2_sftp_fstat_ex.3 is now extended quite a lot to describe a lot of the struct and the bits it uses and how to test for them. --- docs/libssh2_sftp_fstat_ex.3 | 80 +++++++++++++++++++++++++++++++----- include/libssh2_sftp.h | 16 ++++++++ 2 files changed, 86 insertions(+), 10 deletions(-) diff --git a/docs/libssh2_sftp_fstat_ex.3 b/docs/libssh2_sftp_fstat_ex.3 index 28adb55..9dabbc0 100644 --- a/docs/libssh2_sftp_fstat_ex.3 +++ b/docs/libssh2_sftp_fstat_ex.3 @@ -2,32 +2,88 @@ .\" .TH libssh2_sftp_fstat_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" .SH NAME -libssh2_sftp_fstat_ex - get or set attributes on a file handle +libssh2_sftp_fstat_ex - get or set attributes on an SFTP file handle .SH SYNOPSIS +.nf #include #include int -libssh2_sftp_fstat_ex(LIBSSH2_SFTP_HANDLE *handle, LIBSSH2_SFTP_ATTRIBUTES *attrs, int setstat) - -int -libssh2_sftp_fstat(LIBSSH2_SFTP_HANDLE *handle, LIBSSH2_SFTP_ATTRIBUTES *attrs) - -int -libssh2_sftp_fsetstat(LIBSSH2_SFTP_HANDLE *handle, LIBSSH2_SFTP_ATTRIBUTES *attrs) +libssh2_sftp_fstat_ex(LIBSSH2_SFTP_HANDLE *handle, + LIBSSH2_SFTP_ATTRIBUTES *attrs, int setstat) +#define libbssh2_sftp_fstat(handle, attrs) \\ + libssh2_sftp_fstat_ex((handle), (attrs), 0) +#define libssh2_sftp_fsetstat(handle, attrs) \\ + libssh2_sftp_fstat_ex((handle), (attrs), 1) +.fi .SH DESCRIPTION \fIhandle\fP - SFTP File Handle as returned by .BR libssh2_sftp_open_ex(3) -\fIattrs\fP - Pointer to attribute structure to set file metadata -from or into depending on the value of setstat. +\fIattrs\fP - Pointer to an LIBSSH2_SFTP_ATTRIBUTES structure to set file +metadata from or into depending on the value of setstat. \fIsetstat\fP - When non-zero, the file's metadata will be updated with the data found in attrs according to the values of attrs->flags and other relevant member attributes. Get or Set statbuf type data for a given LIBSSH2_SFTP_HANDLE instance. +.SH DATA TYPES +LIBSSH2_SFTP_ATTRIBUTES is a typedefed struct that is defined as below + +.nf +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; +}; +.fi + +You will find a full set of defines and macros to identify flags and +permissions on the \fBlibssh2_sftp.h\fP header file, but some of the +most common ones are: + +To check for specific user permissons, the set of defines are in the +pattern LIBSSH2_SFTP_S_I where is R, W or X for +read, write and excutable and is USR, GRP and OTH for user, +group and other. So, you check for a user readable file, use the bit +\fILIBSSH2_SFTP_S_IRUSR\fP while you want to see if it is executable +for other, you use \fILIBSSH2_SFTP_S_IXOTH\fP 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: +.IP LIBSSH2_SFTP_S_ISLNK +Test for a symbolic link +.IP LIBSSH2_SFTP_S_ISREG +Test for a regular file +.IP LIBSSH2_SFTP_S_ISDIR +Test for a directory +.IP LIBSSH2_SFTP_S_ISCHR +Test for a character special file +.IP LIBSSH2_SFTP_S_ISBLK +Test for a block special file +.IP LIBSSH2_SFTP_S_ISFIFO +Test for a pipe or FIFO special file +.IP LIBSSH2_SFTP_S_ISSOCK +Test for a socket .SH RETURN VALUE Return 0 on success or negative on failure. It returns LIBSSH2_ERROR_EAGAIN when it would otherwise block. While @@ -42,5 +98,9 @@ LIBSSH2_ERROR_EAGAIN is a negative number, it isn't really a failure per se. \fILIBSSH2_ERROR_SFTP_PROTOCOL\fP - An invalid SFTP protocol response was received on the socket, or an SFTP operation caused an errorcode to be returned by the server. +.SH 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. .SH SEE ALSO .BR libssh2_sftp_open_ex(3) diff --git a/include/libssh2_sftp.h b/include/libssh2_sftp.h index 4cc5c2c..031533d 100644 --- a/include/libssh2_sftp.h +++ b/include/libssh2_sftp.h @@ -142,6 +142,22 @@ struct _LIBSSH2_SFTP_ATTRIBUTES { #define LIBSSH2_SFTP_S_IWOTH 0000002 /* W for other */ #define LIBSSH2_SFTP_S_IXOTH 0000001 /* X for other */ +/* macros to check for specific file types, added in 1.2.5 */ +#define LIBSSH2_SFTP_S_ISLNK(m) \ + (((m) & LIBSSH2_SFTP_S_IFMT) == LIBSSH2_SFTP_S_IFLNK) +#define LIBSSH2_SFTP_S_ISREG(m) \ + (((m) & LIBSSH2_SFTP_S_IFMT) == LIBSSH2_SFTP_S_IFREG) +#define LIBSSH2_SFTP_S_ISDIR(m) \ + (((m) & LIBSSH2_SFTP_S_IFMT) == LIBSSH2_SFTP_S_IFDIR) +#define LIBSSH2_SFTP_S_ISCHR(m) \ + (((m) & LIBSSH2_SFTP_S_IFMT) == LIBSSH2_SFTP_S_IFCHR) +#define LIBSSH2_SFTP_S_ISBLK(m) \ + (((m) & LIBSSH2_SFTP_S_IFMT) == LIBSSH2_SFTP_S_IFBLK) +#define LIBSSH2_SFTP_S_ISFIFO(m) \ + (((m) & LIBSSH2_SFTP_S_IFMT) == LIBSSH2_SFTP_S_IFIFO) +#define LIBSSH2_SFTP_S_ISSOCK(m) \ + (((m) & LIBSSH2_SFTP_S_IFMT) == LIBSSH2_SFTP_S_IFSOCK) + /* SFTP File Transfer Flags -- (e.g. flags parameter to sftp_open()) * Danger will robinson... APPEND doesn't have any effect on OpenSSH servers */ #define LIBSSH2_FXF_READ 0x00000001