FBB::Exception - std::exception objects acception stream
insertions
#include <bobcat/exception>
Linking option: -lbobcat
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
FBB
All constructors, members, operators and manipulators, mentioned in this
man-page, are defined in the namespace FBB.
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.
- 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.
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.
- 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.
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.
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).
if (exceptionalCondition)
throw FBB::Exception{ 1 } << "Exceptional condition occurred";
bobcat/exception - defines the class interface
- o
- https://fbb-git.gitlab.io/bobcat/: gitlab project page;
- o
- bobcat_6.02.02-x.dsc: detached signature;
- o
- bobcat_6.02.02-x.tar.gz: source archive;
- o
- bobcat_6.02.02-x_i386.changes: change log;
- o
- libbobcat1_6.02.02-x_*.deb: debian package containing the
libraries;
- o
- libbobcat1-dev_6.02.02-x_*.deb: debian package containing the
libraries, headers and manual pages;
Bobcat is an acronym of `Brokken’s Own Base Classes And
Templates’.
This is free software, distributed under the terms of the GNU
General Public License (GPL).
Frank B. Brokken (f.b.brokken@rug.nl).