Provided by: libbobcat-dev_3.19.01-1ubuntu1_amd64 bug

NAME

       FBB::Log - std::ostream handling log messages

SYNOPSIS

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

DESCRIPTION

       The class FBB::Log is a std::ostream initialized with a FBB::LogBuffer. It is used to send
       log-messages to the (r)syslog stream. Refer to the logbuffer(3bobcat) man-page for details
       about this process.

NAMESPACE

       FBB
       All  constructors,  members,  operators  and manipulators, mentioned in this man-page, are
       defined in the namespace FBB.

INHERITS FROM

       std::ostream

ENUMERATIONS

       The enumeration TimeStamps is defined in the namespace  FBB,  primarily  for  initializing
       FBB::LogBuffer  objects.  It  is  used with FBB::Log members as well. 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.

       The enumeration LogManipulator is used to handle special or exceptional situations through
       manipulators. It is defined in the namespace FBB and has the following two values:

       o      FATAL:
              This  value  may  be  inserted  into  an FBB::Log object to throw an FBB::Exception
              exception (see operator<<() below);

       o      nl:
              This value may be inserted into an FBB::Log object to terminate the  current  line.
              It  will not cause the next line to begin with a time stamp (if applicable) and the
              current message level cannot be modified using a level(3bobcat) manipulator. It  is
              used to allow a single log message to occupy multiple textual lines.

       o      endl:
              This  is  the  standard  ostream  manipulator.  When inserted into a Log object the
              current buffer is flushed. Note that flushing does not happen  immediately  when  a
              newline  (\n)  is  inserted  into  the log stream. Alternatively, std::flush may be
              inserted into the Log object to flush its buffer.

CONSTRUCTORS

       o      Log(char const *delim = " "):
              The default constructor creates a FBB::Log object which isn’t yet associated with a
              stream to log messages on. The member open() (see below) may be used to define such
              a stream.  By default, all messages will have a time stamp prepended to  them  (see
              the  description  of  the  member  setTimestamp()  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.

       o      Log(std::ostream &out, char const *delim = " "):
              This  constructor  creates  a  FBB::Log object logging its messages to the provided
              std::ostream object. By default, all messages will have a time stamp  prepended  to
              them (see the description of the member setTimestamp() 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.

       o      FBB::Log(std::string  const  &filename,  std::ios::openmode  mode = std::ios::out |
              std::ios::app, char const *delim = " "):
              This constructor creates a FBB::Log object logging its messages to the named  file.
              If  filename == "&1" the logmessages will be written to the standard output stream.
              If filename == "&2" the logmessages will be written to the standard  error  stream.
              By  default  the  file is created if not existing, and all messages are appended to
              the stream.  By default, all messages will have a time stamp prepended to them (see
              the  description  of  the  member  setTimestamp()  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.   The  copy constructor is not
              available.

MEMBER FUNCTIONS

       All members of std::ostream are available, as FBB::Log inherits from this class.

       o      size_t level():
              This member returns the currently set log level (i.e., the value set at the  latest
              setLevel() call).

       o      std::ostream &level(size_t useLevel):
              This  member  defines  a  log-level. Messages will be inserted into the stream when
              useLevel is equal to or exceeds the level set  by  setLevel().  The  maximum  level
              which  can  be  selected  is  std::numeric_limits<size_t>::max().  If not even such
              messages  should  be  inserted  into  the  ostream,  then  the  stream  should   be
              deactivated,  using  off(),  see  below.  The  selected  level remains active until
              redefined. Alternatively, the  FBB::level  manipulator  may  be  inserted  into  an
              (empty) FBB::Log object (see level(3bobcat)).

       o      void off():
              Prevents  any  log messages from being generated. It may be cancelled by setLevel()
              (see below).

       o      void open(std::string const &filename, std::ios::openmode mode  =  std::ios::out  |
              std::ios::app, char const *delim = " "):
              This  member  (re)associates an FBB::Log object with the named file. If filename ==
              "&1" the logmessages will be written to the standard output stream. If filename  ==
              "&2"  the logmessages will be written to the standard error stream.  By default the
              file is created if not existing, and all messages are appended to the  stream.   By
              default, all messages will have a time stamp prepended to them (see the description
              of the member setTimestamp() 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.

       o      void setLevel(size_t newLevel):
              Redefines the internal message level. Messages having at least level newLevel  will
              be written. If the member is used without explicit argument, logging is suspended.

       o      void setTimestamp(FBB::TimeStamps stamp, 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 timestamp 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.

STATIC MEMBERS

       o      FBB::Log   &initialize(std::string   const  &filename,  std::ios::openmode  mode  =
              std::ios::out | std::ios::app, char const *delim = " "):

              Returns a reference to a static FBB::Log object. It may only be called once, or  an
              FBB::Exception exception is thrown. It associates a static FBB::Log object with the
              named file. If filename == "&1" the logmessages will be  written  to  the  standard
              output  stream. If filename == "&2" the logmessages will be written to the standard
              error stream.  By default the file is created if not existing, and all messages are
              appended  to the stream.  By default, all messages will have a time stamp prepended
              to them (see the description of the member setTimestamp()  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.

       o      FBB::Log &instance():
              Returns  a  reference  to  a  static  FBB::Log  object,  available  after   calling
              Log::initialize().  If  called before Log::initialize() an FBB::Exception exception
              is thrown.

OVERLOADED OPERATOR

       The following overloaded operator is defined outside of the FBB namespace. It may be  used
       to  insert  an  FBB::LogManipulator into an FBB::Log object. If the overloaded operator is
       used in combination with another type of object it performs no actions.

       o      std::ostream &::operator<<(std::ostream &str, FBB::LogManipulator):
              When inserting FBB::FATAL an FBB::Exception exception  is  thrown;  when  inserting
              FBB::nl  the  line  is  terminated,  but next insertions will not start with a time
              stamp (if applicable).

EXAMPLE

       #include <iostream>
       #include <iomanip>

       #include <bobcat/log>

       using namespace std;
       using namespace FBB;

       int main()
       {
           Log &log = Log::initialize("&1");

           log << "This message is written to cout" << nl <<
                  setw(16) << ’ ’ << "occupying multiple lines\n";

           log.off();
           log << "This message is not shown\n";
           log.setLevel(0);
           log << "This message is shown again\n";
           return 0;
       }

FILES

       bobcat/log - defines the class interface

SEE ALSO

       bobcat(7), errno(3bobcat), level(3bobcat), logbuffer(3bobcat)

BUGS

       None reported

DISTRIBUTION FILES

       o      bobcat_3.19.01-x.dsc: detached signature;

       o      bobcat_3.19.01-x.tar.gz: source archive;

       o      bobcat_3.19.01-x_i386.changes: change log;

       o      libbobcat1_3.19.01-x_*.deb: debian package holding the libraries;

       o      libbobcat1-dev_3.19.01-x_*.deb: debian package holding the libraries,  headers  and
              manual pages;

       o      http://sourceforge.net/projects/bobcat: public archive location;

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).