.\" 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_min 3 2002-09-30 vrb "VRB Programmer's Manual"
.SH NAME
vrb_read_min - read a minimum of data into a VRB
.SH LIBRARY
.B -lvrb
.SH SYNOPSIS
.B #include <vrb.h>
.sp
.IB "size_t " "vrb_read_min" "(vrb_p " "vrb" ", int " "fd" ", size_t " "maxsize" ", size_t " "minsize" ");"
.SH DESCRIPTION
.B vrb_read_min
reads a minimum amount of 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).
If there is insufficient space in the buffer to read the minimum amount,
then
.B read(2)
will not be called.
.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 " maxsize
.br
specifies the maximum length to read, or
.B "~0"
for unlimited.
.sp
.IB "size_t " minsize
.br
specifies the minimum length to read.
.SH "RETURN VALUE"
.I size_t
.br
If successful, the actual length of data read into the buffer is returned.
If the minimum amount of space was not available to read into,
0 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).
.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 (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)