.\" $Id: libssh2_sftp_read.3,v 1.5 2007/06/08 13:33:08 jehousley Exp $
.\"
.TH libssh2_sftp_read 3 "6 Feb 2007" "libssh2 0.15" "libssh2 manual"
.SH NAME
libssh2_sftp_read - read data from an SFTP handle
.SH SYNOPSIS
#include <libssh2.h>
#include <libssh2_sftp.h>

ssize_t libssh2_sftp_read(LIBSSH2_SFTP_HANDLE *handle,
                          char *buffer, size_t buffer_maxlen);
.SH DESCRIPTION
Reads a block of data from an LIBSSH2_SFTP_HANDLE. This method is modelled
after the POSIX \Iread(3)\fP function and uses the same calling
semantics. \fIlibssh2_sftp_read(3)\fP will attempt to read as much as possible
however it may not fill all of buffer if the file pointer reaches the end or
if further reads would cause the socket to block.

\fIhandle\fP is the SFTP File Handle as returned by \fIlibssh2_sftp_open(3)\fP.

\fIbuffer\fP is a pointer to a pre-allocated buffer of at least
\fIbuffer_maxlen\fP bytes to read data into.
.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 "SEE ALSO"
.BR libssh2_sftp_open(3)
.BR libssh2_sftp_readnb(3)