---
name: "exception"
section: "3bobcat"
platform: "linux"
package: "libbobcat-dev"
version: "6.07.01-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/exception"
---

# exception(3bobcat)

std::exception objects acception stream insertions

## 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)](/open/2.md)) 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)](/bobcat/7.md)

## BUGS

None Reported.

## BOBCAT PROJECT FILES

- 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;

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