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

@@ -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 <libssh2.h>
 #include <libssh2_sftp.h>
 
 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<action><who> where <action> is R, W or X for
+read, write and excutable and <who> 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)

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