Description:

This is the reference documentation of module ALib Files of the ALib C++ Library .

See also: A user manual with tutorial-style sample code is found in the Programmer's Manual of this module.

Nested Namespaces:
namespace	detail

Type Index:
struct	FFilter

class	FileExpressions

class	Files

class	FInfo

class	FTree

class	OwnerAndGroupResolver

struct	ResultsPaths

struct	ScanParameters

Type Definition Index:
using	PathString = alib::strings::TLocalString<character, 512>

using	SPFileFilter = std::shared_ptr<FFilter>

Function Index:
ALIB_API AString &	DbgDump (AString &target, FTree &tree, EnumBitSet< FInfo::Types > includedTypes=EnumBitSet< FInfo::Types >(true), FTree::Cursor startNode=FTree::Cursor(), unsigned int depth=(std::numeric_limits< unsigned int >::max)())

ALIB_API enum FInfo::Qualities	ScanFiles (FTree &tree, ScanParameters &parameters, std::vector< ResultsPaths > &resultPaths)

Type Definition Details:

◆ PathString

typedef alib::strings::TLocalString< character, 512 > PathString = alib::strings::TLocalString<character, 512>

Local path string buffer helper type fixed to size 512. The flexible nature of ALib local strings allow dynamic allocation if exceeded.

Definition at line 36 of file finfo.hpp.

◆ SPFileFilter

using SPFileFilter = std::shared_ptr<FFilter>

A shared pointer to a filter.

Definition at line 54 of file ffilter.hpp.

Function Details:

◆ DbgDump()

ALIB_API AString & DbgDump	(	AString &	target,
		FTree &	tree,
		EnumBitSet< FInfo::Types >	includedTypes = EnumBitSet< FInfo::Types >(true),
		FTree::Cursor	startNode = FTree::Cursor(),
		unsigned int	depth = (std::numeric_limits< unsigned int >::max)() )

Dumps the given branch of this object's tree.

Parameters

target	The target string buffer.
tree	The tree to dump.
includedTypes	Optional filter for types. Defaults to 'all'.
startNode	The start node. If this is not a valid node , the root node is chosen. Defaults to an invalid cursor.
depth	The maximum depth of recursion. Defaults to unlimited depth.

Returns: The given target to allow concatenated operations.

◆ ScanFiles()

ALIB_API enum FInfo::Qualities ScanFiles	(	FTree &	tree,
		ScanParameters &	parameters,
		std::vector< ResultsPaths > &	resultPaths )

General Information

Scans the filesystem according to given ScanParameters and adds FInfo entries to the given FTree .

ALib FTree Data Contract

This function has a contract with class FTree that is used to store the scan results. This contract states, that any file or directory found during scan is always stored using the "Real Path" of the entry. This means, any symbolic link is resolved. The consequences are:

Files and directories which represent a symbolic link are always "leaf nodes". (They never contain child nodes.). However, their symlink target path is attached twice to the entry:
1. The original link information given, which often uses relative path addressing.
2. The absolute, "Real Path" of the target, which has a corresponding result entry in the given FTree.
If a using software wants to use symbolic paths, for example to present them to the end user, such paths have to be assembled by the user's code in own responsibility. All information for doing this is provided in the resulting tree object
Doubly linked target files and directories are never a problem for this scanner. Each file is scanned only once. This especially prevents all sorts of problems that would otherwise occur with cyclic symbolic links.
Due to this, even the given start path of a search might not be found as a result in given FTree, because also start paths are converted to a Real Path.
The scan result may contain more than one resulting path. This happens, if a symbolic link targets a file or directory that is not recursively included in the start path. The resulting "Real Path" of the given start path is however always the first result added.

The latter is reflected with parameter resultPaths of this function, which is defined as a std::vector.

Note: As class FTree is based on class monomem::StringTree , using code is enabled to break this contract by adding entries below symbolic links. Other entities of this ALib Module will not break this contract.

Rescanning of Entries

Existing entries in the given tree are not overwritten. They might be scanned with "higher" FInfo::Qualities values; depending given parameters and how they had been scanned before. If the same "level" of scanning is provided, existing entries will not be scanned again. If a rescan of a certain path is wanted, then the target entry of that path has to be deleted prior to invoking this function. Due to the implementation of class FTree, repeated delete and scan operations will not cause any heap-memory activities (of-course, as long as no new entries are detected).

Platform Dependent Code Selection

File scanning is a platform dependent task and hence ALib switches provides two implementations:

A posix version for posix compatible OSes,
A version that relies on C++ std::filesystem.

The fallback version using std::filesystem has the following restrictions:

The only time available is the modification time of an entry. The creation time and last access time are always set to the same as the modification time, even on filesystems that support the other values.
The file time of symbolic links is always that of the target file. The C++ standard has no possibility to access the link's time itself.
The file time of broken symbolic links is set to the current time (time of scanning).
The size that directories occupy on disk can not be determined. Directory entries always report size 0.
The target of a symbolic that points to a non-accessible directory, can not be resolved to the a 'real' path, even if all other path components before are accessible. (This is true for the implementation of the standard library under GNU/Linux and Clang compiler at the time of writing this, 2024/02.)
Flag ScanParameters::CrossFileSystems is ignored. Crossing Filesystems can not be detected using purely standard library.
A files' owner and owning group is not determined. Instead, FInfo::UnknownID is set for both.
The scanning process is half as fast as in the Posix version. The reason for this is probably the internal allocation and de-allocation of many quite volatile string objects in the C++ standard library. Well, but it is still fast though!

Note: As for today, using this module under WindowsOS, will fall back to the C++ std::filesystem version. It may be that a future version will provide a native implementation of this target system. Volunteers from the community are welcome to contribute.