--- name: "logbuf" section: "3bobcat" platform: "linux" package: "libbobcat-dev" version: "6.07.01-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/logbuf" --- # logbuf(3bobcat) std::streambuf handling log messages ## NAME FBB::LogBuf - **std::streambuf** handling log messages ## SYNOPSIS **#include \**\ Linking option: *-lbobcat* ## DESCRIPTION **FBB::LogBuf** is a class derived from **std::streambuf** handling log messages. The stream to log to, timestamps and log-levels can be configured both at construction time and beyond. The **FBB::LogBuf** may be used to initialize a **std::ostream**. ## NAMESPACE **FBB**\ All constructors, members, operators and manipulators, mentioned in this man-page, are defined in the namespace **FBB**. ## INHERITS FROM **std::streambuf** ## ENUMERATIONS The enumeration **TimeStamps** is defined in the namespace **FBB** to be used when initializing **FBB::LogBuf** objects. It has the following values: - o **NOTIMESTAMPS**:\ Log-messages will not have timestamps prepended to them. - o **TIMESTAMPS**:\ Log-messages will have timestamps prepended to them. - o **UTCTIMESTAMPS**:\ Log-messages will have timestamps showing the UTC time prepended to them. The enumeration *Active* is used to distinguish between suspending message insertion when a message’s level does not exceed a minimum level and suspending all message insertions (e.g., when suspending inserting messages into **FBB::Log** objects after calling their *off* member): - o **OFF**:\ All insertions into the *LogBuf* object are suspended; - o **NOT\_ACTIVE**:\ Insertions of messages into the *LogBuf* object are suspended if their levels are less than the a specified minimum (as set by, e.g., *Log::setLevel*). - o **ACTIVE**:\ Messages are inserted ## CONSTRUCTORS - o **LogBuf(TimeStamps timestamps = TIMESTAMPS,** **bool active = true,** **char const \*delim = " ")**:\ This constructor constructs an **FBB::LogBuf** object writing its log-messages to **std::cerr**. If the **active** parameter is initialized to **false** no messages will be logged until the buffer’s activity is switched on (see **setActive()** below). The parameter **delim** is inserted immediately beyond the time stamp. If a delimiter is inappropriate, an empty string or a 0-pointer may be specified. When **stamps == FBB::NOTIMESTAMPS** **delim** is ignored. A time stamp consists of the month, the day number of the month and the (local) time of the current message, as usually appearing in messages in */var/log* files. E.g., *Aug 5 13:52:23*; - - o **LogBuf(std::ostream &stream,** **TimeStamps timestamps = TIMESTAMPS,** **bool active = true,** **char const \*delim = " ")**:\ This constructor constructs an **FBB::LogBuf** object writing its log-messages to the stream used to initialize its **stream** parameter. If the **active** parameter is initialized to **false** no messages will be logged until the buffer’s activity is switched on (see **setActive()** below). The parameter **delim** is inserted immediately beyond the time stamp. If a delimiter is inappropriate, an empty string or a 0-pointer may be specified. When **stamps == FBB::NOTIMESTAMPS delim** is ignored. A time stamp consists of the month, the day number of the month and the (local) time of the current message, as usually appearing in messages in */var/log* files. E.g., *Aug 5 13:52:23*. Copy and move constructors (and assignment operators) are not available. ## PUBLIC MEMBER FUNCTIONS All members of **std::streambuf** are available, as **FBB::LogBuf** inherits from this class. - o **bool active() const**:\ Returns *true* if log-messages are currently processed; - - o **bool empty() const**:\ Returns *true* if the object’s buffer is currently empty (initially or after a newline character has been inserted); - - o **void setStream(std::ostream &stream)**:\ This member may be used to switch the stream to log to. It is the responsibility of the programmer to ensure that the external stream remains available for as long as log-messages are inserted into it; - - o **void settimestamp(FBB::TimeStamps timestamps,** **char const \*delim = " ")**:\ The member function (de)activates time stamp prepending. Use the value **FBB::TIMESTAMPS** to prepend time stamps, **FBB::NOTIMESTAMPS** suppresses time stamps. A time stamp consists of the month, the day number of the month and the (local) time of the current message, as usually appearing in messages in */var/log* files. E.g., *Aug 5 13:52:23*. The parameter **delim** is inserted immediately beyond the time stamp. If a delimiter is inappropriate, an empty string or a 0-pointer may be specified. When **stamps ==** **FBB::NOTIMESTAMPS delim** is ignored; - - o **void setActive(bool active)**:\ Unless the current object’s *Active* state is *OFF* this member can be used to (de)activate logging. The argument **true** activates logging, the argument **false** deactivates it. If the current *Active* status is *OFF* then this member does not change the object’s activity status. This member is normally called by **FBB::Log::level** members; - - o **void setActive(Active active)**:\ The member function (de)activates logging. The argument **ACTIVE** activates logging, the argument **OFF** completely suppresses logging, the argument *NOT\_ACTIVE* also suppresses logging, but here *setActive(true)* can also be used reactivate logging; - - o **void setEmpty(bool empty)**:\ This member may be called to ensure that a timestamp is inserted before the next insertion. It is called as **setEmpty(true)** when a newline character (*\\n*) is inserted, ensuring that another timestamp is prepended before the next insertion. ## EXAMPLE ``` #include #include #include #include using namespace std; using namespace FBB; int main() { LogBuf buffer(cout, FBB::TIMESTAMPS); ostream log(&buffer); log << "This message is written to cout" << nl << setw(16) << ’ ’ << "occupying multiple lines\n"; buffer.setActive(false); log << "one line\n"; log << "more lines "; log << fnl; log << "another\n"; buffer.setActive(true); log << "and active again\n"; log << "another log msg\n"; } ``` ## FILES *bobcat/logbuf* - defines the class interface ## SEE ALSO [**bobcat**(7)](/bobcat/7.md), [**log**(3bobcat)](/log/3bobcat.md) ## BUGS None Reported. ## BOBCAT PROJECT FILES - o *https://fbb-git.gitlab.io/bobcat/*: gitlab project page; Debian Bobcat project files: - o *libbobcat6*: debian package containing the shared library, changelog and copyright note; - o *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’. ## COPYRIGHT This is free software, distributed under the terms of the GNU General Public License (GPL). ## AUTHOR Frank B. Brokken (**f.b.brokken@rug.nl**).