From bda32b6bbf889d6025a3b65b3bb77c2e949347a1 Mon Sep 17 00:00:00 2001
From: James Housley <jim@thehousleys.net>
Date: Sat, 21 Apr 2007 18:07:17 +0000
Subject: [PATCH] Document libssh2_sftp_readdir() and libssh2_sftp_readdirnb()

---
 docs/Makefile.am              |  5 +++--
 docs/libssh2_sftp_readdir.3   | 34 ++++++++++++++++++++++++++++++
 docs/libssh2_sftp_readdirnb.3 | 39 +++++++++++++++++++++++++++++++++++
 3 files changed, 76 insertions(+), 2 deletions(-)
 create mode 100644 docs/libssh2_sftp_readdir.3
 create mode 100644 docs/libssh2_sftp_readdirnb.3

diff --git a/docs/Makefile.am b/docs/Makefile.am
index 1cad2e78..6569fe0d 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -1,4 +1,4 @@
-# $Id: Makefile.am,v 1.3 2007/03/27 12:48:53 jas4711 Exp $
+# $Id: Makefile.am,v 1.4 2007/04/21 18:07:17 jehousley Exp $
 
 EXTRA_DIST = template.3
 
@@ -8,4 +8,5 @@ dist_man_MANS = libssh2_channel_forward_accept.3			\
  libssh2_sftp_init.3 libssh2_channel_readnb_ex.3			\
  libssh2_sftp_open_ex.3 libssh2_channel_set_blocking.3			\
  libssh2_session_free.3 libssh2_poll.3 libssh2_poll_channel_read.3	\
- libssh2_sftp_read.3 libssh2_sftp_readnb.3
+ libssh2_sftp_read.3 libssh2_sftp_readnb.3 libssh2_sftp_readdir.3	\
+ libssh2_sftp_readdirnb.3
diff --git a/docs/libssh2_sftp_readdir.3 b/docs/libssh2_sftp_readdir.3
new file mode 100644
index 00000000..6e0331d7
--- /dev/null
+++ b/docs/libssh2_sftp_readdir.3
@@ -0,0 +1,34 @@
+.\" $Id: libssh2_sftp_readdir.3,v 1.1 2007/04/21 18:07:17 jehousley Exp $
+.\"
+.TH libssh2_sftp_readdir 3 "16 Apr 2007" "libssh2 0.15" "libssh2 manual"
+.SH NAME
+libssh2_sftp_read - read data from an SFTP handle
+.SH SYNOPSIS
+#include <libssh2.h>
+
+int libssh2_sftp_readdir(LIBSSH2_SFTP_HANDLE *handle, char *buffer, 
+                         size_t buffer_maxlen, LIBSSH2_SFTP_ATTRIBUTES *attrs);
+
+.SH DESCRIPTION
+Read a block of data from a LIBSSH2_SFTP_HANDLE. This method is modeled 
+after the POSIX \fIreaddir(3)\fP however, it uses a variable sized directory 
+entry (filename) buffer and returns statbuf type data in the same call.
+
+\fIhandle\fP is the SFTP File Handle as returned by 
+\fIlibssh2_sftp_diropen(3)\fP.
+
+\fIbuffer\fP is a pointer to a pre-allocated buffer of at least
+\fIbuffer_maxlen\fP bytes to read data into.
+
+\fIbuffer_maxlen\fP is the length of buffer in bytes. If the length of the 
+filename is longer than the space provided by buffer_maxlen it will be 
+truncated to fit.
+
+\fIattrs\fP is a pointer to LIBSSH2_SFTP_ATTRIBUTES storage to populate 
+statbuf style data into.
+
+.SH RETURN VALUE
+Number of bytes actually populated into buffer, or -1 on failure.
+.SH "SEE ALSO"
+.BR libssh2_sftp_opendir(3)
+.BR libssh2_sftp_readdirnb(3)
diff --git a/docs/libssh2_sftp_readdirnb.3 b/docs/libssh2_sftp_readdirnb.3
new file mode 100644
index 00000000..ea94e522
--- /dev/null
+++ b/docs/libssh2_sftp_readdirnb.3
@@ -0,0 +1,39 @@
+.\" $Id: libssh2_sftp_readdirnb.3,v 1.1 2007/04/21 18:07:17 jehousley Exp $
+.\"
+.TH libssh2_sftp_readdir 3 "16 Apr 2007" "libssh2 0.15" "libssh2 manual"
+.SH NAME
+libssh2_sftp_readnb - read data from an SFTP handle non-blocking
+.SH SYNOPSIS
+#include <libssh2.h>
+
+int libssh2_sftp_readdirnb(LIBSSH2_SFTP_HANDLE *handle, char *buffer, 
+                         size_t buffer_maxlen, LIBSSH2_SFTP_ATTRIBUTES *attrs);
+
+.SH DESCRIPTION
+Read a block of data from a LIBSSH2_SFTP_HANDLE non-blocking. This method is 
+modeled after the POSIX \fIreaddir(3)\fP however, it uses a variable sized 
+directory entry (filename) buffer and returns statbuf type data in the same 
+call.
+
+\fIhandle\fP is the SFTP File Handle as returned by 
+\fIlibssh2_sftp_diropen(3)\fP.
+
+\fIbuffer\fP is a pointer to a pre-allocated buffer of at least
+\fIbuffer_maxlen\fP bytes to read data into.
+
+\fIbuffer_maxlen\fP is the length of buffer in bytes. If the length of the 
+filename is longer than the space provided by buffer_maxlen it will be 
+truncated to fit.
+
+\fIattrs\fP is a pointer to LIBSSH2_SFTP_ATTRIBUTES storage to populate 
+statbuf style data into.
+
+.SH RETURN VALUE
+Number of bytes actually populated into buffer, or negative on failure.  It
+returns LIBSSH2CHANNEL_EAGAIN when it would otherwise block. While
+LIBSSH2CHANNEL_EAGAIN is a negative number, it isn't really a failure per se.
+
+
+.SH "SEE ALSO"
+.BR libssh2_sftp_opendir(3)
+.BR libssh2_sftp_readdirnb(3)