FBB::Exception - std::exception objects acception stream insertions

       Frank B. Brokken (f.b.brokken@rug.nl).

libbobcat-dev_6.07.01                               2005-2025                            FBB::Exception(3bobcat)

       Bobcat is an acronym of `Brokken’s Own Base Classes And Templates’.

       o      https://fbb-git.gitlab.io/bobcat/: gitlab project page;

       Debian Bobcat project files:

       o      libbobcat6: debian package containing the shared library, changelog and copyright note;

       o      libbobcat-dev: debian package containing the static library, headers, manual pages, and  developer
              info;

       None Reported.

       o      Exception():
              The default constructor (assigns 0 to FBB::g_errno, see the next constructor).

       o      Exception(interrnoValue):
              This constructor stores the provided errnoValue value in a thread-local variable intFBB::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_localintFBB::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.

       This is free software, distributed under the terms of the GNU General Public License (GPL).

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

       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.

           if (exceptionalCondition)
               throw FBB::Exception{ 1 } << "Exceptional condition occurred";

bobcat/exception - defines the class interface

std::exception

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

       All members of std::exception are available, as FBB::Exception inherits from this class.

       o      charconst*what()constnoexcept(true)override:
              Returns the text that was inserted into the FBB::Exception object.

       FBB::Exception - std::exception objects acception stream insertions

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

       o      Exception&&operator<<(Exception&&in,Typeconst&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.

bobcat(7)

       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      staticStreamTypefactory<StreamType>(std::stringconst&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      staticStreamTypefactory<StreamType>(interrnoValue,std::stringconst&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      staticStreamTypefactory<StreamType>(std::stringconst&name,std::ios::openmodemode):
              Returns  an  open  StreamType> stream object, created using the openmodemode flags,  which can be
              used to move-construct a StreamType object.

       o      staticStreamTypefactory<StreamType>(interrnoValue,std::stringconst&name,std::ios::openmodemode):
              Returns  an  open  StreamType> stream object, created using the openmodemode 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      staticStreamTypefactory<StreamType>(std::stringconst&name,std::ios::openmodemode1,std::ios::openmodemode2):
              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      staticStreamTypefactory<StreamType>(interrnoValue,std::stringconst&name,std::ios::openmodemode1,std::ios::openmodemode2):
              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      staticvoidopen(interrnoValue,StreamType&stream,std::stringconst&name,std::ios::openmodemode):
              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      staticvoidopen(StreamType&stream,std::stringconst&name):
              Opens the stream object, using its default open member.

       o      staticvoidopen(interrnoValue,StreamType&stream,std::stringconst&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      staticvoidopen(StreamType&stream,std::stringconst&name,std::ios::openmodemode):
              Opens the stream object, using its open member, passing mode to open.

       o      staticvoidopen(interrnoValue,StreamType&stream,std::stringconst&name,std::ios::openmodemode):
              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      staticvoidopen(StreamType&stream,std::stringconst&name,std::ios::openmodemode1,std::ios::openmodemode2):
              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      staticvoidopen(interrnoValue,StreamType&stream,std::stringconst&name,std::ios::openmodemode1,std::ios::openmodemode2):
              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      staticsize_tprotection(std::stringconst&path,size_tprotect,Protectiontype=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.

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