Chapter 4: Namespaces

4.1: Namespaces

Imagine a math teacher who wants to develop an interactive math program. For this program functions like cos, sin, tan etc. are to be used accepting arguments in degrees rather than arguments in radians. Unfortunately, the function name cos is already in use, and that function accepts radians as its arguments, rather than degrees.

Problems like these are usually solved by defining another name, e.g., the function name cosDegrees is defined. C++ offers an alternative solution through namespaces. Namespaces can be considered as areas or regions in the code in which identifiers may be defined. Identifiers defined in a namespace normally won't conflict with names already defined elsewhere (i.e., outside of their namespaces). So, a function cos (expecting angles in degrees) could be defined in a namespace Degrees. When calling cos from within Degrees you would call the cos function expecting degrees, rather than the standard cos function expecting radians.

4.1.1: Defining namespaces

Namespaces are defined according to the following syntax:
    namespace identifier
    {
        // declared or defined entities
        // (declarative region)
    }

The identifier used when defining a namespace is a standard C++ identifier.

Within the declarative region, introduced in the above code example, functions, variables, structs, classes and even (nested) namespaces can be defined or declared. Namespaces cannot be defined within a function body. However, it is possible to define a namespace using multiple namespace declarations. Namespaces are `open' meaning that a namespace CppAnnotations could be defined in a file file1.cc and also in a file file2.cc. Entities defined in the CppAnnotations namespace of files file1.cc and file2.cc are then united in one CppAnnotations namespace region. For example:

    // in file1.cc
    namespace CppAnnotations
    {
        double cos(double argInDegrees)
        {
            ...
        }
    }

    // in file2.cc
    namespace CppAnnotations
    {
        double sin(double argInDegrees)
        {
            ...
        }
    }

Both sin and cos are now defined in the same CppAnnotations namespace.

Namespace entities can be defined outside of their namespaces. This topic is discussed in section 4.1.4.1.

4.1.1.1: Declaring entities in namespaces

Instead of defining entities in a namespace, entities may also be declared in a namespace. This allows us to put all the declarations in a header file that can thereupon be included in sources using the entities defined in the namespace. Such a header file could contain, e.g.,
    namespace CppAnnotations
    {
        double cos(double degrees);
        double sin(double degrees);
    }

4.1.1.2: A closed namespace

Namespaces can be defined without a name. Such an anonymous namespace restricts the visibility of the defined entities to the source file defining the anonymous namespace.

Entities defined in the anonymous namespace are comparable to C's static functions and variables. In C++ the static keyword can still be used, but its preferred use is in class definitions (see chapter 7). In situations where in C static variables or functions would have been used the anonymous namespace should be used in C++.

The anonymous namespace is a closed namespace: it is not possible to add entities to the same anonymous namespace using different source files.

4.1.2: Referring to entities

Given a namespace and its entities, the scope resolution operator can be used to refer to its entities. For example, the function cos() defined in the CppAnnotations namespace may be used as follows:
    // assume CppAnnotations namespace is declared in the
    // following header file:
    #include <cppannotations>

    int main()
    {
        cout << "The cosine of 60 degrees is: " <<
                CppAnnotations::cos(60) << '\n';
    }

This is a rather cumbersome way to refer to the cos() function in the CppAnnotations namespace, especially so if the function is frequently used. In cases like these an abbreviated form can be used after specifying a using declaration. Following

    using CppAnnotations::cos;  // note: no function prototype,
                                // just the name of the entity
                                // is required.

calling cos results in a call of the cos function defined in the CppAnnotations namespace. This implies that the standard cos function, accepting radians, is not automatically called anymore. To call that latter cos function the plain scope resolution operator should be used:

    int main()
    {
        using CppAnnotations::cos;
        ...
        cout << cos(60)         // calls CppAnnotations::cos()
            << ::cos(1.5)       // call the standard cos() function
            << '\n';
    }

A using declaration can have restricted scope. It can be used inside a block. The using declaration prevents the definition of entities having the same name as the one used in the using declaration. It is not possible to specify a using declaration for a variable value in some namespace, and to define (or declare) an identically named object in a block also containing a using declaration. Example:

    int main()
    {
        using CppAnnotations::value;
        ...
        cout << value << '\n';  // uses CppAnnotations::value
        int value;              // error: value already declared.
    }

4.1.2.1: The `using' directive

A generalized alternative to the using declaration is the using directive:
    using namespace CppAnnotations;

Following this directive, all entities defined in the CppAnnotations namespace are used as if they were declared by using declarations.

While the using directive is a quick way to import all the names of a namespace (assuming the namespace has previously been declared or defined), it is at the same time a somewhat dirty way to do so, as it is less clear what entity is actually used in a particular block of code.

If, e.g., cos is defined in the CppAnnotations namespace, CppAnnotations::cos is going to be used when cos is called. However, if cos is not defined in the CppAnnotations namespace, the standard cos function will be used. The using directive does not document as clearly as the using declaration what entity will actually be used. Therefore use caution when applying the using directive.

Namespace declarations are context sensitive: when a using namespace declaration is specified inside a compound statement then the declaration is valid until the compound statement's closing curly bracket has been encountered. In the next example a string first is defined without explicit specifying std::string, but once the compound statement has ended the scope of the using namespace std declaration has also ended, and so std:: is required once again when defining second:

    #include <string>
    int main()
    {
        {
            using namespace std;
            string first;
        }
        std::string second;
    }

A using namespace directive cannot be used within the declaration block of a class- or enumeration-type. E.g., the following example won't compile:

    struct Namespace
    {
        using namespace std;      // won't compile
    };

4.1.2.2: `Koenig lookup'

If Koenig lookup were called the `Koenig principle', it could have been the title of a new Ludlum novel. However, it is not. Instead it refers to a C++ technicality.

`Koenig lookup' refers to the fact that if a function is called without specifying its namespace, then the namespaces of its argument types are used to determine the function's namespace. If the namespace in which the argument types are defined contains such a function, then that function is used. This procedure is called the `Koenig lookup'.

As an illustration consider the next example. The function FBB::fun(FBB::Value v) is defined in the FBB namespace. It can be called without explicitly mentioning its namespace:

    #include <iostream>

    namespace FBB
    {
        enum Value        // defines FBB::Value
        {
            FIRST
        };

        void fun(Value x)
        {
            std::cout << "fun called for " << x << '\n';
        }
    }

    int main()
    {
        fun(FBB::FIRST);    // Koenig lookup: no namespace
                            // for fun() specified
    }
    /*
        generated output:
    fun called for 0
    */
The compiler is rather smart when handling namespaces. If Value in the namespace FBB would have been defined as typedef int Value then FBB::Value would be recognized as int, thus causing the Koenig lookup to fail.

As another example, consider the next program. Here two namespaces are involved, each defining their own fun function. There is no ambiguity, since the argument defines the namespace and FBB::fun is called:

    #include <iostream>

    namespace FBB
    {
        enum Value        // defines FBB::Value
        {
            FIRST
        };

        void fun(Value x)
        {
            std::cout << "FBB::fun() called for " << x << '\n';
        }
    }

    namespace ES
    {
        void fun(FBB::Value x)
        {
            std::cout << "ES::fun() called for " << x << '\n';
        }
    }

    int main()
    {
        fun(FBB::FIRST);    // No ambiguity: argument determines
                            // the namespace
    }
    /*
        generated output:
    FBB::fun() called for 0
    */

Here is an example in which there is an ambiguity: fun has two arguments, one from each namespace. The ambiguity must be resolved by the programmer:

    #include <iostream>

    namespace ES
    {
        enum Value        // defines ES::Value
        {
            FIRST
        };
    }

    namespace FBB
    {
        enum Value        // defines FBB::Value
        {
            FIRST
        };

        void fun(Value x, ES::Value y)
        {
            std::cout << "FBB::fun() called\n";
        }
    }

    namespace ES
    {
        void fun(FBB::Value x, Value y)
        {
            std::cout << "ES::fun() called\n";
        }
    }

    int main()
    {
        //  fun(FBB::FIRST, ES::FIRST); ambiguity: resolved by
        //                              explicitly mentioning
        //                              the namespace
        ES::fun(FBB::FIRST, ES::FIRST);
    }
    /*
        generated output:
    ES::fun() called
    */

An interesting subtlety with namespaces is that definitions in one namespace may break the code defined in another namespace. It shows that namespaces may affect each other and that namespaces may backfire if we're not aware of their peculiarities. Consider the following example:

    namespace FBB
    {
        struct Value
        {};

        void fun(int x);
        void gun(Value x);
    }

    namespace ES
    {
        void fun(int x)
        {
            fun(x);
        }
        void gun(FBB::Value x)
        {
            gun(x);
        }
    }
Whatever happens, the programmer'd better not use any of the functions defined in the ES namespace, since that would result in infinite recursion. However, that's not the point. The point is that the programmer won't even be given the opportunity to call ES::fun since the compilation fails.

Compilation fails for gun but not for fun. But why is that so? Why is ES::fun flawlessly compiling while ES::gun isn't? In ES::fun fun(x) is called. As x's type is not defined in a namespace the Koenig lookup does not apply and fun calls itself with infinite recursion.

With ES::gun the argument is defined in the FBB namespace. Consequently, the FBB::gun function is a possible candidate to be called. But ES::gun itself also is possible as ES::gun's prototype perfectly matches the call gun(x).

Now consider the situation where FBB::gun has not yet been declared. Then there is of course no ambiguity. The programmer responsible for the ES namespace is resting happily. Some time after that the programmer who's maintaining the FBB namespace decides it may be nice to add a function gun(Value x) to the FBB namespace. Now suddenly the code in the namespace ES breaks because of an addition in a completely other namespace (FBB). Namespaces clearly are not completely independent of each other and we should be aware of subtleties like the above. Later in the C++ Annotations (chapter 11) we'll return to this issue.

Koenig lookup is only used in the context of namespaces. If a function is defined outside of a namespace, defining a parameter of a type that's defined inside a namespace, and that namespace also defines a function with an identical signature, then the compiler reports an ambiguity when that function is called. Here is an example, assuming the abovementioned namespace FBB is also available:

    void gun(FBB::Value x);

    int main(int argc, char **argv)
    {
        gun(FBB::Value{});          // ambiguity: FBB::gun and ::gun can both
                                    // be called.
    }

4.1.3: The standard namespace

The std namespace is reserved by C++. The standard defines many entities that are part of the runtime available software (e.g., cout, cin, cerr); the templates defined in the Standard Template Library (cf. chapter 18); and the Generic Algorithms (cf. chapter 19) are defined in the std namespace.

Regarding the discussion in the previous section, using declarations may be used when referring to entities in the std namespace. For example, to use the std::cout stream, the code may declare this object as follows:

    #include <iostream>
    using std::cout;

Often, however, the identifiers defined in the std namespace can all be accepted without much thought. Because of that, one frequently encounters a using directive, allowing the programmer to omit a namespace prefix when referring to any of the entities defined in the namespace specified with the using directive. Instead of specifying using declarations the following using directive is frequently encountered: construction like

    #include <iostream>
    using namespace std;

Should a using directive, rather than using declarations be used? As a rule of thumb one might decide to stick to using declarations, up to the point where the list becomes impractically long, at which point a using directive could be considered.

Two restrictions apply to using directives and declarations:

4.1.4: Nesting namespaces and namespace aliasing

Namespaces can be nested. Here is an example:
    namespace CppAnnotations
    {
        int value;
        namespace Virtual
        {
            void *pointer;
        }
    }

The variable value is defined in the CppAnnotations namespace. Within the CppAnnotations namespace another namespace (Virtual) is nested. Within that latter namespace the variable pointer is defined. To refer to these variable the following options are available:

Following a using namespace directive all entities of that namespace can be used without any further prefix. If a single using namespace directive is used to refer to a nested namespace, then all entities of that nested namespace can be used without any further prefix. However, the entities defined in the more shallow namespace(s) still need the shallow namespace's name(s). Only after providing specific using namespace directives or using declarations namespace qualifications can be omitted.

When fully qualified names are preferred but a long name like

    CppAnnotations::Virtual::pointer

is considered too long, a namespace alias may be used:

    namespace CV = CppAnnotations::Virtual;

This defines CV as an alias for the full name. The variable pointer may now be accessed using:

    CV::pointer = 0;

A namespace alias can also be used in a using namespace directive or using declaration:

    namespace CV = CppAnnotations::Virtual;
    using namespace CV;

Nested namespace definitions

Starting with the C++17 standard, when nesting namespaces a nested namespace can directly be referred to using scope resolution operators. E.g.,

    namespace Outer::Middle::Inner
    { 
        // entities defined/declared here are defined/declared in the Inner
        // namespace, which is defined in the Middle namespace, which is
        // defined in the Outer namespace
    }

4.1.4.1: Defining entities outside of their namespaces

It is not strictly necessary to define members of namespaces inside a namespace region. But before an entity is defined outside of a namespace it must have been declared inside its namespace.

To define an entity outside of its namespace its name must be fully qualified by prefixing the member by its namespaces. The definition may be provided at the global level or at intermediate levels in the case of nested namespaces. This allows us to define an entity belonging to namespace A::B within the region of namespace A.

Assume the type int INT8[8] is defined in the CppAnnotations::Virtual namespace. Furthermore assume that it is our intent to define a function squares, inside the namespace
CppAnnotations::Virtual returning a pointer to CppAnnotations::Virtual::INT8.

Having defined the prerequisites within the CppAnnotations::Virtual namespace, our function could be defined as follows (cf. chapter 9 for coverage of the memory allocation operator new[]):

    namespace CppAnnotations
    {
        namespace Virtual
        {
            void *pointer;

            typedef int INT8[8];

            INT8 *squares()
            {
                INT8 *ip = new INT8[1];

                for (size_t idx = 0; idx != sizeof(INT8) / sizeof(int); ++idx)
                    (*ip)[idx] = (idx + 1) * (idx + 1);

                return ip;
            }
        }
    }

The function squares defines an array of one INT8 vector, and returns its address after initializing the vector by the squares of the first eight natural numbers.

Now the function squares can be defined outside of the CppAnnotations::Virtual namespace:

    namespace CppAnnotations
    {
        namespace Virtual
        {
            void *pointer;

            typedef int INT8[8];

            INT8 *squares();
        }
    }

    CppAnnotations::Virtual::INT8 *CppAnnotations::Virtual::squares()
    {
        INT8 *ip = new INT8[1];

        for (size_t idx = 0; idx != sizeof(INT8) / sizeof(int); ++idx)
            (*ip)[idx] = (idx + 1) * (idx + 1);

        return ip;
    }

In the above code fragment note the following:

Finally, note that the function could also have been defined in the CppAnnotations region. In that case the Virtual namespace would have been required when defining squares() and when specifying its return type, while the internals of the function would remain the same:

    namespace CppAnnotations
    {
        namespace Virtual
        {
            void *pointer;

            typedef int INT8[8];

            INT8 *squares();
        }

        Virtual::INT8 *Virtual::squares()
        {
            INT8 *ip = new INT8[1];

            for (size_t idx = 0; idx != sizeof(INT8) / sizeof(int); ++idx)
                (*ip)[idx] = (idx + 1) * (idx + 1);

            return ip;
        }
    }

4.2: The std::chrono namespace (handling time)

The C programming language offers tools like sleep(3) and select(2) to suspend program execution for a certain amount of time. And of course the family of time(3) functions for setting and displaying time

Sleep and select can be used for waiting, but as they were designed in an era when multi threading was unavailable, their usefulness is limited when used in multi threaded programs. Multi threading has become part of C++ (covered in detail in chapter 20), and additional time-related functions are available in the std::filesystem namespace, covered below in this chapter.

In multi threaded programs threads are frequently suspended, albeit usually for a very short time. E.g., when a thread wants to access a variable, but the variable is currently being updated by another thread, then the former thread should wait until the latter thread has completed the update. Updating a variable usually doesn't take much time, but if it takes an unexpectedly long time, then the former thread may want to be informed about that, so it can do something else while the latter thread is busy updating the variable. Interactions between threads like these cannot be realized with functions like sleep and select.

The std::chrono namespace bridges the gap between the traditionally available time-related functions and the time-related requirements of multi-threading and of the std::filesystem name space. All but the specific std::filesystem related time functionality is available after including the <chrono> header file. After including the <filesystem> header file the facilities of the std::filesystem are available.

Time can be measured in various resolutions: in Olympic games time differences of hundreds of seconds may make the distinction between a gold and silver medal, but when planning a vacation we might talk about months before we go on vacation. Time resolutions are specified through objects of the class std::ratio, which (apart from including the <chrono> header file) is also available after including the <ratio> header file.

Different events usually last for different amounts of time (given a specific time resolution). Amounts of time are specified through objects of the class std::chrono::duration.

Events can also be characterized by their points in time: midnight, January 1, 1970 GMT is a point in time, as is 19:00, December 5, 2010. Points in time are specified through objects of the class std::chrono::time_point.

It's not just that resolutions, durations of events, and points in time of events may differ, but the devices (clocks) we use for specifying time also differ. In the old days hour glasses were used (and sometimes they're still used when boiling eggs), but on the other hand we may use atomic clocks when measurements should be very precise. Four different types of clocks are available. The commonly used clock is std::chrono::system_clock, but in the context of the file system there's also an (implicitly defined) filesystem::__file_clock.

In the upcoming sections the details of the std::chrono namespace are covered. First we look at characteristics of time resolutions. How to handle amounts of time given their resolutions is covered next. The next section describes facilities for defining and handling time-points. The relationships between these types and the various clock-types are covered thereafter.

In this chapter the specification std::chrono:: is often omitted (in practice using namespace std followed by using namespace chrono is commonly used; [std::]chrono:: specifications are occasionally used to avoid ambiguities). Also, every now and then you'll encounter forward references to later chapters, like the reference to the chapter about multi-threading. These are hard to avoid, but studying those chapters at this point fortunately can be postponed without loss of continuity.

4.2.1: Time resolutions: std::ratio

Time resolutions (or units of time) are essential components of time specifications. Time resolutions are defined through objects of the class std::ratio.

Before the class ratio can be used, the <ratio> header file must be included. Instead the <chrono> header file can be included.

The class ratio requires two template arguments. These are positive integral numbers surrounded by pointed brackets defining, respectively, the numerator and denominator of a fraction (by default the denominator equals 1). Examples:

    ratio<1>        - representing one; 
    ratio<60>       - representing 60
    ratio<1, 1000>  - representing 1/1000.

The class ratio defines two directly accessible static data members: num represents its numerator, den its denominator. A ratio definition by itself simply defines a certain amount. E.g., when executing the following program

    #include <ratio>
    #include <iostream>
    using namespace std;

    int main()
    {
        cout << ratio<5, 1000>::num << ',' << ratio<5, 1000>::den << '\n' <<
                milli::num << ',' << milli::den << '\n';
    }

the text 1,200 is displayed, as that's the `amount' represented by ratio<5, 1000>: ratio simplifies the fraction whenever possible.

A fairly large number of predefined ratio types exist. They are, like ratio itself, defined in the standard namespace and can be used instead of the more cumbersome ratio<x> or ratio<x, y> specification:


yocto 10-24
zepto 10-21

atto 10-18 femto 10-15 pico 10-12
nano 10-9 micro 10-6 milli 10-3
centi 10-2 deci 10-1

deca 101 hecto 102 kilo 103
mega 106 giga 109 tera 1012
peta 1015 exa 1018

zetta 1021 yotta 1024

(note: the definitions of the types yocto, zepto, zetta and yotta use integral constants exceeding 64 bits. Although these constants are defined in C++, they are not available on 64 bit or smaller architectures.)

Time related ratios can very well be interpreted as fractions or multiple of seconds, with ratio<1, 1> representing a resolution of one second.

Here is an example showing how these abbreviations can be used:

        cout << milli::num << ',' << milli::den << '\n' <<
                kilo::num << ',' << kilo::den << '\n';

4.2.2: Amounts of time: std::chrono::duration

Amounts of time are specified through objects of the class std::chrono::duration.

Before using the class duration the <chrono> header file must be included.

Like ratio the class duration requires two template arguments. A numeric type (int64_t is normally used) defining the type holding the duration's amount of time, and a time-resolution (called its resolution), usually specified through a std::ratio-type (often using one of its chrono abbreviations).

Using the predefined std::deca ratio, representing units of 10 seconds an interval of 30 minutes is defined as follows:

    duration<int64_t, std::deca> halfHr(180);

Here halfHr represents a time interval of 180 deca-seconds, so 1800 seconds. Comparable to the predefined ratios predefined duration types are available:


nanoseconds   duration<int64_t, nano>
microseconds   duration<int64_t, micro>
milliseconds   duration<int64_t, milli>
seconds   duration<int64_t>
minutes   duration<int64_t, ratio<60>>
hours   duration<int64_t, ratio<3600>>

Using these types, a time amount of 30 minutes can now simply be defined as minutes halfHour(30).

The two types that were specified when defining a duration<Type, Resolution> can be retrieved as, respectively,

Duration objects can be constructed by specifying an argument of its numeric type:

Duration supports copy- and move-constructors (cf. chapter 9) and its default constructor initializes its int64_t data member to zero.

The amount of time stored in a duration object may be modified by adding or subtracting two duration objects or by multiplying, dividing, or computing a modulo value of its data member. Numeric multiplication operands may be used as left-hand side or right-hand side operands; in combination with the other multiplication operators the numeric operands must be used as right-hand side operands. Compound assignment operators are also available. Some examples:

    minutes fullHour = minutes{ 30 } + halfHour;
    fullHour = 2 * halfHour;
    halfHour = fullHour / 2;
    fullHour = halfHour + halfHour;

    halfHour /= 2;
    halfHour *= 2;

In addition, duration offers the following members (the first member is an ordinary member function requiring a duration object). The other three are static members (cf. chapter 8) which can be used without requiring objects (as shown at the zero code snippet):

Duration objects using different resolutions may be combined as long as no precision is lost. When duration objects using different resolutions are combined the resulting resolution is the finer of the two. When compound binary operators are used the receiving object's resolution must be the finer or the compilation fails.

    minutes halfHour{ 30 };
    hours oneHour{ 1 };

    cout << (oneHour + halfHour).count();   // displays: 90

    halfHour += oneHour;            // OK
    // oneHour += halfHours;        // won't compile

The suffixes h, min, s, ms, us, ns can be used for integral values, creating the corresponding duration time intervals. E.g., minutes min = 1h stores 60 in min.

4.2.3: Clocks measuring time

Clocks are used for measuring time. C++ offers several predefined clock types, and all but one of them are defined in the std::chrono namespace. The exception is the clock std::filesystem::__file_clock (see section 4.3.1 for its details).

Before using the chrono clocks the <chrono> header file must be included.

We need clock types when defining points in time (see the next section). All predefined clock types define the following types:

All predefined clock types have a member now returning the clock's time_point corresponding to the current time (relative to the clock's epoch). It is a static member and can be used this way: system_clock::time_point tp = system_clock::now().

There are three predefined clock types in the chrono namespace:

The __file_clock is defined in the std::filesystem namespace ( covered in section 4.3.1).

In addition to now the classes system_clock and high_resolution_clock (referred to as Clock below) offer these two static members:

The example illustrates how these functions can be called:

    system_clock::from_time_t(
        system_clock::to_time_t(
            system_clock::from_time_t(
                time(0);
            )
        )
    );

4.2.4: Points in time: std::chrono::time_point

Single moments in time can be specified through objects of the class std::chrono::time_point.

Before using the class time_point the <chrono> header file must be included.

Like duration the class time_point requires two template arguments: A clock type and a duration type. Usually system_clock is used as the clock's type using nanoseconds as the default duration type (it may be omitted if nanoseconds is the intended duration type). Otherwise specify the duration type as the time_point's second template argument. The following two time point definitions therefore use identifcal time point types:

    time_point<standard_clock, nanoseconds> tp1;
    time_point<standard_clock> tp2;

The class time_point supports three constructors:

The following operators and members are available:

All predefined clocks use nanoseconds as their time resolution. To express the time in a less precise resolution take one unit of time of the less precise resolution (e.g., hours(1)) and convert it to nanoseconds. Then divide the value returned by the time point's time_since_epoch().count() member by count member of the less precise resolution converted to nanoseconds. Using this procedure the number of hours passed since the beginning of the epoch can be determined:

    cout << system_clock::now().time_since_epoch().count() /
            nanoseconds(hours(1)).count() << 
            " hours since the epoch\n";

Time point objects based on the system clock or on the high resolution clock can be converted to std::time_t (or the equivalent type time_t) values. Such time_t values are used when converting time to text. For such conversions the manipulator put_time (cf. section 6.3.2) is commonly used, but put_time must be provided with the address of a std::tm object, which in turn can be obtained from a std::time_t value. The whole process is fairly complex, and the core elements are visualized in figure 3.

Figure 3: Time according to C++

The essential step eventually leading to the insertion of a time point's value into a std::ostream consists of using system_clock::to_time_t(time_point<system_clock> const &tp) to convert a time point to a time_t value (instead of using system_clock the high_resolution_clock can also be used). How a time point can be inserted into a std::ostream is described in section 6.4.4.

4.3: The std::filesystem namespace

Computers commonly store information that must survice reboots in their file systems. Traditionally, to manipulate the file system the C programming language offers functions performing the required system calls. Such functions (like rename(2), truncate(2), opendir(2), and realpath(3)) are of course also available in C++, but their signatures and way of use are often less attractive as they usually expect char const * parameters and may use static buffers or memory allocation based on malloc(3) and free(3).

Since 2003 the Boost library offers wrappers around these functions, offering interfaces to those system calls that are more C++-like.

Currently C++ directly supports these functions in the std::filesystem namespace. These facilities can be used after including the <filesystem> header file.

The filesystem namespace is extensive: it contains more than 10 different classes, and more than 30 free functions. To refer to the identifiers defined in the std::filesystem namespace their fully qualified names (e.g., std::filesystem::path can be used). Alternatively, after specifying `using namespace std::filesystem;' the identifiers can be used without further qualifications. Namespace specifications like `namespace fs = std::filesystem;' are also encountered, allowing specifications like fs::path.

Functions in the filesystem namespace may fail. When functions cannot perform their assigned tasks they may throw exceptions (cf. chapter 10) or they may assign values to error_code objects that are passed as arguments to those functions (see section 4.3.2 below).

4.3.1: the '__file_clock' type

In section 4.2.3 it was stated that various predefined clocks are available, of which the system_clock refers to the clock used by the computer itself. The filesystem namespace uses a different clock: the std::filesystem::__file_clock. Time points obtained using the __file_clock differ from the time points obtained using the system clock: time points using the __file_clock are based on an epoch that (currently) lies well beyond the epoch Jan 1, 00:00:00 1970 that is used by the system clock: Fri Dec 31 23:59:59 2173. The two epochs can be positioned on a time scale with the present somewhere in between:
    <------|-----------------------|-----------------------|------->
      system_clock's -------->  present <--------    __file_clock's
       epoch starts  positive            negative     epoch starts
                      count               count

The __file_clock has its own peculiarities: the static member now is available, as are the the non-static members: additions and subtractions of durations and the member time_since_epoch can all be used. The other members (to_time_t, from_time_t, min and max) aren't available.

Since to_time_t is not available for __file_clock how can we show the time or obtain the time's components of a time_point<__file_clock> object?

Computing the difference between the epochs we find 6'437'663'999 seconds, which we can add to the obtained time since the __file_clock's epoch to obtain the time since the system_clock's epoch. If timePt holds the duration since the __file_clock epoch then

    6'437'663'999 + system_clock::to_time_t(
                        time_point<system_clock>{ nanoseconds(timePt) })

equals the number of seconds since the system_clock's epoch.

The potential drawback of this procedure is that, as __file_clock's name starts with underscores, the begin of its epoch might change. By using the now members of both clocks this drawback is avoided:

    auto systemNow = system_clock::now().time_since_epoch();
    auto fileNow = __file_clock::now().time_since_epoch();
    time_t diff = (systemNow - fileNow) / 1'000'000'000;

    time_t seconds = diff + system_clock::to_time_t(
                        time_point<system_clock>{ nanoseconds(timePt) });

4.3.2: The class 'error_code'

Objects of the class std::error_code encapsulate error values, and associated error categories (cf. section 10.9). Traditionally error values are available as values assigned to the global int errno variable. By convention, when errno's value equals zero there's no error. This convention was adopted by error_code.

Error codes can be defined for many conceptually different situations. Those situations are characterized by their own error categories.

Error categories are used to associate error_code objects with the errors that are defined by those categories. Default available error categories may use values like EADDRINUSE (or the equivalent enum class errc value address_in_use) but new types of error categories, tailored to other contexts, can also be defined. Defining error categories is covered near the end of the C++ Annotations (section 23.7.1). At this point two error_category members are briefly introduced:

Error category classes are singleton classes: only one object exists of each error category. In the context of the filesystem namespace the standard category system_category is used, and a reference to the system_category object is returned by the free function std::system_category, expecting no arguments. The public interface of the class error_code declares these construtors and members:

Constructors:

Members:

Free functions:

Several functions introduced below define an optional last error_code &ec parameter. Those functions have noexcept specifications. If those functions cannot complete their tasks, then ec is set to the appropriate error code, calling ec.clear() if no error was encountered. If no ec argument is provided then those functions throw a filesystem_error exception if they cannot complete their tasks.

4.3.3: Names of file system entries: path

Objects of the class filesysten::path hold names of file system entries. The class path is a value class: a default constructor (empty path) as well as standard copy/move construction/assignment facilities are available. In addition, the following constructors can be used: A thus constructed path doesn't have to refer to an existing file system entry.

Path constructors expect character sequences (including NTBSs) that may consist of various (all optional) elements:

The constructors also define a last format ftmp = auto_format parameter, fir which in practice almost never an argument has to be provided (for its details see cppreference.)

Many functions expect path arguments which can usually be created from NTBSs or std::string objects as path allows promotions (cf. section 11.4). E.g., the filesystem function absolute expects a const &path argument. It can be called like this: absolute("tmp/filename").

4.3.3.1: Path modifiers

Objects of the class path can be handled in various ways:

Accessors (no arguments, const members) return the path's content in various forms, depending on the used accessor member: c_str returns an NTBS, string, wstring, u8string, u16string, u32string (possibly prefixed by generic_, like generic_string) returns a string-type of object. Example:

    path ulb{ "/usr/local/bin" };
    cout << ulb.string() << '\n';      // shows:   /usr/local/bin

Double quotes surround the displayed path name when inserting a path object into a stream. The double quotes are omitted when accessing the path's content as an NTBS or as a string, and also when assigning (or casting) path objects to strings.

When extracting path objects from streams the path name that is extracted may optionally be surrounded by double quotes. The extracted path contains one set of surrounding quotes.

All of the path's components are sequentially accessed using its begin and end iterators: each component is returned as a path. If available root names and root directories are returned as initial components, followed by the individual directories and finally filename components. The directory separators themselves are not returned when iterating over a path's components.

Path components may also directly be obtained (if a component isn't present then an empty path component is returned). The following decomposers are available: root_name, root_directory, root_path, relative_path, parent_path ( returning the current path-content from which the last element has been removed), filename, stem (returning the filename without its dot-extension), and extension. Example:

    path ulb{ "/usr/local/bin" };
    cout << ulb.relative_path() << '\n';    // shows:  "usr/local/bin"
                                            // (note the double quotes)

When prefixed by has_ the member returns a bool which is true if the component is present. Also available: is_absolute, is_relative.

4.3.3.2: Path operators and free functions

In addition to the member functions various (free) operators are available:

Path objects can be compared (using the ==, !=, <, <=, >, and >= operators); the / operator returns the concatenated lhs and rhs, separated by a directory separator.

Comparisons use lexicographical comparisons (as if by comparing the return values of their string members).

In addition free functions are available. Some of these copy files. Those functions accept an optional std::filesystem::copy_options argument. The enum class copy_options defines symbolic constants that can be used to fine-tune the behavior of these functions. The enumeration supports bitwise operators (the symbols' values are shown between parentheses). It defines these symbols:

The following functions expect path arguments:

4.3.4: Handling directories: directory_entry

The file system is a recursive data structure. Its top-level entry is a directory (the root directory) containing plain directory entries (files, (soft) links, named sockets, etc.) and possibly also (sub)directory entries referring to nested directories which in turn may contiain plain- and (sub)directory entries.

In the std::filesystem namespace the elements of directories are objects of the class directory_entry, containing names and statuses of the entries of that directory.

The class directory_entry supports all standard constructors and assignment operators and in addition a constructor expecting a path:

    directory_entry(path const &entry);

Objects of the class directory_entry can be constructed by name, without requiring that those objects refer to existing entries in the computer's file system. The assignment operator is also available, as is the (ostream) insertion operator, inserting the object's path into the stream. The extraction operator is not available.

`directory_entry' objects may be compared using the ==, !=, <, <=, >, and >= operators. These operators are then applied to their path objects: directory_entry("one") == directory_entry("one") returns true.

In addition to these operators the class directory_entry also has these member functions:

4.3.4.1: Visiting directory entries: (recursive_)directory_iterator

The filesystem namespace has two classes simplifying directory processing: objects of the class directory_iterator are (input) iterators iterating over the entries of directories; and objects of the class recursive_directory_iterator are (input) iterators recursively visiting all entries of directories.

The classes (recursive_)directory_iterator provides default, copy, and move constructors. Objects of both classes may also be constructed from a path and an optional error_code. E.g.,

    directory_iterator(path const &dest [, error_code &ec]);

All members of standard input iterators (cf. section 18.2) are supported. These iterators point to directory_entry objects referring to entries in the computer's file system. E.g.,

    cout << *directory_iterator{ "/home" } << '\n'; // shows the first
                                                        // entry under /home

End-iterators matching these objects are available through the default constructed objects of the two classes. In addition, range-based for loops can be used as shown by the next example:

    for (auto &entry: directory_iterator("/var/log"))
        cout << entry << '\n';

For-statements explicitly defining iterators can also be used:

    for (
        auto iter = directory_iterator("/var/log"), 
              end = directory_iterator{}; 
                iter != end; 
                    ++iter
    )
        cout << entry << '\n';

After constructing a (recursive_)directory_iterator base{"/var/log"} object it refers to the first element of its directory. Such iterators can also explicitly be defined: auto &iter = begin(base), auto iter = begin(base), auto &iter = base or auto iter = base. All these iter objects refer to base's data, and incrementing them also advances base to its next element:

    recursive_directory_iterator base{ "/var/log/" };
    auto iter = base;
                                // final two elements show identical paths,
                                // different from the first element.
    cout << *iter << ' ' << *++iter << ' ' << *base << '\n';
The functions begin and end that are used in the above examples are, like (recursive_)directory_iterator, available in the filesystem namespace.

The recursive_directory_iterator also accepts a directory_options argument (see below), by default specified as directory_options::none:

    recursive_directory_iterator(path const &dest,
                            directory_options options [, error_code &ec]);

The enum class directory_options defines values that are used to fine-tune the behavior of recursive_directory_iterator objects, supporting bitwise operators (the values of its symbols are shown between parentheses):

The class recursive_directory_iterator also has these members:

Here is a little program displaying all directory elements of a directory and of all its immediate sub-directories.

    int main()
    {
        recursive_directory_iterator base{ "/var/log" };

        for (auto entry = base, end = end(base); entry != end; ++entry)
        {
            cout << entry.depth() << ": " << *entry << '\n';
            if (entry.depth() == 1)
                entry.disable_recursion_pending();
        }
    }

The above program handles entries as they come. If other strategies are needed they have to be implemented. E.g., a breadth-first strategy first visits all the non-directory entries and then visits the sub-directories. In the next example this is realized by processing each of the directories stored in level (initially it merely contains the starting directory). `Processing a directory' means that its non-directory entries are directly processed while the names of its sub-directories are stored in next. Once all entries in level have been processed the names of the next level sub-directories are available in next and by assigning next to level all directories at the next level are processed. When reaching the most deeply nested sub-directories next remains empty and the while statement ends:

    void breadth(path const &dir)           // starting dir.
    {
        vector<path> level{ dir };          // currently processed level
    
        while (not level.empty())           // process all its dirs.
        {
            vector<path> next;              // dirs of the next level
    
            for (auto const &dir: level)    // visit all dirs at this level
            {
                cout << "At " << dir << '\n';
                                            // at each dir: visit all entries
                for (auto const &entry: directory_iterator{ dir })
                {
                    if (entry.is_directory())   // store all dirs at the current
                        next.push_back(entry);  //  level
                    else                        // or process its non-dir entry
                        cout << "   entry: " << entry << '\n';
                }
            }
    
            level = next;                   // continue at the next level,
        }                                   // which eventually won't exist
    }

4.3.5: Types (file_type) and permissions (perms) of file system elements: file_status

File system entries (represented by path objects), have several attributes: permissions (e.g., the owner may modifiy an entry, others may only read entries), and types (like plain files, directories, and soft-links).

Types and permissions of file system entries are available through objects of the class file_status. The class file_status is a value-class supporting copy- and move- constructors and assignment operators.

The constructor

    explicit file_status(file_type type = file_type::none,
                         perms permissions = perms::unknown)

creates the file status for a specific type of file system entry having a specific set of permissions. It also acts as default constructor.

The constructor's first parameter is an enumeration specifying the type of a file system entry represented by a path object:

The constructor's second parameter defines the enum class perms specifying the access permissions of file system entries. The enumeration's symbols were selected so that their meanings should be more descriptive than the constants defined in the <sys/stat.h> header file, but other than that they have identical values. All bitwise operators can be used by values of the enum class perms. Here is an overview of the symbols defined by the enum class perms:


4
Symbol Value sys/stat.h
Meaning

none
0000
No permission bits were set
owner_read
0400
S_IRUSR
File owner has read permission
owner_write
0200
S_IWUSR
File owner has write permission
owner_exec
0100
S_IXUSR
File owner has execute/search permissions
owner_all
0700
S_IRWXU
File owner has read, write, and execute/search permissions
group_read
0040
S_IRGRP
The file's group has read permission
group_write
0020
S_IWGRP
The file's group has write permission
group_exec
0010
S_IXGRP
The file's group has execute/search permissions
group_all
0070
S_IRWXG
The file's group has read, write, and execute/search permissions
others_read
0004
S_IROTH
Other users have read permission
others_write
0002
S_IWOTH
Other users have write permission
others_exec
0001
S_IXOTH
Other users have execute/search permissions
others_all
0007
S_IRWXO
Other users have read, write, and execute/search permissions
all
0777
All users have read, write, and execute/search permissions
set_uid
04000
S_ISUID
Set user ID to file owner user ID on execution
set_gid
02000
S_ISGID
Set group ID to file's user group ID on execution
sticky_bit
01000
S_ISVTX
POSIX XSI specifies that when set on a directory
only file owners may delete files even if the directory is writeable by others
(used, e.g., with /tmp)
mask
07777
All valid permission bits.

The class file_status provides these members:

4.3.5.1: Obtaining the status of file system entries

The filesystem functions status and symlink_status retrieve or change statuses of file system entries. These functions may be called with a final (optional) error_code argument which is assigned an appropriate error code if they cannot perform their tasks. If the argument is omitted the members throw exceptions if they cannot perform their tasks:

Once a file_status object is obtained the file type of the entry whose status it represents can be interrogated using these functions (defined in the filesystem namespace, where WHATEVER is the requested specification):

    bool is_WHATEVER(file_status status)
    bool is_WHATEVER(path const path &entry [, error_code &ec])

These functions return true if status or status matches the requested type. Here are the available functions:

Alternatively, the file_status::type() member can be used in, e.g., a switch to select an entry matching its file_type return value (see the previous section (4.3.5) for a description of the symbols defined by the file_type enum).

Here is a little program showing how file statuses can be obtained and shown (for the map see section 12.4.7):

    namespace
    {
        std::unordered_map<file_type, char const *> statusMap =
        {
            { file_type::not_found, "an unknown file" },
            { file_type::none,      "not yet or erroneously evaluated "
                                                                "file type" },
            { file_type::regular,   "a regular file" },
            { file_type::directory, "a directory" },
            { file_type::symlink,   "a symbolic link" },
            { file_type::block,     "a block device" },
            { file_type::character, "a character device" },
            { file_type::fifo,      "a named pipe" },
            { file_type::socket,    "a socket file" },
            { file_type::unknown,   "an unknown file type" }
        };
    }
    
    int main()
    {
        cout << oct;
    
        string line;
        while (true)
        {
            cout << "enter the name of a file system entry: ";
            if (not getline(cin, line) or line.empty())
                break;
    
            path entry{ line };
    
            error_code ec;
            file_status stat = status(entry, ec);
    
            if (not status_known(stat))
            {
                cout << "status of " << entry << " is unknown. "
                                                "Ec = " << ec << '\n';
                continue;
            }
    
            cout << "status of " << entry << ": type = " <<
                     statusMap[stat.type()] <<
                     ", permissions: " <<
                        static_cast<size_t>(stat.permissions()) << '\n';
        }
    }

4.3.6: Information about the space of file systems: space_info

Every existing path lives in a file system, Sizes of file systems typically are quite large, but there is a limit to their sizes.

The size of file systems, the number of bytes that is currently being used and the remaining number of bytes is made available by the function space(path const &entry [, error_code &ec]), returning the information about the file system containing entry in a POD struct space_info.

If the error_code argument is provided then it is cleared if no error occurs, and set to the operating system's error code if an error has occurred. If an error occurs and the error_code argument was not provided then a filesystem_error exception is thrown, receiving path as its first argument and the operating system's error code as its error_code argument.

The returned space_info has three fields:

    uintmax_t capacity;     // total size in bytes
    uintmax_t free;         // number of free bytes on the file system
    uintmax_t available;    // free bytes for a non-privileged process

If a field cannot be determined it is set to -1 (i.e., the max. value of the type uintmax_t).

The function can be used this way:

    int main()
    {
        path tmp{ "/tmp" };
    
        auto pod = space(tmp);
    
        cout << "The filesystem containing /tmp has a capacity of " <<
                                                pod.capacity << " bytes,\n"
            "i.e., " << pod.capacity / (1024 * 1024) << " MB.\n"
            "# free bytes: " << pod.free << "\n"
            "# available:  " << pod.available << "\n"
            "free + available:  " << pod.free + pod.available << '\n';
    }

4.3.7: File system exceptions: filesystem_error

The std::filesystem namespace offers its own exception type filesystem_error (see also chapter 10). Its constructor has the following signature (the bracketed parameters are optional):
    filesystem_error(string const &what, 
                    [path const &path1, [path const &path2,]] 
                    error_code ec);

As filesystem facilities are closely related to standard system functions, errc error code enumeration values can be used to obtain error_codes to pass to filesystem_error, as illustrated by the following program:

    int main()
    try
    {
        try
        {
            throw filesystem_error{ "exception encountered", "p1", "p2",
                                        make_error_code(errc::address_in_use) };
        }
        catch (filesystem_error const &fse)
        {
            cerr << "what:  " << fse.what() << "\n"
                    "path1: " << fse.path1() << "\n"
                    "path2: " << fse.path2() << "\n"
                    "code:  " << fse.code() << '\n';
    
            throw;
        }
    }
    catch (exception const &ec)
    {
        cerr << "\n"
                "plain exception's what: " << ec.what() << "\n\n";
    }