.\" Hey Emacs! This file is -*- nroff -*- source.
.\"
.\" Copyright © 2002 - Philip Howard - All rights reserved
.\"
.\" This program is free software; you can redistribute it and/or
.\" modify it under the terms of the GNU Lesser General Public
.\" License as published by the Free Software Foundation; either
.\" version 2.1 of the License, or (at your option) any later version.
.\"
.\" This library is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
.\" Lesser General Public License for more details.
.\"
.\" You should have received a copy of the GNU Lesser General Public
.\" License along with this library; if not, write to the Free Software
.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
.\"
.TH vrb_read 3 2002-09-30 vrb "VRB Programmer's Manual"
.SH NAME
vrb_read - read data into a VRB
.SH LIBRARY
.B -lvrb
.SH SYNOPSIS
.B #include <vrb.h>
.sp
.IB "size_t " "vrb_read" "(vrb_p " "vrb" ", int " "fd" ", size_t " "size" ");"
.SH DESCRIPTION
.B vrb_read
reads data from a specified open file descriptor using
.B read(2)
into the specified
virtual ring buffer until the specified maximum length has been read,
the buffer is full, or end-of-file, or an error is returned
(including EAGAIN or EWOULDBLOCK for a non-blocking descriptor).
.SH ARGUMENTS
.IB "vrb_p " vrb
.br
specifies which virtual ring buffer.
.sp
.IB "int " fd
.br
specifies the open file descriptor to read from
.sp
.IB "size_t " size
.br
specifies the maximum length to read, or
.B "~0"
for unlimited.
.SH "RETURN VALUE"
.I size_t
.br
If successful, the actual length of data read into the buffer is returned.
If end-of-file occurs, the return value is ~0 and errno is 0.
If an error occurs from
.B read(2),
the return value is ~0 and
errno is set by
.B read(2).
Note that this is a different way of returning an end-of-file
condition than
.B read(2)
uses.
.SH ERRORS
If an error is returned, then
.I errno
will have one of the following values:
.TP
.B 0
An end-of-file has occurred.
Note that this is a different way of returning an end-of-file
condition than
.B read(2)
uses.
.TP
.B EINVAL
An invalid virtual ring buffer pointer was specified.
.SH "SEE ALSO"
.BR vrb (3),
.BR vrb_capacity (3),
.BR vrb_data_len (3),
.BR vrb_data_ptr (3),
.BR vrb_destroy (3),
.BR vrb_get (3),
.BR vrb_get_min (3),
.BR vrb_give (3),
.BR vrb_init (3),
.BR vrb_init_opt (3),
.BR vrb_is_empty (3),
.BR vrb_is_full (3),
.BR vrb_is_not_empty (3),
.BR vrb_is_not_full (3),
.BR vrb_move (3),
.BR vrb_new (3),
.BR vrb_new_opt (3),
.BR vrb_put (3),
.BR vrb_put_all (3),
.BR vrb_read_min (3),
.BR vrb_resize (3),
.BR vrb_space_len (3),
.BR vrb_space_ptr (3),
.BR vrb_take (3),
.BR vrb_uninit (3),
.BR vrb_write (3),
.BR vrb_write_min (3),
.BR read(2)