.TH "FBB::OmmapStream" "3bobcat" "2005\-2024" "libbobcat\-dev_6\&.06\&.02" "std::istream using FBB::MmapBuf as streambuf"

.PP 
.SH "NAME"
FBB::OmmapStream \- Input Stream using mmap(2) through FBB::MmapBuf
.PP 
.SH "SYNOPSIS"
\fB#include <bobcat/ommapstream>\fP
.br 

.PP 
Linking option: \fI\-lbobcat\fP
.PP 
.SH "DESCRIPTION"
\fBFBB::OmmapStream\fP objects are used to write information to files which
are made available in the virtual address space of the calling process\&. Using
the virtual address space is handled by the class\(cq\&s privately inherited
\fBFBB::MmapBuf\fP (\fIstd::streambuf\fP class\&.
.PP 
By mapping files in the process\(cq\&s virtual address space the time required for
processing such files is usually dramatically reduced\&.
.PP 
An \fIstd::exception\fP is thrown, and an error message is written to \fIcerr\fP
if the \fBFBB::MmapBuf\fP base class cannot determine the size of the specified
file, or when the (un)mapping cannot be performed\&.
.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::ostream\fP, privately from \fBFBB::MmapBuf\fP\&.
.PP 
.SH "CONSTRUCTORS"
.IP o 
\fBOmmapStream()\fP:
.br 
The default constructor merely constructs an empty \fBOmmapStream\fP
object\&. To change it to a usable object use move assignment;
.PP 
.IP o 
\fBOmmapStream(std::string const &fname, char const *bufSize = 0,
std::ios::openmode openMode = std::ios::out, mode_t mode = 0644)\fP:
.br 
The constructor initializes the \fIOmmapStream\fP object for a file
named \fIfname\fP\&. 
.PP 
The \fIopenMode\fP parameter specifies how \fIfname\fP is used\&. The
standard \fIios::in, ios::out, ios::trunc, ios::app,\fP and \fIios::ate\fP modes
are supported\&.
.PP 
By default bfOmmapStream) uses a mapping buffer size of 10 times the standard
page size, (cf\&. \fBsysconf\fP(3), and the member \fIpageSize\fP below)\&. The size
of the mapping buffer can also be specified using the \fIbufSize\fP
parameter\&. To specify it use a value followed by \fIK, M,\fP or \fIG\fP,
representing, resp\&. 1024, 1024 * 1024, and 1024 * 1024 * 1024 bytes\&. The final
buffer size is at least equal to the standard page size\&. When a larger value
is specified the used buffer size is set to \fIspecified / pageSize *
pageSize\fP\&.
.PP 
The \fImode\fP parameter specifies the user/group/other access mode which is
used when the file is created by \fIMmapBuf\fP\&. Its default value specifies
read/write access by the user, and  read access by others\&.
)
.PP 
The move constructor and move assignment operator are available\&.
.br 
The copy constructor and copy assignment operator are not available\&.
.PP 
.SH "MEMBER FUNCTIONS"
All members of \fBstd::istream\fP are available, as \fBFBB::OmmapStream\fP
inherits from that class\&. 
.IP o 
\fBsize_t bufSize() const\fP:
.br 
returns the used t(mmap) buffer size;
.IP 
.IP o 
\fBsize_t fileSize() const\fP:
.br 
returns the current size of the used file\&. The size is updated to a
larger size when writing beyond the current file size\&. Once the
\fBOmmapStream\fP object ceases to exist the used file\(cq\&s size is modified to the
current \fIfileSize\fP value\&.
.IP 
.IP o 
\fBsize_t pageSize() const\fP:
.br 
returns the smallest page size used by t(mmap)\&.

.PP 
.SH "EXAMPLE"
An example is provided in bobcat\(cq\&s source archive and gitlab repository at
\fIbobcat/ommapstream/demo\fP\&. 
.PP 
.SH "FILES"
\fIbobcat/ommapstream\fP \- defines the class interface
.PP 
.SH "SEE ALSO"
\fBbobcat\fP(7), \fBchmod\fP(2), \fBimmapstream\fP(3bobcat),
\fBiommapstream\fP(3bobcat), \fBmmap\fP(2), \fBmmapbuf\fP(3bobcat)
\fBsysconf\fP(3)
.SH "BUGS"
None Reported\&.
.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