.\" $Id: libssh2_sftp_readdir.3,v 1.10 2007/07/04 09:42:08 dottedmag Exp $
.\"
.TH libssh2_sftp_readdir_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual"
.SH NAME
libssh2_sftp_readdir_ex - read directory data from an SFTP handle
.SH SYNOPSIS
#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);

.SH DESCRIPTION
\fIhandle\fP - is the SFTP File Handle as returned by 
.BR libssh2_sftp_diropen(3)

\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.

\fIlongentry\fP - is a pointer to a pre-allocated buffer of at least
\fIlongentry_maxlen\fP bytes to read data into.

\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.

\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 \-1 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.

\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket.

\fILIBSSH2_ERROR_SOCKET_TIMEOUT\fP - 

\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 SEE ALSO
.BR libssh2_sftp_opendir(3)
.BR libssh2_sftp_closedir(3)