FBB::MemoryBuf(3bobcat)

📦
version 6.15.01 · 2 versions
, in ubuntu stonking

✨ FBB::MemoryBuf ✨

okay bestie, this is a page from the bobcat manual set — section 3bobcat, if you're keeping score 💅 — and it's literally all about FBB::MemoryBuf, a streambuf that talks to memory segments. buckle up 🎀

💖 NAME 💖

FBB::MemoryBuf — a streambuf that interfaces to memory segments. it's giving glambassador between your stream and a chunk of shared memory ✨

🌸 SYNOPSIS 🌸

#include <bobcat/memorybuf>
Linking option: -lbobcat

no cap, that's the whole vibe right there 🦋

🫶 DESCRIPTION 🫶

MemoryBuf implements a specialization of the std::streambuf class — which means stream classes like std::iostream and FBB::MemoryStream get to do I/O operations on memory segments (cf. shmget(2)). iconic behavior honestly.

FBB::MemoryBuf provides the streambufs of FBB::MemoryStream objects using a FBB::MemoryBridge object that interfaces to the shared memory blocks read and written by a FBB::MemoryBuf object. so it's like… the middle bestie. the group chat admin. the one holding it all together 💜

👑 NAMESPACE 👑

FBB

every single constructor, member, operator and manipulator mentioned on this page is defined in the namespace FBB. periodt.

🦋 INHERITS FROM 🦋

std::streambuf.

classic inheritance moment. it's giving legacy. 💅

🎀 CONSTRUCTORS 🎀

  • MemoryBuf() — the default constructor defines a stub MemoryBuf object, and lowkey you can't just immediately use it to access memory segments. in practice, usable FBB::MemoryBuf objects come from one of the constructors below. so this one is more of a placeholder bestie 🙈
  • MemoryBuf(std::string const &bufSize, [bool erase = false,] std::ios::openmode openMode = std::ios::in | std::ios::out, size_t access = 0600) — constructs a MemoryBuf object. its default capacity is specified by bufSize (cf. the section BUFSIZE below), using memory segment(s) that contain the stream's bytes.

the access rights of the data stored in MemoryStream objects are defined by the access parameter, interpreted as an octal value, using the same specifications that chmod(1) uses.

the erase parameter decides what happens to the memory segments once the MemoryBuf object goes out of scope. when it's omitted or specified as false, the allocated memory segments are not erased from memory when the object goes out of scope — and yes, they can be reaccessed using the memory object's ID (see the next constructor) right up until the computer is rebooted. when it's specified as true, the memory segments are erased from memory when the object goes out of scope.

if construction fails, an FBB::Exception is thrown. okay? 😭
  • MemoryBuf(int id, [bool erase,] std::ios::openmode openMode = std::ios::in | std::ios::out) — this constructor connects to a memory segment having ID id.

the erase parameter works exactly like it does in the previous constructor.

specifying the ios::trunc flag (or a comparable flag, like merely ios::out) immediately clears the current content of the memory segments. so watch out, bestie 💀

an FBB::Exception is thrown if construction fails (e.g., when no memory segment having ID id exists).

the move constructor and the move assignment operator are available. the copy constructor and the copy assignment operator are not available. no copies bestie, only moves 💅✨

🌈 BUFSIZE 🌈

the bufSize parameter required by the second MemoryStream constructor and by the open member (see below) specifies the default number of shared memory blocks and their sizes.

the size of the memory blocks is specified as k, M or G, indicating block sizes in kilo-, Mega- and GigaBytes. before those letters you put the default number of blocks. e.g., "100M".

internally, the number of kiloBytes is converted to pages, using the system's page size, which is commonly equal to 4 kB (so when you specify "5k" the stream prepares for two shared data segments, each having a capacity of 4 kB). the number of MegaBytes is used as specified, and when specifying GB the data segments are .5 GB.

the number of shared data segments is automatically enlarged when the current capacity is exceeded, and the potentially available data segments are initially not allocated — they get allocated once information is written into their areas. lazy allocation rights ✨

💜 MEMBER FUNCTIONS 💜

all members of std::streambuf are available. everything. the whole menu 🍓

  • int id() const — returns the ID of the memory segments.
  • void info(std::ostream &out) — inserts information about the MemoryBridge into out: the IDs of the memory data blocks, their sizes, the current maximum number of memory data blocks, the number of bytes that can be read from the memory segments, and its actual storage capacity. it's giving full dossier 📋
  • std::streamsize maxEnd() const — when using a MemoryBuf object, the offset just beyond the current maximum offset is returned. e.g., if a MemoryBuf object is configured with 5 data blocks of 1 MB each, then maxEnd returns 5 * 1024 * 1024. when the object extends its number of data blocks, maxEnd returns the corresponding new value.
  • void setErase(bool erase) — used to change the erase setting of a MemoryBuf object. it can be used by, e.g., forking programs where the program constructs a MemoryBuf object specifying erase == false, but whose memory segments should be erased when the parent process ends and not also when the child process ends. this is accomplished by calling setErase(true) in the parent process. parent gets the final say, as she should 💅
  • void truncate(std::streamsize size) — used to reduce or enlarge the available memory size of a MemoryBuf object to size. if it's reduced then the memory segments' data bytes from size to its original size are set to 0: newly allocated memory segments are always initialized to 0 byte values. clean slate energy 🧚
  • std::streamsize writtenUntil() const — returns the highest ever byte-offset where a value was written. the record holder 🏆

⭐ EXAMPLE ⭐

see the memorystream(3bobcat) man page. (yes, it's over there. go look 👀)

🎀 FILES 🎀

  • bobcat/memorybuf — defines the class interface

🔥 SEE ALSO 🔥

bobcat(7), chmod(1), memorybridge(3bobcat), memoryreadme(7bobcat), memorystream(3bobcat), shmget(2),

the whole friend group, fr fr 🫶

💀 BUGS 💀

note that by default exceptions thrown from within a std::stream object are caught by the stream object itself, setting its ios::failbit flag. so the stream is out here catching feelings and exceptions 🙈

to allow exceptions to leave a stream object, its exceptions member can be called, e.g., using:

myStream.exceptions(ios::failbit | ios::badbit | ios::eofbit);

do that or your exception is never leaving the group chat. iykyk 💅

🌈 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''. cute and clever, we love a backronym 💖

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

🦋 AUTHOR 🦋

Frank B. Brokken (f.b.brokken@rug.nl). the icon, the legend, the author of the whole era 👑

that's the whole page, no details left behind, no options skipped, no vibe compromised 💖 this was libbobcat-dev_6.15.01, dated 2005-2026 — so it's been slaying for two decades and counting, periodt ✨🎀

📦 where this page comes from