.TH "FBB::IOmmapStream" "3bobcat" "2005\-2025" "libbobcat\-dev_6\&.07\&.01" "std::istream using FBB::MmapBuf as streambuf"

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

.PP 
Linking option: \fI\-lbobcat\fP
.PP 
.SH "DESCRIPTION"
\fBFBB::IOmmapStream\fP objects are used for reading or writing 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::iostream\fP, privately from \fBFBB::MmapBuf\fP\&.
.PP 
.SH "CONSTRUCTORS"
.IP o 
\fBIOmmapStream()\fP:
.br 
The default constructor merely constructs an empty \fBIOmmapStream\fP
object\&. To change it to a usable object use move assignment;
.PP 
.IP o 
\fBIOmmapStream(std::string const &fname, char const *bufSize = 0,
std::ios::openmode openMode = std::ios::out | std::ios::in, 
mode_t mode = 0644)\fP:
.br 
The constructor initializes the \fIIOmmapStream\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 bfIOmmapStream) 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::IOmmapStream\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
\fBIOmmapStream\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/iommapstream/demo\fP\&. 
.PP 
.SH "FILES"
\fIbobcat/iommapstream\fP \- defines the class interface
.PP 
.SH "SEE ALSO"
\fBbobcat\fP(7), \fBchmod\fP(2), \fBimmapstream\fP(3bobcat), \fBmmap\fP(2),
\fBmmapbuf\fP(3bobcat), \fBommapstream\fP(3bobcat), \fBsysconf\fP(3)
.PP 
.SH "BUGS"
None Reported\&.
.PP 
.SH "BOBCAT PROJECT FILES"

.PP 
.IP o 
\fIhttps://fbb\-git\&.gitlab\&.io/bobcat/\fP: gitlab project page;

.PP 
Debian Bobcat project files:
.PP 
.IP o 
\fIlibbobcat6\fP: debian package containing the shared library, changelog
and copyright note;
.IP o 
\fIlibbobcat\-dev\fP: debian package containing the
static library, headers, manual pages, and developer info;

.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