Provided by: libbobcat-dev_6.07.01-2_amd64 
NAME
FBB::Filesystem - class offering std::filesystem facilities
SYNOPSIS
#include <bobcat/filesystem>
Linking option: -lbobcat
This header file also includes the std::chrono header file.
DESCRIPTION
The Bobcat class FileSystem is a plain wrapper around the facilities offered by the C++ std::filesystem
namespace. FileSystem was developed because the use of the std::filesystem facilities is considered
overly complex: too many free functions having signatures resembling C, and therefore not object-based.
Its std::filesystem::path type offers several nice features which are then usable via the path member
functions, but functions manipulating the file system aren’t members, but are defined as free functions
requiring path arguments.
The class FileSystem offers almost all std::filesystem facilities via its member functions. Except for
some (static) members all facilities operate on data stored inside FileSystem objects.
The class FileSystem is an extensive class: over-all it contains about 60 constructors, operators and
members. It’ll probably take a while before a mental picture of what the class offers has been attained,
but at least it embeds all components of the std::filesystem namespace.
Note:
o The class FileSystem uses std::chrono::file_clock, which is available since the C++-2a standard:
specify the --std=c++2a (or more recent) compiler option when using FileSystem.
NAMESPACE
FBB
All constructors, members, operators and manipulators, mentioned in this man-page, are defined in the
namespace FBB.
INHERITS FROM
FBB::FS - internally used only, covered in this man-page
TYPEDEFS AND ENUMS
Typedefs:
o DirEntry - std::filesystem::directory_entry
o DirIter - std::filesystem::directory_iterator
o EC - std::error_code
o FileClock - std::chrono::file_clock
o FileType - std::filesystem::file_type
o Path - std::filesystem::path
o Perms - std::filesystem::perms
o RecursiveIter - std::filesystem::recursive_directory_iterator
o FileStatus - std::filesystem::file_status
o SystemClock - std::chrono::system_clock
FSOptions:
o enum FSOptions:
contains the following values, inherited by FileSystem. Options up to CP_MASK are primarily used
by the copy member, options beyond CP_MASK are used by setPermissions:
NEW copy is only performed if the destination
doesn’t yet exist
REPLACE copy is only performed if the destination
exists but it is replaced
UPDATE copy is only performed if the destination
is older than the filesystem entry to copy
RECURSIVE directories are recursively copied; can be
combined with CP_SYMLINKS, SKIP_SYMLINKS,
ONLY_DIRS
CP_SYMLINKS symlinks are copied as symlinks
SKIP_SYMLINKS symlinks are ignored
ONLY_DIRS only the directory structure is copied
other entries in directories are ignored
SYMLINK with copy: define a symlink to the current
entry
HARDLINK with copy: define a hard link to the current
entry
FILE with copy: only files are processed, not
directories
CP_SYMLINK copies a symlink to a symlink
NEW_SYMLINK defines a non-existing (directory) symlink
NEW_LINK create_hard-link
CP_MASK all the above enum values
RESET replace the current permissions
ADD add to the current permissions
REMOVE remove the specified permissions
All bit-wise operators are available for FSOptions values.
STATIC DATA MEMBER
The class FileSystem defines one static data member: std::error_code s_errorCode. All FileSystem objects
can use this error_code object after calling their function call operator. E.g.,
FileSystem fs;
fs();
Once fs() has been called members called by fs accepting error_code arguments receive s_error_code as
their argument. It’s also possible to use other error_code objects, or not to use error_code arguments
(which is the default). See also the description of the function call operator below.
CONSTRUCTORS
Path arguments can also be arguments of types from which Path objects can be constructed (e.g.,
std::string, char const *, raw string literal).
FileSystem objects contain two data members: a Path and an EC *. When FileSystem objects are initialized
their EC * is set to 0.
o Filesystem():
The default constructor constructs an empty object, not using the class’s static s_errorCode
object;
o Filesystem(Path const &path, bool useEC = true):
The object is initialized with a copy of path. By default useEC == true, in which case it uses the
class’s static s_errorCode object;
o Filesystem(Path &&path, EC &ec):
The object is initialized with a copy of path, passing ec to members supporting EC arguments;
o Filesystem(Path const &tmp, bool useEC = true):
The object moves tmp to its internal path. By default useEC == true, in which case it uses the
class’s static s_errorCode object;
o Filesystem(Path &&tmp, EC &ec):
The object moves tmp to its internal path, passing ec to members supporting EC arguments.
Copy and move constructors (and assignment operators) are available. The newly constructed or assigned
object use the same EC specification as their source (right-hand side) objects.
OVERLOADED OPERATORS
Type arguments can be arguments of type FileSystem, Path or types from which Path objects can be
constructed (e.g., std::string, char const *, raw string literal).
o std::istream &operator>>(std::istream &in, FileSystem &rhs):
extracts a path specification from in, and initializes rhs with the extracted path;
o std::ostream &operator<<(std::ostream &out, FileSystem const &rhs):
inserts the object’s path into out;
o bool operator==(FileSystem const &lhs, FileSystem const &rhs):
returns true if lhs and rhs refer to the same file system entry. An exception is thrown if at
least one argument doesn’t refer to an existing file system entry and the lhs operand hasn’t
specified an EC (see operator()() below). This operator calls the member sameAs for its lhs
argument;
o FileSystem &operator/=(Type const &arg):
arg is appended to the object’s path data member. If the path data member did not already end in
’/’ then /arg is appended;
o FileSystem &operator+=(Type const &arg):
arg is appended to the object’s path data member;
o FileSystem [const] &operator()(EC &ec = s_errorCode) [const]:
this operator activates passing EC arguments to member function accepting such arguments. By
calling this operator without argument member functions receive FileSystem’s s_errorCode.
Alternatively another (e.g., local) error_code object can be specified which will then be passed
to members accepting error_code arguments. Example:
std::error_code ec;
FileSystem fs;
fs(ec);
Using EC arguments is configured separately for each FileSystem object. The member noEC can be
used to suppress passing EC arguments to std::filesystem functions;
MEMBER FUNCTIONS
Type arguments can be arguments of type FileSystem, Path or types from which Path objects can be
constructed (e.g., std::string, char const *, raw string literal).
All members can use EC objects to prevent exceptions being thrown when the members cannot perform their
tasks.
o FileSystem absolute() const:
returns a FileSystem object containing the absolute path of the calling object’s Path, which does
not have to exist. Relative directory specifications are kept: absolute simply prefixes the
current working directory to the calling object’s Path;
o FileSystem canonical() const:
returns a FileSystem object containing the canonical absolute path of the calling object’s Path,
from which all relative specifications have been removed. Path must refer to an existing file
system entry;
o bool copy(Type const &dest, FSOptions cpOptions = DEFAULT):
copies the object’s file system entry to dest. It is covered in detail in the section COPYING FILE
SYSTEM ENTRIES below;
o uintmax_t count() const:
returns the number of hard-link counts of the calling FileSystem object. The file system entry
must exist;
o char const *c_str() const:
returns the calling object’s PATH specification as a NTBS;
o static FileSystem cwd([EC &ec]):
this static member returns the current working directory (cwd). If the cwd cannot be determined
then an exception is thrown, unless an EC argument is specified, in which case the EC argument
provides information about the failure;
o FileSystem destination() const:
returns a FileSystem object containing the (symlink) destination of the calling object, which must
refer to a symlink;
o DirEntry directory() const:
returns a DirEntry for the calling object. The calling object does not have to refer to a
directory, and not even to an existing file system entry;
o Ranger<DirIter> dirRange() const:
returns a pair of directory iterators non-recursively visiting all entries referred to by the
calling object, which must specify a directory name (see also the member recursiveRange). Example:
for (auto const &entry: fs.dirRange())
cout << entry << ’\n’;
o static std::error_code &errorCode():
this static member returns a reference to FileSystem’s static (modifiable) EC data member.
o bool exists() const:
returns true if the current object’s file system entry exists;
o static bool exists(FileStatus status):
returns true if status indicates that the current file system entry exists (see also the member
status below);
o std::string extension() const:
returns the extension (including the initial dot (.) of the calling object);
o FileClock::time_point fcModification() const:
returns the FileClock::time_point of the (existing) file system entry represented by the calling
object;
o std::string filename() const:
returns the filename (i.e., the path name from which all but the last element has been removed).
If the calling object doesn’t contain a filename (as with ./ or /) then and empty string is
returned;
o bool hasExtension() const:
returns true if the calling object’s Path has an extension;
o bool hasFilename() const:
returns true if the calling object’s Path contains characters after its final / character;
o bool isAbsolute() const:
returns true if the calling object’s Path starts with /;
o bool isRelative() const:
returns true if the calling object’s Path does not start with /;
o bool knownStatus() const:
this member only returns false for std::filesystem::file_status{}. The member status is probably
more useful: non-existing entries show status values FileType::not_found or FileType::unknown.
To check for specific statuses the functions
bool is_WHATEVER(file_status status) or
bool is_WHATEVER(path const &entry [, EC &ec])
can also be used;
o bool mkDir() const:
returns true if the (plain) directory name stored in the calling oblect could be created. This
member does not create nested sub-directories, but the directory name specified as the last
(/-separated) component of the calling object’s Path is created if its parent directories already
exist;
o bool mkDir(Type const &reference) const:
same as the previous member, but the created directory receives the same attributes (permissions)
as reference;
o bool mkDirs() const:
returns true if the last component of the calling object’s Path could be created and its parent
components could either be created or already existed as directories. Only the directories are
constructed, not their entries. Use the copy member (see section COPYING FILE SYSTEM ENTRIES
below) to copy directories and their file system entries;
o SystemClock::time_point modification() const:
returns the SystemClock::time_point of the (existing) file system entry represented by the calling
object;
o FileSystem [const] &noEC() [const]:
if the calling object uses an EC, then the EC won’t be used anymore after calling this member;
o FileSystem parent() const:
returns a FileSystem object initialized with the parent Path of the calling object. The parent is
equal to the calling object’s Path from which its filename has been removed (returning an empty
object if the calling object merely contains `/’);
o Path const &path() const:
returns the current object’s Path data member. When inserting path() into an ostream Path is
surrounded by double quotes. If that’s not required call the string member;
o Perms permissions() const:
returns the permissions of the calling object, which must refer to an existing file system entry.
The returned Perms value consists of bitwise or-ed values of the std::filesystem::perms enum
class, but can be statically cast to mode_t values which are used as argument to chmod(2);
o Ranger<[Const]Iter> range() [const]:
returns a pair of iterators visiting all components of the calling object’s Path.Example:
for (auto const &comp: fs.range())
cout << comp << ’\n’;
o FileSystem relative() const:
returns a copy of the calling object from which an initial `/’ has been removed;
o bool remove() const:
returns true if the current object’s file system entry has been removed;
o size_t removeAll() const:
returns the number of (recursively) removed file system entries starting at the calling object’s
Path. The calling object doesn’t have to specify a directory;
o bool rename(Type const &newName) const:
returns true if the current file system entry could be renamed to newName. The calling object’s
Path is not altered;
o bool resize(std::uintmax_t size) const:
returns true if the current file system entry could be resized to size;
o bool sameAs(Type const &other) const:
returns true if other refers to the same file system entry as the calling object. It is called by
operator== as its lhs member;
o FileSystem &setCwd():
changes the current process’s current working directory to the directory specified by the calling
object;
o static FileSystem setCwd(Path const &path [, EC &ec]):
this static member changes the current process’s current working directory to the directory
specified by its Path argument;
o FileSystem &setExtension(std::string const &ext):
changes the filename extension of the current object to ext. A dot (.) is used to separate the
current object’s stem (see below) and the extension. The resulting file name only has a single
dot;
o FileSystem &setFilename(std::string const &newName):
changes the current object’s file name (including its extension) to newName. If the current object
refers to an existing file system entry then that file system entry is kept as-is;
o bool setModification(FBB::DateTime const &time):
changes the modification time of the current file system entry to the time time-specification;
o bool setModification(SystemClock::time_point const &time):
changes the modification time of the current file system entry to the time time-specification;
o FileSystem [const] &setPermissions(PermType perms, FSOptions opt = RESET) [const]:
changes the permissions of the current file system entry to perms, which must be statically
castable to Perms. Example:
// change "entry’s" permissions to -rw-------
FileSystem{ "entry" }.setPermissions(0600);
o bool setType(FileType type, bool destination = true):
it’s unclear what this function is used for. It calls filesystem::(symlink_)status, using
symlink_status when called as type(false). It returns false if type doesn’t match the current file
system entry referred, but the type itself isn’t modified;
o uintmax_t size() const:
returns the size in bytes of the current file system entry;
o FileStatus status(bool destination = true) const:
returns the filesystem::status of the current file system entry. If the current object is a
symlink and the symlink’s status is requested then call status(false);
o FileSystem stem() const:
returns the file name of the current object without its extension;
o std::string string() const:
returns the current object’s Path data member as a std::string;
o static FileSystem tmpDir(Type arg [= true]):
this static member returns the file system’s directory which is by default used for temporary
files. By default tmpDir uses FileSystem::s_errorCode objct, when calling tmpDir(false) no EC
object is used;
o static FileSystem tmpDir(EC &ec):
this static member returns the file system’s directory using the specified EC object when
determining the temporay directory;
o FileType type(bool destination = true) const:
returns the FileType of the current file system entry. If the current object refers to a symlink
call type(false) to receive the symlink’s type.
COPYING FILE SYSTEM ENTRIES
The member copy(Type const &dest, FSOptions cpOptions = DEFAULT)’s first argument specifies the name of
the copied file or directory. It’s second argument specifies the type of the copy-operation. Options can
be combined using binary operators (usually bit_or). The following combinations are valid:
o FILE - unconditionally copies the current entry to dest;
o FILE | NEW - the current entry is copied to dest if dest does not yet exist;
o FILE | REPLACE - the current entry is copied to dest if dest already exists;
o FILE | UPDATE - the current entry is only copied to dest if it is younger than dest;
o CP_SYMLINK - the current entry must be a symlink, dest may not yet exist and becomes a symlink to
the same destination as the current entry’s destination;
o NEW_LINK - dest may not yet exist. It becomes a hard-link to the current entry. The current object
must exist;
o NEW_SYMLINK - dest may not yet exist. It becomes a symlink to the current entry. If the current
entry is itself a symlink then dest becomes a symlink to the current entry, and not to the entry
the current object refers to. The current object does not have to be an existing file system
entry;
o RECURSIVE - the current entry is recursively copied to dest. If the current entry isn’t a
directory then the entry itself is copied as if RECURSIVE was not specified;
o RECURSIVE | CP_SYMLINKS - like using RECURSIVE but existing symlinks are copied as symlinks;
o RECURSIVE | ONLY_DIRS - like using RECURSIVE but only the directory structure is copied;
o RECURSIVE | SKIP_SYMLINKS - like using RECURSIVE but existing symlinks are not copied;
EXAMPLE
#include <iostream>
#include <string>
#include <exception>
#include <bobcat/filesystem>
using namespace std;
using namespace FBB;
int main(int argc, char **argv)
{
if (argc == 1)
{
cout << "1st arg: an existing file\n"
"2nd arg (optional): a directory owned by the caller\n";
return 1;
}
FileSystem fs{ argv[1] };
if (not fs.exists())
cout << "No such file " << argv[1] << ’\n’;
else
cout << "last modification date of " << argv[1] << ": " <<
fs.modification() << ’\n’;
cout << oct << "Permissions: 0" <<
static_cast<size_t>(fs.permissions()) << dec << ’\n’;
if (argc > 2)
{
cout << "Entries of " << argv[2] << ":\n";
FileSystem fs2{ argv[2] };
for (auto const &entry: fs2.dirRange())
cout << " " << entry << ’\n’;
cout << fs2.errorCode().message() << ’\n’;
}
}
FILES
bobcat/filesystem - defines the class interface
SEE ALSO
bobcat(7), chmod(2), datetime(3bobcat), ranger(3bobcat)
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).
libbobcat-dev_6.07.01 2005-2025 FBB::FileSystem(3bobcat)