Provided by: libbobcat-dev_5.11.01-1_amd64 
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:
o ANY: an existing file may have any set of protection bits;
o EQUAL: an existing file mut have exactly the set of protection bits as specified
when calling Exception::protection.
CONSTRUCTORS
o Exception():
The default constructor (assigns 0 to FBB::g_errno, see the next constructor).
o Exception(int errnoValue):
This constructor stores the provided errnoValue value in a thread-local variable
int FBB::g_errno. Before Bobcat 4.04.00 errnoValue was only stored in the global
::errno variable (it still is), but as this variable is also used by many other
functions, errno’s value may have changed by the time the exception is caught. The
thread_local int FBB::g_errno variable does not have that drawback.
When g_errno must be declared without including bobcat/exception then do
namespace FBB
{
extern thread_local int g_errno;
}
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.
o char const *what() const noexcept(true) override:
Returns the text that was inserted into the FBB::Exception object.
OVERLOADED OPERATORS
o 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.
o 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") };
o 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.
o 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.
o 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.
o 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.
o 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.
o 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.
o static void open(StreamType &stream, std::string const &name):
Opens the stream object, using its default open member.
o 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.
o 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.
o 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.
o 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.
o 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.
o 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:
o 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
o https://fbb-git.gitlab.io/bobcat/: gitlab project page;
o bobcat_5.11.01-x.dsc: detached signature;
o bobcat_5.11.01-x.tar.gz: source archive;
o bobcat_5.11.01-x_i386.changes: change log;
o libbobcat1_5.11.01-x_*.deb: debian package containing the libraries;
o libbobcat1-dev_5.11.01-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).