.TH "FBB::MmapBuf" "3bobcat" "2005\-2024" "libbobcat\-dev_6\&.06\&.02" "std::streambuf using mmap(2)"

.PP 
.SH "NAME"
FBB::MmapBuf \- a std::streambuf using mmap(2) for file I/O
.PP 
.SH "SYNOPSIS"
\fB#include <bobcat/mmapbuf>\fP
.br 

.PP 
Linking option: \fI\-lbobcat\fP
.PP 
.SH "DESCRIPTION"
The \fBmmap\fP(2) functions map files in the virtual address space of the
calling process\&. Using \fImmap\fP in \fBC++\fP is doable, but complex\&. The
\fBMmapBuf\fP \fIstd::streambuf\fP class embeds the features of \fBmmap\fP(2),
allowing the use of \fBC++\fP\(cq\&s streams instead of using the raw \fImmap\fP
calls\&. the \fBFBB::Mmapbase\fP class defines a \fIstd::streambuf\fP which can be
used by \fIistream, ostream,\fP and \fIiostream\fP objects\&.
.PP 
An \fIstd::exception\fP is thrown, and an error message is written to \fIcerr\fP
if the details about the specified filename (cf\&. section \fBCONSTRUCORS\fP
cannot be determined, or when \fImmap\fP or \fImunmap\fP return errors\&.
.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 "CONSTRUCTORS"
.IP o 
\fBMmapBuf()\fP:
.br 
The default constructor merely constructs an empty \fBMmapBuf\fP
object\&. To change it to a usable object use move assignment;
.IP 
.IP o 
\fBMmapBuf(std::string const &fname, 
std::ios::openmode openMode,
char const *bufSize = 0, mode_t mode = 0644)\fP:
.br 
The constructor initializes the \fIMmapBuf\fP object for a file named
\fIfname\fP\&. The \fIopenmode\fP can be any combination of the
\fIstd::ios::openmode\fP values\&. The required values are usually provided when
constructing \fIImapStream, OmapStream,\fP or \fIIOmapStream\fP objects
(cf\&. section \fBSEE ALSO\fP below)\&.
.IP 
The \fIopnemMode\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\&.
.IP 
By default bfMmapBuf 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::stringstream\fP are available, as \fBFBB::MmapBuf\fP
inherits from that class\&.
.PP 
.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 size of the used file\&. The size is updated to a larger
size when writing beyond the current file size\&. Once \fBMmapBuf\fP objects
cease to exist the used file\(cq\&s size is modified to the current \fIfileSize\fP
value\&. The size of a file that can only be read is never altered\&.
.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/mmapbuf/demo\fP\&.
.PP 
.SH "FILES"
\fIbobcat/mmapbuf\fP \- defines the class interface
.PP 
.SH "SEE ALSO"
\fBbobcat\fP(7), \fBchmod\fP(2), \fBimmapstream\fP(3bobcat),
\fBiommapstream\fP(3bobcat), \fBommapstream\fP(3bobcat), \fBmmap\fP(2),
\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;
.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