FBB::Exception(3bobcat)
insertable exception class
(libbobcat-dev_6.06.02)
2005-2024
NAME
FBB::Exception - std::exception objects acception stream insertions
SYNOPSIS
    #include <bobcat/exception>
    Linking option: -lbobcat
DESCRIPTION
       FBB::Exception objects derived from std::exception, but accept
stream insertions. Their intended use consists of throwing an anonymous
object, into which the text of the std::exception::what
message has been inserted.
Exception exceptions are thrown by several Bobcat classes. These
classes are 
Arg,
ArgConfig,
BigInt,
Cgi,
Cidr,
ClientSocket,
CmdFinderBase,
ConfigFile,
DateTime,
DecryptBuf,
DigestBuf,
EncryptBuf,
Fork,
GetHostent,
Glob,
HMacBuf,
Hostname,
LocalClientSocket,
LocalServerSocket,
LocalSocketBase,
Log,
MailHeaders,
Mbuf,
Milter,
Mstream,
OFoldBuf,
OneKey,
Pattern,
Pipe,
Process,
Redirector,
Selector,
ServerSocket,
Signal,
SocketBase,
Stat,
TempStream,
User,
Xpointer
NAMESPACE
    FBB
    All constructors, members, operators and manipulators, mentioned in this
man-page, are defined in the namespace FBB.
INHERITS FROM
    std::exception
ENUMERATION
    The enumeration Protection is used by the member protection
described below. The enumeration has two values:
    
    -  ANY: an existing file may have any set of protection bits;
    
-  EQUAL: an existing file mut have exactly the set of protection bits
        as specified when calling Exception::protection.
    
CONSTRUCTORS
    
Copy and move constructors (and assignment operators) are available.
MEMBER FUNCTIONS
     All members of std::exception are
available, as FBB::Exception inherits from this class.
    
    -  char const *what() const noexcept(true) override:
 Returns the text that was inserted into the FBB::Exception object.
OVERLOADED OPERATORS
    
    -  Exception &&operator<<(Exception &&in, Type const &t):
 A function template implementing the overloaded insertion operator. It
can be used to insert values of any type that can also be inserted into an
ostringstream object.
STATIC MEMBERS
The following convenience functions can be used for controlled opening of
stream-type objects, like std::ofstream and std::ifstream
objects. These stream-type objects must support open and close
members, like those provided by std::ifstream and std::ofstream.
If the stream  was already open it is first closed.
If opening fails an FBB::Exception exception is thrown containing a
short message stating that the named stream could not be opened.
    -  static StreamType factory<StreamType>(std::string const &name):
 Returns an open StreamType> stream object which can be used to
        move-construct a StreamType object. E.g.,
    auto out{ Exception::factory<ofstream>("/tmp/out") };
            
 
-  static StreamType factory<StreamType>(int errnoValue,
                                              std::string const &name):
 Returns an open StreamType> stream object which can be used to
        move-construct a StreamType object. If constructing
        the stream object fails, then the thrown FBB::Exception assigns
        errnoValue to FBB::g_errno.
 
-  static StreamType factory<StreamType>(std::string const &name,
                                              std::ios::openmode mode):
 Returns an open StreamType> stream object, created using
        the openmode mode flags,  which can be used to
        move-construct a StreamType object.
 
-  static StreamType factory<StreamType>(int errnoValue,
                                              std::string const &name,
                                              std::ios::openmode mode):
 Returns an open StreamType> stream object, created using
        the openmode mode flags,  which can be used to
        move-construct a StreamType object.  If constructing
        the stream object fails, then the thrown FBB::Exception assigns
        errnoValue to FBB::g_errno.
 
-  static StreamType factory<StreamType>(std::string const &name,
                                              std::ios::openmode mode1,
                                              std::ios::openmode mode2):
 Returns an open StreamType> stream object. the stream is initially
        opened using mode1. If that fails, mode2 is used. If both ways
        to open the stream fail, then an Exception is thrown.  The
        returned stream can be used to move-construct a StreamType object.
        This member can be used to open an std::fstream which may or may
        not yet exist for both reading and writing. E.g.,
    auto out{ Exception::factory<fstream>("/tmp/out",
                ios::in | ios::out,
                ios::in | ios::out | ios::trunc) };
            
If /tmp/out already exists, then ios::in | ios::out should
        succeed. If it doesn't, then it's created empty for reading and
        writing, using ios::in | ios::out | ios::trunc.
 
-  static StreamType factory<StreamType>(int errnoValue,
                                              std::string const &name,
                                              std::ios::openmode mode1,
                                              std::ios::openmode mode2):
 Returns an open StreamType> stream object. the stream is initially
        opened using mode1. If that fails, mode2 is used. If both ways
        to open the stream fail, then an Exception is thrown, assigning
        errnoValue to FBB::g_errno.
 
-  static void open(int errnoValue, StreamType &stream,
                        std::string const &name, std::ios::openmode mode):
 Opens the stream object, using its open member, passing mode to
        open. If opening the stream fails, then the thrown
        FBB::Exception assigns errnoValue to FBB::g_errno.
 
-  static void open(StreamType &stream, std::string const &name):
 Opens the stream object, using its default open member.
 
-  static void open(int errnoValue,
                         StreamType &stream, std::string const &name):
 Opens the stream object, using its default open member. If opening
        the stream fails, then the thrown FBB::Exception assigns
        errnoValue to FBB::g_errno.
 
-  static void open(StreamType &stream, std::string const &name,
                                    std::ios::openmode mode):
 Opens the stream object, using its open member, passing mode to
        open.
 
-  static void open(int errnoValue, StreamType &stream,
                        std::string const &name, std::ios::openmode mode):
 Opens the stream object, using its open member, passing mode to
        open. If opening the stream fails, then the thrown
        FBB::Exception assigns errnoValue to FBB::g_errno.
 
-  static void open(StreamType &stream, std::string const &name,
                                    std::ios::openmode mode1,
                                    std::ios::openmode mode2):
 Opens the stream object, using its open member, , initially passing
        mode1 to open. If that fails, mode2 is used. If both ways
        to open the stream fail, then an Exception is thrown.
 
-  static void open(int errnoValue, StreamType &stream,
                        std::string const &name, std::ios::openmode mode1,
                                    std::ios::openmode mode2):
 Opens the stream object, using its open member, initially passing
        mode1 to open. If that fails, mode2 is used. If both ways
        to open the stream fail, then an Exception is thrown, assigning
        errnoValue to FBB::g_errno.
 
-  static size_t protection(std::string const &path, size_t protect,
                          Protection type = EQUAL):
 Returns the protection bits (cf. open(2)) of path. The
        protect parameter is used to specify the requested protection
        bits. This value is usually specified as an octal value. If the
        specified value exceeds 0777 an exception is thrown. The third
        parameter is only used in combination with already existing files. If
        specified as ANY the file's actual permission bits are not
        compared with protect; if specified as EQUAL the file's
        permission bits must be identical to protect, or an exception is
        thrown. If path does not yet exist a file path with permission
        protect is created. This member returns path's permission
        bits.
If path is created by protection, then opening a stream for
        path does not change path's protection.
     
MANIPULATOR
The following manipulator (which is not part of the
FBB::Exception, class, but is defined in the FBB namespace) can be
inserted into the FBB::Exception object:
    
    -  FBB::errnodescr:
 The descriptive text associated with the current errno value is
inserted into the FBB::Exception object (it can also be used to insert the
descriptive text in a std::ostream object). No text is inserted if
errno equals zero. This manipulator is thread-safe (but errno may be
modified when errno holds an invalid value).
EXAMPLE
        
    if (exceptionalCondition)
        throw FBB::Exception{ 1 } << "Exceptional condition occurred";
        
FILES
    bobcat/exception - defines the class interface
SEE ALSO
    bobcat(7)
BUGS
    None Reported.
BOBCAT PROJECT FILES
    -  https://fbb-git.gitlab.io/bobcat/: gitlab project page;
    
-  bobcat_6.06.02-x.dsc: detached signature;
    
-  bobcat_6.06.02-x.tar.gz: source archive;
    
-  bobcat_6.06.02-x_i386.changes: change log;
    
-  libbobcat1_6.06.02-x_*.deb: debian package containing the
            libraries;
    
-  libbobcat1-dev_6.06.02-x_*.deb: debian package containing the
            libraries, headers and manual pages;
    
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).