File Identification

Core file type detection methods. More...

Collaboration diagram for File Identification:

Functions
FileTypeT	Recognition::Magic::IdentifyFile (const std::filesystem::path &path) const
	Identify the type of a single file.
ExpectedFileTypeT	Recognition::Magic::IdentifyFile (const std::filesystem::path &path, const std::nothrow_t &tag) const noexcept
	Identify the type of a single file (noexcept version).
FileTypeMapT	Recognition::Magic::IdentifyFiles (const std::filesystem::path &directory, std::filesystem::directory_options option=std::filesystem::directory_options::follow_directory_symlink) const
	Identify all files in a directory.
FileTypeMapT	Recognition::Magic::IdentifyFiles (const std::filesystem::path &directory, ProgressTrackerT progress_tracker, std::filesystem::directory_options option=std::filesystem::directory_options::follow_directory_symlink) const
	Identify all files in a directory with progress tracking.
ExpectedFileTypeMapT	Recognition::Magic::IdentifyFiles (const std::filesystem::path &directory, const std::nothrow_t &tag, std::filesystem::directory_options option=std::filesystem::directory_options::follow_directory_symlink) const noexcept
	Identify all files in a directory (noexcept version).
ExpectedFileTypeMapT	Recognition::Magic::IdentifyFiles (const std::filesystem::path &directory, const std::nothrow_t &tag, ProgressTrackerT progress_tracker, std::filesystem::directory_options option=std::filesystem::directory_options::follow_directory_symlink) const noexcept
	Identify all files in a directory with progress tracking (noexcept version).
FileTypeMapT	Recognition::Magic::IdentifyFiles (const Utility::FileContainer auto &files) const
	Identify multiple files from a container.
FileTypeMapT	Recognition::Magic::IdentifyFiles (const Utility::FileContainer auto &files, ProgressTrackerT progress_tracker) const
	Identify multiple files with progress tracking.
ExpectedFileTypeMapT	Recognition::Magic::IdentifyFiles (const Utility::FileContainer auto &files, const std::nothrow_t &tag) const noexcept
	Identify multiple files from a container (noexcept version).
ExpectedFileTypeMapT	Recognition::Magic::IdentifyFiles (const Utility::FileContainer auto &files, const std::nothrow_t &tag, ProgressTrackerT progress_tracker) const noexcept
	Identify multiple files with progress tracking (noexcept version).

Detailed Description

Core file type detection methods.

Methods for identifying file types using magic number analysis.

Function Documentation

IdentifyFile() [1/2]

Magic::FileTypeT Recognition::Magic::IdentifyFile ( const std::filesystem::path & path ) const

nodiscard

Identify the type of a single file.

Analyzes the content of the specified file and returns its type based on magic number analysis.

Parameters

[in]

path

Path to the file to identify.

Returns

File type string (format depends on configured Flags).

Exceptions

MagicIsClosed	If the Magic instance is closed.
MagicDatabaseNotLoaded	If no database is loaded.
EmptyPath	If path is empty.
PathDoesNotExist	If path does not exist.
MagicIdentifyFileError	If identification fails.

Magic magic{Magic::Flags::Mime};
auto type = magic.IdentifyFile("/etc/passwd");
// type = "text/plain; charset=us-ascii"

See also

IdentifyFiles() for batch identification

Since

10.0.0

Examples

magic_examples.cpp.

IdentifyFile() [2/2]

Magic::ExpectedFileTypeT Recognition::Magic::IdentifyFile ( const std::filesystem::path & path, const std::nothrow_t & tag ) const

nodiscardnoexcept

Identify the type of a single file (noexcept version).

Parameters

[in]	path	Path to the file to identify.
[in]	tag	Pass std::nothrow to select this overload.

Returns

ExpectedFileTypeT containing the file type or error message.

auto result = magic.IdentifyFile("/path/to/file", std::nothrow);
if (result) {
    std::println("Type: {}", *result);
} else {
    std::println("Error: {}", result.error());
}

See also

ExpectedFileTypeT

Since

10.0.0

IdentifyFiles() [1/8]

ExpectedFileTypeMapT Recognition::Magic::IdentifyFiles ( const std::filesystem::path & directory, const std::nothrow_t & tag, ProgressTrackerT progress_tracker, std::filesystem::directory_options option = std::filesystem:: directory_options::follow_directory_symlink ) const

inlinenodiscardnoexcept

Identify all files in a directory with progress tracking (noexcept version).

Parameters

[in]	directory	Path to the directory to scan.
[in]	tag	Pass std::nothrow to select this overload.
[out]	progress_tracker	Shared progress tracker (must not be null).
[in]	option	Directory iteration options.

Returns

Map from file paths to expected results (type or error per file).

Since

10.0.0

IdentifyFiles() [2/8]

ExpectedFileTypeMapT Recognition::Magic::IdentifyFiles ( const std::filesystem::path & directory, const std::nothrow_t & tag, std::filesystem::directory_options option = std::filesystem:: directory_options::follow_directory_symlink ) const

inlinenodiscardnoexcept

Identify all files in a directory (noexcept version).

Parameters

[in]	directory	Path to the directory to scan.
[in]	tag	Pass std::nothrow to select this overload.
[in]	option	Directory iteration options.

Returns

Map from file paths to expected results (type or error per file).

See also

ExpectedFileTypeMapT

Since

10.0.0

IdentifyFiles() [3/8]

FileTypeMapT Recognition::Magic::IdentifyFiles ( const std::filesystem::path & directory, ProgressTrackerT progress_tracker, std::filesystem::directory_options option = std::filesystem:: directory_options::follow_directory_symlink ) const

inlinenodiscard

Identify all files in a directory with progress tracking.

Same as IdentifyFiles(directory, option) but with progress monitoring.

Parameters

[in]	directory	Path to the directory to scan.
[out]	progress_tracker	Shared progress tracker (must not be null).
[in]	option	Directory iteration options.

Returns

Map from file paths to their identified types.

Exceptions

NullTracker	If progress_tracker is null.
...	Same exceptions as IdentifyFiles(directory, option).

using namespace std::chrono_literals;
 
auto tracker = Utility::MakeSharedProgressTracker();
 
// Start identification in another thread
auto future = std::async([&magic, tracker] {
    return magic.IdentifyFiles("/large/directory", tracker);
});
 
// Monitor progress
while (!tracker->IsCompleted()) {
    std::println("Progress: {}", tracker->GetCompletionPercentage().ToString());
    std::this_thread::sleep_for(100ms);
}

See also

ProgressTrackerT

Utility::MakeSharedProgressTracker()

Since

10.0.0

IdentifyFiles() [4/8]

FileTypeMapT Recognition::Magic::IdentifyFiles ( const std::filesystem::path & directory, std::filesystem::directory_options option = std::filesystem:: directory_options::follow_directory_symlink ) const

inlinenodiscard

Identify all files in a directory.

Recursively scans a directory and identifies the type of each regular file.

Parameters

[in]	directory	Path to the directory to scan.
[in]	option	Directory iteration options (default: follow_directory_symlink).

Returns

Map from file paths to their identified types.

Exceptions

MagicIsClosed	If the Magic instance is closed.
MagicDatabaseNotLoaded	If no database is loaded.
EmptyPath	If directory path is empty.
PathDoesNotExist	If directory does not exist.
PathIsNotDirectory	If path is not a directory.
FilesystemError	If filesystem operation fails.
MagicIdentifyFileError	If identification fails for any file.

auto results = magic.IdentifyFiles("/path/to/directory");
for (const auto& [path, type] : results) {
    std::println("{} -> {}", path.string(), type);
}

See also

FileTypeMapT

Since

10.0.0

Examples

magic_examples.cpp.

IdentifyFiles() [5/8]

FileTypeMapT Recognition::Magic::IdentifyFiles ( const Utility::FileContainer auto & files ) const

inlinenodiscard

Identify multiple files from a container.

Identifies the type of each file in the provided container.

Template Parameters

Container

type satisfying Utility::FileContainer concept.

Parameters

[in]

files

Container of file paths to identify.

Returns

Map from file paths to their identified types.

Exceptions

MagicIsClosed	If the Magic instance is closed.
MagicDatabaseNotLoaded	If no database is loaded.
EmptyPath	If any file path is empty.
PathDoesNotExist	If any file does not exist.
MagicIdentifyFileError	If identification fails for any file.

std::vector<std::filesystem::path> files = {
    "/path/to/file1.txt",
    "/path/to/file2.png"
};
auto results = magic.IdentifyFiles(files);

See also

Utility::FileContainer

Since

10.0.0

IdentifyFiles() [6/8]

ExpectedFileTypeMapT Recognition::Magic::IdentifyFiles ( const Utility::FileContainer auto & files, const std::nothrow_t & tag ) const

inlinenodiscardnoexcept

Identify multiple files from a container (noexcept version).

Parameters

[in]	files	Container of file paths to identify.
[in]	tag	Pass std::nothrow to select this overload.

Returns

Map from file paths to expected results (type or error per file).

Since

10.0.0

IdentifyFiles() [7/8]

ExpectedFileTypeMapT Recognition::Magic::IdentifyFiles ( const Utility::FileContainer auto & files, const std::nothrow_t & tag, ProgressTrackerT progress_tracker ) const

inlinenodiscardnoexcept

Identify multiple files with progress tracking (noexcept version).

Parameters

[in]	files	Container of file paths to identify.
[in]	tag	Pass std::nothrow to select this overload.
[out]	progress_tracker	Shared progress tracker (must not be null).

Returns

Map from file paths to expected results (type or error per file).

Since

10.0.0

IdentifyFiles() [8/8]

FileTypeMapT Recognition::Magic::IdentifyFiles ( const Utility::FileContainer auto & files, ProgressTrackerT progress_tracker ) const

inlinenodiscard

Identify multiple files with progress tracking.

Parameters

[in]	files	Container of file paths to identify.
[out]	progress_tracker	Shared progress tracker (must not be null).

Returns

Map from file paths to their identified types.

Exceptions

NullTracker	If progress_tracker is null.
...	Same exceptions as IdentifyFiles(files).

Since

10.0.0