sftp_readdir: always zero terminate, detail the return code

I also added a description for the 'longentry' field which was
previously undocumented!

docs/libssh2_sftp_readdir_ex.3

@@ -4,16 +4,22 @@
 .SH NAME
 libssh2_sftp_readdir_ex - read directory data from an SFTP handle
 .SH SYNOPSIS
+.nf
 #include <libssh2.h>
 #include <libssh2_sftp.h>
 
 int 
-libssh2_sftp_readdir_ex(LIBSSH2_SFTP_HANDLE *handle, char *buffer, size_t buffer_maxlen, char *longentry, size_t longentry_maxlen, LIBSSH2_SFTP_ATTRIBUTES *attrs);
-
-int 
-libssh2_sftp_readdir(LIBSSH2_SFTP_HANDLE *handle, char *buffer, size_t buffer_maxlen, LIBSSH2_SFTP_ATTRIBUTES *attrs);
+libssh2_sftp_readdir_ex(LIBSSH2_SFTP_HANDLE *handle,
+                        char *buffer, size_t buffer_maxlen,
+                        char *longentry, size_t longentry_maxlen,
+                        LIBSSH2_SFTP_ATTRIBUTES *attrs);
 
+#define libssh2_sftp_readdir(h, b, bl, a)      \\
+    libssh2_sftp_readdir_ex((h), (b), (bl), NULL, 0, (a))
 .SH DESCRIPTION
+Reads a block of data from a LIBSSH2_SFTP_HANDLE and returns file entry
+information for the next entry, if any.
+
 \fIhandle\fP - is the SFTP File Handle as returned by 
 .BR libssh2_sftp_open_ex(3)
 
@@ -25,25 +31,22 @@ filename is longer than the space provided by buffer_maxlen it will be
 truncated to fit.
 
 \fIlongentry\fP - is a pointer to a pre-allocated buffer of at least
-\fIlongentry_maxlen\fP bytes to read data into.
+\fIlongentry_maxlen\fP bytes to read data into. The format of the `longname'
+field is unspecified by SFTP protocol. It MUST be suitable for use in the
+output of a directory listing command (in fact, the recommended operation for
+a directory listing command is to simply display this data).
 
-\fIlongentry_maxlen\fP - is the length of longentry in bytes. If the length 
-of the full directory entry is longer than the space provided by 
-longentry_maxlen it will be truncated to fit.
+\fIlongentry_maxlen\fP - is the length of longentry in bytes. If the length of
+the full directory entry is longer than the space provided by
+\fIlongentry_maxlen\fP it will be truncated to fit.
 
 \fIattrs\fP - is a pointer to LIBSSH2_SFTP_ATTRIBUTES storage to populate 
 statbuf style data into.
-
-Read a block of data from a LIBSSH2_SFTP_HANDLE. This method is modeled 
-after the POSIX 
-.BR readdir(2)
-however, it uses a variable sized directory entry (filename) buffer and 
-returns statbuf type data in the same call.
-
 .SH RETURN VALUE
-Number of bytes actually populated into buffer, or negative on failure.  It
-returns LIBSSH2_ERROR_EAGAIN when it would otherwise block. While
-LIBSSH2_ERROR_EAGAIN is a negative number, it isn't really a failure per se.
+Number of bytes actually populated into buffer (not counting the terminating
+zero), or negative on failure.  It returns LIBSSH2_ERROR_EAGAIN when it would
+otherwise block. While LIBSSH2_ERROR_EAGAIN is a negative number, it isn't
+really a failure per se.
 .SH ERRORS
 \fILIBSSH2_ERROR_ALLOC\fP -  An internal memory allocation call failed.