libssh2/docs/libssh2_channel_read_ex.3

.\" $Id: libssh2_channel_read_ex.3,v 1.8 2007/06/13 12:50:35 jehousley Exp $
.\"
.TH libssh2_channel_read_ex 3 "1 June 2007" "libssh2 0.15" "libssh2 manual"
.SH NAME
libssh2_channel_read_ex - read data from a channel stream
.SH SYNOPSIS
#include <libssh2.h>

ssize_t
libssh2_channel_read_ex(LIBSSH2_CHANNEL *channel, int stream_id, char *buf, size_t buflen);

ssize_t
libssh2_channel_read(LIBSSH2_CHANNEL *channel, char *buf, size_t buflen);

ssize_t
libssh2_channel_read_stderr(LIBSSH2_CHANNEL *channel, char *buf, size_t buflen);

.SH DESCRIPTION
Attempt to read data from an active channel stream. All channel streams have
one standard I/O substream (stream_id == 0), and may have up to 2^32 extended
data streams as identified by the selected \fIstream_id\fP. The SSH2 protocol
currently defines a stream ID of 1 to be the stderr substream.

\fIchannel\fP - active channel stream to read from. 

\fIstream_id\fP - substream ID number (e.g. 0 or SSH_EXTENDED_DATA_STDERR) 

\fIbuf\fP - pointer to storage buffer to read data into

\fIbuflen\fP - size of the buf storage

\fIlibssh2_channel_read(3)\fP and \fIlibssh2_channel_read_stderr(3)\fP are
macros.
.SH RETURN VALUE
Actual number of bytes read 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_SOCKET_SEND\fP - Unable to send data on socket.

\fILIBSSH2_ERROR_CHANNEL_CLOSED\fP- The channel has been closed.

.SH SEE ALSO
.BR libssh2_poll_channel_read(3)
Update to reflect the current code and add possible error values 2007-06-13 16:50:35 +04:00			`.\" $Id: libssh2_channel_read_ex.3,v 1.8 2007/06/13 12:50:35 jehousley Exp $`
Added an initial set of man pages. 2006-12-21 17:09:12 +03:00			`.\"`
Modify the code to truely support non-blocking. Propogate the EAGAIN error all the way up to the user interface. All code modules bug sftp.c have been completed. Functions that return an "int", or similar return LIBSSH2CHANNEL_EAGAIN to indicate some part of the call would block, in non-blocking mode. Functions that return a structure, like "LIBSSH2_CHANNEL *", return NULL and set the libssh2 error. The error can be obtained with either libssh2_session_last_error() or libssh2_session_last_errno(). Either of these will return the error code of LIBSSH2_ERROR_EAGAIN if the call would block, in non-blocking mode. The current state of a function and some variable are keep in the structures so that on the next call the operation that would block can be retried again with the same data. 2007-06-06 16:34:06 +04:00			`.TH libssh2_channel_read_ex 3 "1 June 2007" "libssh2 0.15" "libssh2 manual"`
Added an initial set of man pages. 2006-12-21 17:09:12 +03:00			`.SH NAME`
			`libssh2_channel_read_ex - read data from a channel stream`
			`.SH SYNOPSIS`
			`#include <libssh2.h>`

Update to reflect the current code and add possible error values 2007-06-13 16:50:35 +04:00			`ssize_t`
			`libssh2_channel_read_ex(LIBSSH2_CHANNEL channel, int stream_id, char buf, size_t buflen);`
Added an initial set of man pages. 2006-12-21 17:09:12 +03:00
Update to reflect the current code and add possible error values 2007-06-13 16:50:35 +04:00			`ssize_t`
			`libssh2_channel_read(LIBSSH2_CHANNEL channel, char buf, size_t buflen);`

			`ssize_t`
			`libssh2_channel_read_stderr(LIBSSH2_CHANNEL channel, char buf, size_t buflen);`
Added an initial set of man pages. 2006-12-21 17:09:12 +03:00
			`.SH DESCRIPTION`
			`Attempt to read data from an active channel stream. All channel streams have`
			`one standard I/O substream (stream_id == 0), and may have up to 2^32 extended`
			`data streams as identified by the selected \fIstream_id\fP. The SSH2 protocol`
			`currently defines a stream ID of 1 to be the stderr substream.`

			`\fIchannel\fP - active channel stream to read from.`

			`\fIstream_id\fP - substream ID number (e.g. 0 or SSH_EXTENDED_DATA_STDERR)`

			`\fIbuf\fP - pointer to storage buffer to read data into`

			`\fIbuflen\fP - size of the buf storage`

			`\fIlibssh2_channel_read(3)\fP and \fIlibssh2_channel_read_stderr(3)\fP are`
			`macros.`
			`.SH RETURN VALUE`
Modify the code to truely support non-blocking. Propogate the EAGAIN error all the way up to the user interface. All code modules bug sftp.c have been completed. Functions that return an "int", or similar return LIBSSH2CHANNEL_EAGAIN to indicate some part of the call would block, in non-blocking mode. Functions that return a structure, like "LIBSSH2_CHANNEL *", return NULL and set the libssh2 error. The error can be obtained with either libssh2_session_last_error() or libssh2_session_last_errno(). Either of these will return the error code of LIBSSH2_ERROR_EAGAIN if the call would block, in non-blocking mode. The current state of a function and some variable are keep in the structures so that on the next call the operation that would block can be retried again with the same data. 2007-06-06 16:34:06 +04:00			`Actual number of bytes read or negative on failure. It returns`
To simplify the user's error interface always use LIBSSH2_ERROR_EAGAIN. LIBSSH2CHANNEL_EAGAIN and LIBSSH2SFTP_EAGAIN are still valid, but are defined as LIBSSH2_ERROR_EAGAIN. 2007-06-08 17:33:08 +04:00			`LIBSSH2_ERROR_EAGAIN when it would otherwise block. While`
			`LIBSSH2_ERROR_EAGAIN is a negative number, it isn't really a failure per se.`
Update to reflect the current code and add possible error values 2007-06-13 16:50:35 +04:00			`.SH ERRORS`
			`\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket.`

			`\fILIBSSH2_ERROR_CHANNEL_CLOSED\fP- The channel has been closed.`

			`.SH SEE ALSO`
more/updated man pages 2007-02-23 13:20:56 +03:00			`.BR libssh2_poll_channel_read(3)`