.TH "FBB::IFdBuf" "3bobcat" "2005\-2024" "libbobcat\-dev_6\&.06\&.02" "File Descriptor Input Stream Buffer"

.PP 
.SH "NAME"
FBB::IFdBuf \- Input stream buffer initialized by a file descriptor
.PP 
.SH "SYNOPSIS"
\fB#include <bobcat/ifdbuf>\fP (when using \fBFBB::IFdBuf\fP
.br 
\fB#include <bobcat/ifdbufs>\fP (when using \fBFBB::IFdBufS\fP
.PP 
Linking option: \fI\-lbobcat\fP
.PP 
.SH "DESCRIPTION"
\fBFBB::IFdBuf\fP objects may be used as a \fIstd::streambuf\fP of
\fIstd::istream\fP objects to allow extractions from a file descriptor\&.
.PP 
\fBFBB::IFdBufS\fP objects operate like \fBFBB::IFdBuf\fP objects but use
\fBFBB::Selector\fP objects to check whether information on the object\(cq\&s file
descriptor is available before reading information from the file descriptor\&.
.PP 
File descriptors are not defined within the context of \fBC++\fP,
but they can be used on operating systems that support the concept\&. Realize
that using file descriptors introduces operating system dependencies\&.
.PP 
.SH "NAMESPACE"
\fBFBB\fP
.br 
All constructors, members, operators and manipulators, mentioned in this
man\-page, are defined in the namespace \fBFBB\fP\&.
.PP 
.SH "INHERITS FROM"
\fBstd::streambuf\fP
.PP 
.SH "ENUMERATION"
The public enumeration \fIMode\fP defined in the class \fIFBB::IFdStreamBuf\fP
has the following values:
.IP o 
\fBCLOSE_FD\fP, indicating that the file descriptor used by the object
must be closed;
.IP o 
\fBKEEP_FD\fP (the default) indicating that the file descriptor used by
the object must not be closed\&.

.PP 
.SH "CONSTRUCTORS"
.IP o 
\fBIFdBuf()\fP:
.br 
This constructor initializes the streambuf, without associating it to
a file descriptor, and without using buffering\&. The member \fIreset\fP can be
used subsequently to associate the object with a file descriptor and
optionally a buffer size\&. When the object is destroyed or if the mode\-less
overloaded version of the \fIreset\fP member is called, the file descriptor is
not closed\&.
.IP 
.IP o 
\fBIFdBuf(Mode mode)\fP:
.br 
This constructor initializes the streambuf, without associating it to
a file descriptor, and without using buffering\&. The member \fIreset\fP can be
used subsequently to associate the object with a file descriptor and
optionally a buffer size\&. When the object is destroyed or if the mode\-less
overloaded version of the member \fIreset\fP is called, the \fIMode\fP argument
determines whether the file descriptor will be closed or will remain open\&.
.IP 
.IP o 
\fBIFdBuf(int fd, size_t n = 1)\fP:
.br 
This constructor initializes the streambuf, associating it to file
descriptor \fIfd\fP, and an optional unget buffer size (by default having size
1)\&.  When the object is destroyed or if the mode\-less overloaded version of
the member \fIreset\fP is called, the file descriptor is not closed\&.
.IP 
.IP o 
\fBIFdBuf(int fd, Mode mode, size_t n = 1)\fP:
.br 
This constructor initializes the streambuf, associating it to file
descriptor \fIfd\fP, and an optional unget buffer size (by default having size
1)\&.   When the object is destroyed or if the mode\-less
overloaded version of the \fIreset\fP member is called, the \fIMode\fP argument
determines whether the file descriptor will be closed or will remain open\&.
.IP 
.IP o 
\fBIFdBufS constructors\fP:
.br 
Use \fBIFdBufS\fP constructors corresponding to \fBIFdBuf\fP constructors
to construct the corresponding \fBIFdBufS\fP objects\&.

.PP 
Copy and move constructors (and assignment operators) are not available\&.
.PP 
.SH "MEMBER FUNCTIONS"
All members of \fIstd::streambuf\fP are
available, as \fIFBB::IFdBuf(S)\fP inherits from this class\&.
.PP 
.IP o 
\fBvoid close()\fP:
.br 
The file descriptor used by the \fIIFdBuf(S)\fP is closed,
irrespective of the \fIMode\fP that was specified when the \fIIFdBuf(S)\fP
object was constructed\&. Following \fIclose\fP the \fIIFdBuf(S)\fP object can
no longer be used until one of its \fIreset\fP members has been called\&.
.IP 
.IP o 
\fBint fd() const\fP:
.br 
The file descriptor used by the \fIIFdBuf(S)\fP object is returned\&.
If the \fIOFdBuf\fP is not associated with a file descriptor \-1 is
returned\&.
.IP 
.IP o 
\fBvoid reset(int fd, size_t n = 1)\fP:
.br 
The streambuf is (re)initialized, using file descriptor \fIfd\fP, and an
optional unget buffer size (by default having size 1)\&. When called repeatedly,
the \fIMode\fP specification used whem the object was constructed determines
whether the file descriptor will be closed or will remain open\&.
.IP 
.IP o 
\fBvoid reset(int fd, Mode mode, size_t n = 1)\fP:
.br 
The streambuf is (re)initialized, using file descriptor \fIfd\fP, a file
descriptor closing parameter and an optional unget buffer size (by default
having size 1)\&. Depending on the \fIMode\fP argument the object\(cq\&s currently used
file descriptor will be closed or will remain open when the \fIIFdBuf(S)\fP
object is destroyed\&.

.PP 
.SH "EXAMPLE"

.PP 
.nf 
#include <unistd\&.h>

#include <istream>
#include <iostream>

#include <bobcat/ifdbuf>

using namespace std;
using namespace FBB;

int main(int argc, char **argv)
{
                           // define a streambuf of 20 or argv[1] characters
    IFdBuf buf{ STDIN_FILENO, argc == 1 ? 20 : stoul(argv[1]) };

    istream in{ &buf };

    cout << in\&.rdbuf();
}

.fi 

.PP 
.SH "FILES"
\fIbobcat/ifdbuf\fP \- defines the \fBFBB::IFdBuf\fP class interface
.br 
\fIbobcat/ifdbufs\fP \- defines the \fBFBB::IFdBufS\fP class interface
.PP 
.SH "SEE ALSO"
\fBbobcat\fP(7), \fBifdstream\fP(3bobcat), \fBofdbuf\fP(3bobcat),
\fBstd::streambuf\fP
.PP 
.SH "BUGS"
The member \fIxsgetn(char *dest, std::streamsize n)\fP sets
\fIistream::good()\fP to \fIfalse\fP when fewer bytes than \fIn\fP were read using
\fIistream::read()\fP\&. Also see \fIxsgetn\fP\(cq\&s description\&.
.PP 
Note that by default the provided file descriptors remain open\&. The
complementary class \fBofdbuf\fP(3bobcat) by default \fIcloses\fP the file
descriptor\&.
.PP 
.SH "BOBCAT PROJECT FILES"

.PP 
.IP o 
\fIhttps://fbb\-git\&.gitlab\&.io/bobcat/\fP: gitlab project page;
.IP o 
\fIbobcat_6\&.06\&.02\-x\&.dsc\fP: detached signature;
.IP o 
\fIbobcat_6\&.06\&.02\-x\&.tar\&.gz\fP: source archive;
.IP o 
\fIbobcat_6\&.06\&.02\-x_i386\&.changes\fP: change log;
.IP o 
\fIlibbobcat1_6\&.06\&.02\-x_*\&.deb\fP: debian package containing the
libraries;
.IP o 
\fIlibbobcat1\-dev_6\&.06\&.02\-x_*\&.deb\fP: debian package containing the
libraries, headers and manual pages;

.PP 
.SH "BOBCAT"
Bobcat is an acronym of `Brokken\(cq\&s Own Base Classes And Templates\(cq\&\&.
.PP 
.SH "COPYRIGHT"
This is free software, distributed under the terms of the
GNU General Public License (GPL)\&.
.PP 
.SH "AUTHOR"
Frank B\&. Brokken (\fBf\&.b\&.brokken@rug\&.nl\fP)\&.
.PP