IOMMAPSTREAM(3bobcat)

📦
version 6.15.01 · 3 versions
, in ubuntu stonking

✨ NAME ✨

FBB::IOmmapStream — an Input Stream that uses mmap(2) through FBB::MmapBuf 💫

(hey bestie, this is the IOmmapStream page from the 3bobcat manual — come sit, it's actually so good)

🌸 SYNOPSIS 🌸

#include <bobcat/iommapstream>

Linking option: -lbobcat

💖 DESCRIPTION 💖

So like, FBB::IOmmapStream objects are what you use when you want to read from or write to files that get plopped right into the virtual address space of the calling process. The whole "living in your virtual address space" situation is handled by the class's privately inherited FBB::MmapBuf, which is a std::streambuf class. 💅

And the vibe? By mapping files into the process's virtual address space, the time it takes to process those files is usually dramatically reduced. it's giving speed. 🔥

Now for the part where you gotta be careful: an std::exception gets thrown, and an error message gets written to cerr, if the FBB::MmapBuf base class can't figure out the size of the file you specified, or when the (un)mapping can't be done. 😭 so like, handle your errors bestie.

🦋 NAMESPACE 🦋

FBB

Every single constructor, member, operator and manipulator mentioned in this man-page is defined in the namespace FBB.

👑 INHERITS FROM 👑

std::iostream, privately from FBB::MmapBuf.

🎀 CONSTRUCTORS 🎀

  • IOmmapStream() — the default constructor just constructs an empty IOmmapStream object, no thoughts, head empty. To actually turn it into something usable you use move assignment. ✨
  • IOmmapStream(std::string const &fname, char const *bufSize = 0, std::ios::openmode openMode = std::ios::out | std::ios::in, mode_t mode = 0644) — this constructor initializes the IOmmapStream object for a file named fname. 📂

The openMode parameter says how fname is used. The standard ios::in, ios::out, ios::trunc, ios::app, and ios::ate modes are supported. periodt.

By default, FBB::IOmmapStream uses a mapping buffer size of 10 times the standard page size (check sysconf(3), and the member pageSize below 👇). The size of the mapping buffer can also be set with the bufSize parameter. To specify it, use a value followed by K, M, or G, representing, respectively, 1024, 1024 * 1024, and 1024 * 1024 * 1024 bytes. The final buffer size is at least the standard page size. When you specify a larger value, the buffer size that actually gets used is set to specified / pageSize * pageSize.

The mode parameter specifies the user/group/other access mode that's used when the file is created by MmapBuf. Its default value means read/write access for the user, and read access for others. 🔐

Heads up bestie: the move constructor and move assignment operator are available. The copy constructor and copy assignment operator are not available. no copying, only moving. we love a class with boundaries 💅

🌈 MEMBER FUNCTIONS 🌈

All members of std::iostream are available, because FBB::IOmmapStream inherits from that class. slay.

  • size_t bufSize() const — returns the used (mmap) buffer's size 🧚
  • size_t fileSize() const — returns the current size of the file in use. The size gets updated to a larger size when you write beyond the current file size. And once the IOmmapStream object ceases to exist, the used file's size is modified to the current fileSize value. iconic.
  • size_t pageSize() const — returns the smallest page size used by (mmap) 📏

⭐ EXAMPLE ⭐

An example is provided in bobcat's source archive and gitlab repository at bobcat/iommapstream/demo. go look, it's right there 🫶

🍓 FILES 🍓

bobcat/iommapstream — defines the class interface ✨

💜 SEE ALSO 💜

bobcat(7), chmod(2), immapstream(3bobcat), mmap(2), mmapbuf(3bobcat), ommapstream(3bobcat), sysconf(3)

💀 BUGS 💀

None Reported. (we're so back, not a single bug to be found 🙈)

🌸 BOBCAT PROJECT FILES 🌸

Debian Bobcat project files:

  • libbobcat6 — debian package containing the shared library, changelog and copyright note;
  • libbobcat-dev — debian package containing the static library, headers, manual pages, and developer info;

👑 BOBCAT 👑

Bobcat is an acronym of Brokken's Own Base Classes And Templates. iykyk 💅

This is free software, distributed under the terms of the GNU General Public License (GPL). free as in free bestie 💖

💖 AUTHOR 💖

Frank B. Brokken (f.b.brokken@rug.nl). thank you king 👑

and that's the whole page bb! this one shipped in libbobcat-dev_6.15.01, dated 2005-2026 — go be the main character of your own mmap journey 🦋✨
📦 where this page comes from