.TH "FBB::SyslogStream" "3bobcat" "2005\-2020" "libbobcat\-dev_5\&.07\&.00" "Output Stream for Syslog"

.PP 
.SH "NAME"
FBB::SyslogStream \- An output stream inserting syslog messages
.PP 
.SH "SYNOPSIS"
\fB#include <bobcat/syslogstream>\fP
.br 
Linking option: \fI\-lbobcat\fP 
.PP 
.SH "DESCRIPTION"
\fBFBB::SyslogStream\fP objects may be used as a \fIstd::ostream\fP to write
syslog messages using stream facilities\&. 
.PP 
Multiple separate insertions can be used to create a single syslog message:
the message is only sent to the syslog daemon after receiving a \fIflush\fP
command (e\&.g\&., after inserting \fIstd::flush\fP or \fIstd::endl\fP)\&. Non\-printable
characters (like \fI\(cq\&\en\(cq\&\fP) show up in the syslog message as octal values,
preceded by \fI#\fP (e\&.g\&., \fI#012\fP for \fI\(cq\&\en\(cq\&\fP)\&. The newline normally inserted
by \fIstd::endl\fP is ignored: \fBSyslogStream\fP objects interpret \fIstd::endl\fP
like \fIstd::flush\fP\&. 
.PP 
One series of insertions may contain multiple \fIstd::endl\fP or \fIstd::flush\fP
manipulators\&. At each of these manipulators a new message is sent to the
syslog daemon, containing all info that has so far been buffered\&. After
sending a message to the syslog daemon, the \fBSyslogStream\fP\(cq\&s internal buffer
is cleared\&.
.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::ostream\fP
.PP 
.SH "ENUMERATIONS"

.PP 
The following enumerations are defined in the namespace \fBFBB\fP:
.PP 
\fBPriority\fP:
.PP 
The values of this enumeration match the corresponding priority
\fILOG_xxx\fP values used with \fBsyslog\fP(3):
.IP o 
\fBEMERG\fP:
.br 
system is unusable;
.IP o 
\fBALERT\fP:
.br 
action must be taken immediately;
.IP o 
\fBCRIT\fP:
.br 
critical conditions;
.IP o 
\fBERR\fP:
.br 
error conditions;
.IP o 
\fBWARNING\fP:
.br 
warning conditions;
.IP o 
\fBNOTICE\fP:
.br 
normal, but significant, condition;
.IP o 
\fBINFO\fP:
.br 
informational message;
.IP o 
\fBDEBUG\fP:
.br 
debug\-level message;
The \fIsetMask\fP member (see below) can be used to select which type of
messages will actually be processed by the syslog daemon\&.
.PP 
\fBPriorityType\fP:
.PP 
This enumeration has two values fine\-tuning the type of messages that
are actually processed by the syslog daemon:
.IP o 
\fBSINGLE\fP:
.br 
Only messages of the priority specified at the \fIsetMask\fP call are
processed by the syslog daemon;
.IP o 
\fBUPTO\fP:
.br 
Messages of priority \fIEMERG\fP up to the the priority specified at the
\fIsetMask\fP call are processed by the syslog daemon;
By default, the syslog daemon processes all messages it receives\&.
.PP 
\fBFacility\fP:
.PP 
The values of this enumeration match the corresponding facility
\fILOG_xxx\fP values used with \fBsyslog\fP(3):
.IP o 
\fBAUTHPRIV\fP:
.br 
security/authorization messages (private)
.IP o 
\fBCRON\fP:
.br 
clock daemon (\fIcron\fP and \fIat\fP)
.IP o 
\fBDAEMON\fP:
.br 
other system daemons
.IP o 
\fBKERN\fP:
.br 
kernel messages
.IP o 
\fBLOCAL0\fP:
.br 
reserved for local use\&. \fBLOCAL1\fP through \fBLOCAL7\fP are
available as well\&.
.IP o 
\fBLPR\fP:
.br 
line printer subsystem
.IP o 
\fBMAIL\fP:
.br 
mail subsystem
.IP o 
\fBNEWS\fP:
.br 
\fIUSENET\fP news subsystem
.IP o 
\fBSYSLOGBUF\fP:
.br 
messages generated internally by \fIsyslogbufd\fP
.IP o 
\fBUSER\fP:
.br 
generic user\-level messages
.IP o 
\fBUUCP\fP:
.br 
UUCP subsystem

.PP 
.SH "CONSTRUCTORS"
.IP o 
\fBSyslogStream(string const &ident = \(dq\&\(dq\&,
FBB::Priority priority = FBB::NOTICE, 
FBB::Facility facility = FBB::USER,
int option = 0)\fP:
.br 
This constructor initializes a \fBSyslogStream\fP object\&.  The
\fIident\fP parameter is usually the name of the program\&. Its content are
prepended to syslog messages\&. 
.IP 
The \fIpriority\fP parameter determines the default importance of the message
sent to the syslog daemon\&. By default messages are sent to the syslog daemon
with priority \fBFBB::NOTICE\fP\&. Syslog messages may be given different priority
by inserting a \fBSyslogStream\fP manipulator (see below)\&. The priority set at
construction time may also be modified using the \fIsetPriority\fP and
\fIsetDefaultPriority\fP members\&.
.IP 
Which messages actually appear in log facilities is not determined by
the messages\(cq\& priorities, but by syslog\(cq\&s \fIlog mask\fP\&. The log mask can be
set by the static member \fIsetMask\fP (see below)\&.
.IP 
The \fIfacility\fP parameter determines the type of program doing the
logging\&. By default \fBFBB::USER\fP is used\&.
.IP 
The \fIoption\fP parameter may be used to specify various options (use the
binary `\fIbitor\fP\(cq\& (`\fI|\fP\(cq\&) operator to combine options):
.IP 
\fBLOG_CONS\fP:
write directly to system console  if  there  is  an
error while sending to system logger 
.br 
\fBLOG_NDELAY\fP:
open the connection immediately (normally, the con\-
nection is opened when the first message is logged) 
.br 
\fBLOG_PERROR\fP:
print to stderr as well 
.br 
\fBLOG__PID\fP:
include PID with each message 
.br 

.IP 
By default no options are used\&.

.PP 
Copy and move constructors (and assignment operators) are not available\&.
.PP 
.SH "MEMBER FUNCTIONS"

.PP 
All members of \fBstd::ostream\fP are available, as \fBFBB::SyslogStream\fP
inherits from this class\&.
.PP 
.IP o 
\fBvoid close()\fP:
.br 
If the \fBSyslogStream\fP\(cq\&s internal buffer is not empty it is flushed to
the syslog daemon\&. Thereafer \fBcloselog\fP(3) is called\&.
.IP o 
\fBPriority defaultPriority() const\fP:
.br 
Returns the current default priority\&. I\&.e\&., the priority that will be
used for the messages after inserting \fIendl\fP or \fIflush\fP\&.
.IP o 
\fBvoid open(string const &ident,
FBB::Priority priority = FBB::NOTICE, 
FBB::Facility facility = FBB::USER,
int option = 0)\fP:
.br 
Redefines the current identifier, priority, facility and options that
are used when sending messages to the syslog daemon\&. If the
\fBSyslogStream\fP\(cq\&s internal buffer is not empty it is first flushed to
the syslog daemon using the identifier, priority and options that were
active just before calling \fIopen\fP\&.
.IP o 
\fBPriority priority() const\fP:
.br 
Returns the next priority\&. I\&.e\&., the priority that will be used for
the next message that is sent to the syslog daemon\&.
.IP o 
\fBPriority setDefaultPriority(Priority priority)\fP:
.br 
Changes the default priority of the next message that is sent to the
syslog daemon after inserting \fIstd::eoln\fP or
\fIstd::flush\fP\&. The previously active default priority is
returned\&.
.IP o 
\fBPriority setPriority(Priority priority)\fP:
.br 
Changes the priority for the
next message that is sent to the syslog daemon after inserting
\fIstd::eoln\fP or \fIstd::flush\fP\&. Subsequent messages will again use
the default priority\&. The previously active priority setting is
returned\&.

.PP 
.SH "STATIC MEMBER FUNCTIONS"

.PP 
.IP o 
\fBPriority setMask(Priority priority, PriorityMask upTo)\fP:
.br 
Syslog messages of (if \fIupTo\fP equals \fISINGLE\fP) or up to (if
\fIupTo\fP equals \fIUPTO\fP) the indicated priority are processed by the
syslog daemon\&. 
.IP o 
\fBPriority setMask(Priority priority, Priority \&.\&.\&.priorities)\fP:
.br 
Syslog messages of the priorities passed to \fIsetMask\fP are processed
by the syslog daemon\&. At least one priority must be specified\&.
.IP o 
\fBFacility stoF(std::string const &name, Facility facility = USER)\fP:
.br 
Returns the facility matching the name of the facility provided by
\fIname\fP\&. Facility matching is performed case insensitively\&. E\&.g\&., if
\fIname\fP contains \fIdaemon\fP, facility \fIFBB::DAEMON\fP is returned\&. If
\fIname\fP does not match any facility name then the value of this
function\(cq\&s second argument is returned\&. The function\(cq\&s name (\fIstoF\fP)
was used in analogy of the various \fIsto\&.\&.\&.\fP conversion functions
that were made available by the \fBC++11\fP standard\&.
.IP o 
\fBPriority stoP(std::string const &name, Priority priority = NOTICE)\fP:
.br 
Returns the priority matching the name of the priority provided by
\fIname\fP\&. Priority matching is performed case insensitively\&. E\&.g\&., if
\fIname\fP contains \fIemerg\fP, priority \fIFBB::EMERG\fP is returned\&. If
\fIname\fP does not match any priority name then the value of this
function\(cq\&s second argument is returned\&. The function\(cq\&s name (\fIstoP\fP)
was used in analogy of the various \fIsto\&.\&.\&.\fP conversion functions
that were made available by the \fBC++11\fP standard\&.

.PP 
.SH "MANIPULATORS"

.PP 
The following set of manipulators are all defined as (static) members\&.
They may be inserted into an \fBFBB::SyslogStream\fP object\&. Except for the last
manipulator (\fIstrerrno\fP), they have the following characteristics in common:
.IP o 
They change the priority of the messages that are subsequently
inserted by the \fBFBB::SyslogStream\fP object, thus acting like a separate
\fIsetPriority\fP call\&.
.IP o 
When inserting multiple manipulators before the inserted message is
flushed (e\&.g\&., using the \fIstd::flush\fP or the \fIstd::endl\fP manipulators) the
last inserted \fBFBB::SyslogStream\fP manipulator will be used\&.
.IP o 
If the manipulators are not inserted into an
\fBFBB::SyslogStream\fP object (but in another \fIstd::ostream\fP type of object)
then they perform no action\&.

.PP 
Here are the available manipulators:
.IP o 
\fBSyslogStream::alert\fP:
.br 
Messages are inserted with priority \fBFBB::ALERT\fP\&.
.IP o 
\fBSyslogStream::crit\fP:
.br 
Message are inserted with priority \fBFBB::CRIT\fP\&.
.IP o 
\fBSyslogStream::debug\fP:
.br 
Messages are inserted with priority \fBFBB::DEBUG\fP\&.
.IP o 
\fBSyslogStream::emerg\fP:
.br 
Messages are inserted with priority \fBFBB::EMERG\fP\&.
.IP o 
\fBSyslogStream::err\fP:
.br 
Messages are inserted with priority \fBFBB::ERR\fP\&.
.IP o 
\fBSyslogStream::info\fP:
.br 
Messages are inserted with priority \fBFBB::INFO\fP\&.
.IP o 
\fBSyslogStream::notice\fP:
.br 
Messages are inserted with priority \fBFBB::NOTICE\fP\&.
.IP o 
\fBSyslogStream::strerrno\fP:
.br 
This manipulator inserts the textual interpretation of \fIstd::errno\fP\(cq\&s
current value into a \fIstd::ostream\fP\&. Note that, different from the
other manipulators, the object into which this manipulator is inserted
does not have to be a \fBFBB::SyslogStream\fP object\&.
.IP o 
\fBSyslogStream::warning\fP:
.br 
Messages are inserted with priority \fBFBB::WARNING\fP\&.

.PP 
.SH "EXAMPLE"
.nf 

#include <bobcat/syslogstream>

using namespace std;
using namespace FBB;

int main(int argc, char **argv)
{
    SyslogStream sls(argv[0]);

    sls << SyslogStream::debug << \(dq\&Hello world\(dq\& << flush <<
           SyslogStream::strerrno << endl;
}
    
.fi 

.PP 
.SH "FILES"
\fIbobcat/syslogstream\fP \- defines the class interface
.PP 
.SH "SEE ALSO"
\fBbobcat\fP(7), \fBcloselog\fP(3), \fBopenlog\fP(3), \fBrsyslogd\fP(8),
\fBsyslog\fP(3), \fBsyslogbuf\fP(3bobcat)
.PP 
.SH "BUGS"
The constructor\(cq\&s \fIoption\fP parameter is an \fIint\fP\&. Because of this,
\fIint\fP values rather than enumeration values are passed to the
constructor\&. It is the responsibility of the programmer to pass defined option
values only\&.
.PP 
.SH "BOBCAT PROJECT FILES"

.PP 
.IP o 
\fIhttps://fbb\-git\&.gitlab\&.io/bobcat/\fP: gitlab project page;
.IP o 
\fIbobcat_5\&.07\&.00\-x\&.dsc\fP: detached signature;
.IP o 
\fIbobcat_5\&.07\&.00\-x\&.tar\&.gz\fP: source archive;
.IP o 
\fIbobcat_5\&.07\&.00\-x_i386\&.changes\fP: change log;
.IP o 
\fIlibbobcat1_5\&.07\&.00\-x_*\&.deb\fP: debian package containing the
libraries;
.IP o 
\fIlibbobcat1\-dev_5\&.07\&.00\-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