alib::files Namespace Reference

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
	This namespace implements internals of namespace alib::files.

Type Index:
struct	FFilter
class	File
class	FileExpressions
class	FilesCamp
class	FInfo
	The entry type which is embedded in each tree node. More...
class	FTree
struct	FTreeListener
class	OwnerAndGroupResolver
struct	ResultsPaths
struct	ScanParameters
	Input parameters to function ScanFiles. More...
struct	TSharedFTree
class	TTextFile

Type Definition Index:
using	SPFileFilter = std::shared_ptr<FFilter>
	A shared pointer to a filter.

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)())
void	FFormat_File (const alib::Box &box, const alib::String &formatSpec, alib::NumberFormat &nf, alib::AString &target)
ALIB_API FInfo::Qualities	ScanFiles (FTree &tree, ScanParameters &parameters, std::vector< ResultsPaths > &resultPaths, SharedLock *lock)
FInfo::Qualities	ScanFiles (SharedFTree &tree, ScanParameters &parameters, std::vector< ResultsPaths > &resultPaths)

Variable Index:
String	DBG_DUMP_FORMAT
String	DBG_FILES_SCAN_VERBOSE_LOG_FORMAT

Type Definition Details:

SPFileFilter

using SPFileFilter = std::shared_ptr<FFilter>

A shared pointer to a filter.

Definition at line 49 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.
This function is only available with debug-compilations.

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.

FFormat_File()

void FFormat_File	(	const Box &	box,
		const String &	formatSpec,
		NumberFormat &	nf,
		AString &	target )

This implementation of boxing function FFormat for objects of type File, simply invokes the method File::Format and thus, using the format specification is given with that method.

Note that the NumberFormat instance used for formatting file sizes and similar, does not use the instance given with parameter nf. Instead, the instance retrieved with FTree::GetNumberFormat is used. This feature enables to determine the number format separately for file data output, independent of the settings the formater uses.

If the parameter formatSpec is empty, the string "ta h on gn s dm nal" is used, which is resourced in camp FILES under the key "FFMT".

Parameters

box	The box containing the file object.
formatSpec	The format string.
nf	The number format specification to use.
target	The target string to write to.

Definition at line 395 of file file.cpp.

Here is the call graph for this function:

ScanFiles() [1/2]

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

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 a scan is always stored using the "Real Path" of the entry. This means that 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 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 on 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 before 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 uses one of two different implementations:

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

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

• The only time attribute available is the modification time of an entry. Fields BDate, CDate, and ADate 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 cannot be determined. Directory entries always report size 0.
• The target of a symbolic link which points to a non-accessible directory, cannot be resolved to 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 cannot be detected using purely the 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 deallocation 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.

Parameters

tree	The tree to fill.
parameters	The input parameters to determine the scan process.
resultPaths	A container to add the resulting list of 'real' paths and corresponding start nodes found during the search. The first entry added by this function is always the 'real'-version of field StartPath of the given params struct. Further paths/nodes pairs are created when symbolic links are found and followed.
lock	Pointer to an (optional) SharedLock. The overloaded version of this function that accepts SharedFTree sets this to the instance found in the shared tree. This parameter is available (and to be passed) only if the module ALib Threads is included in the ALib Distribution.

Returns

Scan quality code of the tree node of the first resulting path, hence of the node referred to by ScanParameters::StartPath. If this is erroneous, the start path was invalid, for example, not accessible, a broken link, a circular link, etc.

ScanFiles() [2/2]

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

inline

Invokes ScanFiles( FTree&, ScanParameters&, std::vector<ResultsPaths>&,SharedLock*) passing the lock included in the given SharedFTree as parameter lock.

Parameters

tree	The shared tree to fill.
parameters	The input parameters to determine the scan process.
resultPaths	The result paths.

Returns

Scan quality code of the first resulting path.

Definition at line 293 of file fscanner.hpp.

Here is the call graph for this function:

Variable Details:

DBG_DUMP_FORMAT

String DBG_DUMP_FORMAT

extern

The format string used with namespace function DbgDump.
Defaults to "{:ta h{2,r} on{10,r} gn{10,r} s(IEC){10,r} dm qqq FxFa (rd{3r}' D' rf{3r}' F' re{2r}' EA' rb{2r}'BL) 'nf l}\n"
This global variable is only available with debug-compilations.

DBG_FILES_SCAN_VERBOSE_LOG_FORMAT

String DBG_FILES_SCAN_VERBOSE_LOG_FORMAT

extern

The format string used with verbose logging to domain /ALIB/FILES/SCAN during with namespace function ScanFiles.
Defaults to " {:ta h{2,r} on{10,r} gn{10,r} s(IEC){10,r} dm qqq nf l}"