The magic class provides a C++ wrapper over the Magic Number Recognition Library. More...

#include <magic.hpp>

Classes
class	magic_private

Public Types
enum	flags : unsigned long long { none = 0ULL , debug = 1ULL << 0 , symlink = 1ULL << 1 , compress = 1ULL << 2 , devices = 1ULL << 3 , mime_type = 1ULL << 4 , continue_search = 1ULL << 5 , check_database = 1ULL << 6 , preserve_atime = 1ULL << 7 , raw = 1ULL << 8 , error = 1ULL << 9 , mime_encoding = 1ULL << 10 , mime = 1ULL << 11 , apple = 1ULL << 12 , extension = 1ULL << 13 , compress_transp = 1ULL << 14 , no_compress_fork = 1ULL << 15 , nodesc = 1ULL << 16 , no_check_compress = 1ULL << 17 , no_check_tar = 1ULL << 18 , no_check_soft = 1ULL << 19 , no_check_apptype = 1ULL << 20 , no_check_elf = 1ULL << 21 , no_check_text = 1ULL << 22 , no_check_cdf = 1ULL << 23 , no_check_csv = 1ULL << 24 , no_check_tokens = 1ULL << 25 , no_check_encoding = 1ULL << 26 , no_check_json = 1ULL << 27 , no_check_simh = 1ULL << 28 , no_check_builtin = 1ULL << 29 }
	The flags enums are used for configuring the flags of a magic. More...

enum class	parameters : std::size_t { indir_max = 0uz , name_max = 1uz , elf_phnum_max = 2uz , elf_shnum_max = 3uz , elf_notes_max = 4uz , regex_max = 5uz , bytes_max = 6uz , encoding_max = 7uz , elf_shsize_max = 8uz , mag_warn_max = 9uz }
	The parameters enums are used for displaying or modifying the parameters of a magic. More...

using	flags_mask_t = std::bitset<30uz>
	Bitmask type representing a set of magic::flags used to configure the magic instance.

using	file_type_t = std::string
	String type representing the detected type of a file.

using	error_message_t = std::string
	String type representing an error message from file identification.

using	expected_file_type_t = std::expected<file_type_t, error_message_t>
	Result type for file identification, containing either a file type or an error message.

using	types_of_files_t = std::map<std::filesystem::path, file_type_t>
	Map from file paths to their detected types.

using	type_of_a_file_t = types_of_files_t::value_type
	Key-value pair representing a single file and its detected type.

using	expected_types_of_files_t
	Map from file paths to expected file type results (success or error).

using	expected_type_of_a_file_t = expected_types_of_files_t::value_type
	Key-value pair representing a single file and its expected file type result.

using	tracker_t = utility::shared_progress_tracker_t
	Alias for a shared pointer to a progress tracker used for monitoring file identification progress.

using	flags_container_t = std::vector<flags>
	Container type holding a collection of magic::flags.

using	parameter_value_map_t = std::map<parameters, std::size_t>
	Map from magic::parameters to their corresponding values.

using	parameter_value_t = parameter_value_map_t::value_type
	Key-value pair representing a single parameter and its value.

Public Member Functions
	magic () noexcept
	Construct magic without opening it.

	magic (flags_mask_t flags_mask, const std::filesystem::path &database_file=default_database_file)
	Construct magic, open it using the flags and load the magic database file.

	magic (flags_mask_t flags_mask, const std::nothrow_t &tag, const std::filesystem::path &database_file=default_database_file) noexcept
	Construct magic, open it using the flags and load the magic database file, noexcept version.

	magic (const flags_container_t &flags_container, const std::filesystem::path &database_file=default_database_file)
	Construct magic, open it using the flags and load the magic database file.

	magic (const flags_container_t &flags_container, const std::nothrow_t &tag, const std::filesystem::path &database_file=default_database_file) noexcept
	Construct magic, open it using the flags and load the magic database file, noexcept version.

	magic (magic &&other) noexcept
	Move construct magic.

	magic (const magic &)=delete
	Deleted copy constructor.

magic &	operator= (magic &&other) noexcept
	Move assign to this magic.

magic &	operator= (const magic &)=delete
	Deleted copy assignment.

	~magic ()
	Destruct magic.

	operator bool () const noexcept
	Used for testing whether magic is valid for identifying file types or not.

void	close () noexcept
	Close magic.

flags_container_t	get_flags () const
	Get the flags of magic.

std::optional< flags_container_t >	get_flags (const std::nothrow_t &tag) const noexcept
	Get the flags of magic, noexcept version.

std::size_t	get_parameter (parameters parameter) const
	Get the value of a parameter of magic.

std::optional< std::size_t >	get_parameter (parameters parameter, const std::nothrow_t &tag) const noexcept
	Get the value of a parameter of magic, noexcept version.

parameter_value_map_t	get_parameters () const
	Get the values of all parameters of magic.

std::optional< parameter_value_map_t >	get_parameters (const std::nothrow_t &tag) const noexcept
	Get the values of all parameters of magic, noexcept version.

file_type_t	identify_file (const std::filesystem::path &path) const
	Identify the type of a file.

expected_file_type_t	identify_file (const std::filesystem::path &path, const std::nothrow_t &tag) const noexcept
	Identify the type of a file, noexcept version.

types_of_files_t	identify_files (const std::filesystem::path &directory, std::filesystem::directory_options option=std::filesystem::directory_options::follow_directory_symlink) const
	Identify the types of all files in a directory.

types_of_files_t	identify_files (const std::filesystem::path &directory, tracker_t tracker, std::filesystem::directory_options option=std::filesystem::directory_options::follow_directory_symlink) const
	Identify the types of all files in a directory with progress tracking.

expected_types_of_files_t	identify_files (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 the types of all files in a directory, noexcept version.

expected_types_of_files_t	identify_files (const std::filesystem::path &directory, const std::nothrow_t &tag, tracker_t tracker, std::filesystem::directory_options option=std::filesystem::directory_options::follow_directory_symlink) const noexcept
	Identify the types of all files in a directory with progress tracking, noexcept version.

types_of_files_t	identify_files (const utility::file_container auto &files) const
	Identify the types of files.

types_of_files_t	identify_files (const utility::file_container auto &files, tracker_t tracker) const
	Identify the types of files with progress tracking.

expected_types_of_files_t	identify_files (const utility::file_container auto &files, const std::nothrow_t &tag) const noexcept
	Identify the types of files, noexcept version.

expected_types_of_files_t	identify_files (const utility::file_container auto &files, const std::nothrow_t &tag, tracker_t tracker) const noexcept
	Identify the types of files with progress tracking, noexcept version.

bool	is_database_loaded () const noexcept
	Used for testing whether a magic database is loaded or not.

bool	is_open () const noexcept
	Used for testing whether magic is open or closed.

bool	is_valid () const noexcept
	Used for testing whether magic is valid for identifying file types or not.

void	load_database_file (const std::filesystem::path &database_file=default_database_file)
	Load a magic database file.

bool	load_database_file (const std::nothrow_t &tag, const std::filesystem::path &database_file=default_database_file) noexcept
	Load a magic database file, noexcept version.

void	open (flags_mask_t flags_mask)
	Open magic using the flags.

bool	open (flags_mask_t flags_mask, const std::nothrow_t &tag) noexcept
	Open magic using the flags, noexcept version.

void	open (const flags_container_t &flags_container)
	Open magic using the flags.

bool	open (const flags_container_t &flags_container, const std::nothrow_t &tag) noexcept
	Open magic using the flags, noexcept version.

void	set_flags (flags_mask_t flags_mask)
	Set the flags of magic.

bool	set_flags (flags_mask_t flags_mask, const std::nothrow_t &tag) noexcept
	Set the flags of magic, noexcept version.

void	set_flags (const flags_container_t &flags_container)
	Set the flags of magic.

bool	set_flags (const flags_container_t &flags_container, const std::nothrow_t &tag) noexcept
	Set the flags of magic, noexcept version.

void	set_parameter (parameters parameter, std::size_t value)
	Set the value of a parameter of magic.

bool	set_parameter (parameters parameter, std::size_t value, const std::nothrow_t &tag) noexcept
	Set the value of a parameter of magic, noexcept version.

void	set_parameters (const parameter_value_map_t &parameters)
	Set the values of the parameters of magic.

bool	set_parameters (const parameter_value_map_t &parameters, const std::nothrow_t &tag) noexcept
	Set the values of the parameters of magic, noexcept version.

Static Public Member Functions
static bool	check (const std::filesystem::path &database_file=default_database_file) noexcept
	Check the validity of entries in the colon separated database files passed in as database_file.

static bool	compile (const std::filesystem::path &database_file=default_database_file) noexcept
	Compile the colon separated list of database files passed in as database_file.

static std::string	get_version () noexcept
	Get the version of the Magic Number Recognition Library.

Static Public Attributes
static std::string_view	default_database_file {DEFAULT_DATABASE_FILE}
	The path of the default database file.

Private Types
using	default_file_container_t = std::vector<std::filesystem::path>

Private Member Functions
types_of_files_t	identify_directory_impl (const std::filesystem::path &directory, std::filesystem::directory_options option, tracker_t tracker=utility::make_shared_progress_tracker()) const

expected_types_of_files_t	identify_directory_impl (const std::filesystem::path &directory, const std::nothrow_t &tag, std::filesystem::directory_options option, tracker_t tracker=utility::make_shared_progress_tracker()) const noexcept

types_of_files_t	identify_container_impl (const default_file_container_t &files, tracker_t tracker=utility::make_shared_progress_tracker()) const

expected_types_of_files_t	identify_container_impl (const default_file_container_t &files, const std::nothrow_t &tag, tracker_t tracker=utility::make_shared_progress_tracker()) const noexcept

Private Attributes
std::unique_ptr< magic_private >	m_impl

Friends
std::string	to_string (magic::flags flag)
	Convert the magic::flags to string.

std::string	to_string (magic::parameters parameter)
	Convert the magic::parameters to string.

Detailed Description

The magic class provides a C++ wrapper over the Magic Number Recognition Library.

Note

To use the magic class for file type identification, ensure the following:

The magic instance must be opened.
A magic database file must be successfully loaded. Only after these steps is the instance considered valid for identifying file types.

Member Typedef Documentation

◆ default_file_container_t

using recognition::magic::default_file_container_t = std::vector<std::filesystem::path>

private

◆ error_message_t

using recognition::magic::error_message_t = std::string

String type representing an error message from file identification.

◆ expected_file_type_t

using recognition::magic::expected_file_type_t = std::expected<file_type_t, error_message_t>

Result type for file identification, containing either a file type or an error message.

◆ expected_type_of_a_file_t

using recognition::magic::expected_type_of_a_file_t = expected_types_of_files_t::value_type

Key-value pair representing a single file and its expected file type result.

◆ expected_types_of_files_t

using recognition::magic::expected_types_of_files_t

Initial value:

 std::map<
        std::filesystem::path,
        expected_file_type_t>

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

◆ file_type_t

using recognition::magic::file_type_t = std::string

String type representing the detected type of a file.

◆ flags_container_t

using recognition::magic::flags_container_t = std::vector<flags>

Container type holding a collection of magic::flags.

◆ flags_mask_t

using recognition::magic::flags_mask_t = std::bitset<30uz>

Bitmask type representing a set of magic::flags used to configure the magic instance.

◆ parameter_value_map_t

using recognition::magic::parameter_value_map_t = std::map<parameters, std::size_t>

Map from magic::parameters to their corresponding values.

◆ parameter_value_t

using recognition::magic::parameter_value_t = parameter_value_map_t::value_type

Key-value pair representing a single parameter and its value.

◆ tracker_t

using recognition::magic::tracker_t = utility::shared_progress_tracker_t

Alias for a shared pointer to a progress tracker used for monitoring file identification progress.

See also: utility::progress_tracker

◆ type_of_a_file_t

using recognition::magic::type_of_a_file_t = types_of_files_t::value_type

Key-value pair representing a single file and its detected type.

◆ types_of_files_t

using recognition::magic::types_of_files_t = std::map<std::filesystem::path, file_type_t>

Map from file paths to their detected types.

Member Enumeration Documentation

◆ flags

enum recognition::magic::flags : unsigned long long

The flags enums are used for configuring the flags of a magic.

Note: The flags enums are suitable for bitwise or operations.

Enumerator
none	0ULL	No special handling.
debug	1ULL << 0	Print debugging messages to stderr.
symlink	1ULL << 1	If the file queried is a symlink, follow it.
compress	1ULL << 2	If the file is compressed, unpack it and look at the contents.
devices	1ULL << 3	If the file is a block or character special device, then open the device and try to look in its contents.
mime_type	1ULL << 4	Return a MIME type string, instead of a textual description.
continue_search	1ULL << 5	Return all matches, not just the first.
check_database	1ULL << 6	Check the magic database for consistency and print warnings to stderr.
preserve_atime	1ULL << 7	On systems that support utime(3) or utimes(2), attempt to preserve the access time of files analysed.
raw	1ULL << 8	Don't translate unprintable characters to a \ooo octal representation.
error	1ULL << 9	Treat operating system errors while trying to open files and follow symlinks as real errors, instead of printing them in the magic buffer.
mime_encoding	1ULL << 10	Return a MIME encoding, instead of a textual description.
mime	1ULL << 11	A shorthand for mime_type\|mime_encoding.
apple	1ULL << 12	Return the Apple creator and type.
extension	1ULL << 13	Return a slash-separated list of extensions for this file type.
compress_transp	1ULL << 14	Don't report on compression, only report about the uncompressed data.
no_compress_fork	1ULL << 15	Don't allow decompressors that use fork.
nodesc	1ULL << 16	A shorthand for extension\|mime\|apple
no_check_compress	1ULL << 17	Don't look inside compressed files.
no_check_tar	1ULL << 18	Don't examine tar files.
no_check_soft	1ULL << 19	Don't consult magic files.
no_check_apptype	1ULL << 20	Don't check for EMX application type (only on EMX).
no_check_elf	1ULL << 21	Don't print ELF details.
no_check_text	1ULL << 22	Don't check for various types of text files.
no_check_cdf	1ULL << 23	Don't get extra information on MS Composite Document Files.
no_check_csv	1ULL << 24	Don't examine CSV files.
no_check_tokens	1ULL << 25	Don't look for known tokens inside ascii files.
no_check_encoding	1ULL << 26	Don't check text encodings.
no_check_json	1ULL << 27	Don't examine JSON files.
no_check_simh	1ULL << 28	Don't examine SIMH tape files.
no_check_builtin	1ULL << 29	No built-in tests; only consult the magic file.

◆ parameters

enum class recognition::magic::parameters : std::size_t

strong

The parameters enums are used for displaying or modifying the parameters of a magic.

Enumerator
indir_max	0uz	Recursion limit for indirection (default is 15).
name_max	1uz	Use limit for name/use magic (default is 30).
elf_phnum_max	2uz	Max ELF program sections processed (default is 128).
elf_shnum_max	3uz	Max ELF sections processed (default is 32768).
elf_notes_max	4uz	Max ELF notes processed (default is 256).
regex_max	5uz	Max length limit for REGEX searches (default is 8192).
bytes_max	6uz	Max bytes to look inside file (default is 7340032).
encoding_max	7uz	Max bytes to scan for encoding (default is 1048576).
elf_shsize_max	8uz	Max ELF section size (default is 134217728).
mag_warn_max	9uz	Max warnings to tolerate in a magic file (default is 64).

Constructor & Destructor Documentation

◆ magic() [1/7]

recognition::magic::magic ( )

noexcept

Construct magic without opening it.

Note: This magic is not valid for identifying file types until it is opened and a magic database file is loaded.

◆ magic() [2/7]

recognition::magic::magic	(	flags_mask_t	flags_mask,
		const std::filesystem::path &	database_file = default_database_file )

explicit

Construct magic, open it using the flags and load the magic database file.

Parameters

[in]	flags_mask	One of the flags enums or bitwise or of the flags enums.
[in]	database_file	The path of magic database file, default is default_database_file.

Exceptions

magic_open_error	if opening magic fails.
empty_path	if the path of the database file is empty.
path_does_not_exist	if the path of the database file does not exist.
path_is_not_regular_file	if the path of the magic database file is not a file.
magic_load_database_file_error	if loading the magic database file fails.

Note: load_database_file() adds “.mgc” to the database filename as appropriate.

◆ magic() [3/7]

recognition::magic::magic	(	flags_mask_t	flags_mask,
		const std::nothrow_t &	tag,
		const std::filesystem::path &	database_file = default_database_file )

noexcept

Construct magic, open it using the flags and load the magic database file, noexcept version.

Parameters

[in]	flags_mask	One of the flags enums or bitwise or of the flags enums.
[in]	tag	Tag for non-throwing overload.
[in]	database_file	The path of magic database file, default is default_database_file.

Note: load_database_file() adds “.mgc” to the database filename as appropriate.

◆ magic() [4/7]

recognition::magic::magic	(	const flags_container_t &	flags_container,
		const std::filesystem::path &	database_file = default_database_file )

explicit

Construct magic, open it using the flags and load the magic database file.

Parameters

[in]	flags_container	Flags.
[in]	database_file	The path of magic database file, default is default_database_file.

Exceptions

magic_open_error	if opening magic fails.
empty_path	if the path of the database file is empty.
path_does_not_exist	if the path of the database file does not exist.
path_is_not_regular_file	if the path of the magic database file is not a file.
magic_load_database_file_error	if loading the magic database file fails.

Note: load_database_file() adds “.mgc” to the database filename as appropriate.

◆ magic() [5/7]

recognition::magic::magic	(	const flags_container_t &	flags_container,
		const std::nothrow_t &	tag,
		const std::filesystem::path &	database_file = default_database_file )

noexcept

Construct magic, open it using the flags and load the magic database file, noexcept version.

Parameters

[in]	flags_container	Flags.
[in]	tag	Tag for non-throwing overload.
[in]	database_file	The path of magic database file, default is default_database_file.

Note: load_database_file() adds “.mgc” to the database filename as appropriate.

◆ magic() [6/7]

recognition::magic::magic ( magic && other )

noexcept

Move construct magic.

Note: After move construction, the moved-from object (other) is closed. It cannot be used for identifying file types until it is reopened and a magic database file is loaded.

◆ magic() [7/7]

recognition::magic::magic ( const magic & )

delete

Deleted copy constructor.

◆ ~magic()

recognition::magic::~magic ( )

default

Destruct magic.

Member Function Documentation

◆ check()

bool recognition::magic::check ( const std::filesystem::path & database_file = default_database_file )

staticnodiscardnoexcept

Check the validity of entries in the colon separated database files passed in as database_file.

Parameters

[in] database_file The file to check, default is default_database_file.

Returns: True if the database_file has valid entries, false otherwise.

◆ close()

void recognition::magic::close ( )

noexcept

Close magic.

Note: magic cannot be used for identifying file types until it is reopened and a magic database file is loaded.

◆ compile()

bool recognition::magic::compile ( const std::filesystem::path & database_file = default_database_file )

staticnodiscardnoexcept

Compile the colon separated list of database files passed in as database_file.

Parameters

[in] database_file The file to compile, default is default_database_file.

Returns: True on success, false otherwise.

Note: The compiled files created are named from the basename of each file argument with “.mgc” appended to it.

◆ get_flags() [1/2]

magic::flags_container_t recognition::magic::get_flags ( ) const

nodiscard

Get the flags of magic.

Returns: flags_container_t

Exceptions

magic_is_closed if magic is closed.

◆ get_flags() [2/2]

std::optional< magic::flags_container_t > recognition::magic::get_flags ( const std::nothrow_t & tag ) const

nodiscardnoexcept

Get the flags of magic, noexcept version.

Parameters

[in] tag Tag for non-throwing overload.

Returns: flags_container_t or std::nullopt if magic is closed.

◆ get_parameter() [1/2]

std::size_t recognition::magic::get_parameter ( magic::parameters parameter ) const

nodiscard

Get the value of a parameter of magic.

Parameters

[in] parameter One of the parameters enum.

Returns: Value of the desired parameter.

Exceptions

magic_is_closed if magic is closed.

◆ get_parameter() [2/2]

std::optional< std::size_t > recognition::magic::get_parameter	(	parameters	parameter,
		const std::nothrow_t &	tag ) const

nodiscardnoexcept

Get the value of a parameter of magic, noexcept version.

Parameters

[in]	parameter	One of the parameters enum.
[in]	tag	Tag for non-throwing overload.

Returns: Value of the desired parameter or std::nullopt if magic is closed.

◆ get_parameters() [1/2]

magic::parameter_value_map_t recognition::magic::get_parameters ( ) const

nodiscard

Get the values of all parameters of magic.

Returns: <parameter, value> map.

Exceptions

magic_is_closed if magic is closed.

◆ get_parameters() [2/2]

std::optional< magic::parameter_value_map_t > recognition::magic::get_parameters ( const std::nothrow_t & tag ) const

nodiscardnoexcept

Get the values of all parameters of magic, noexcept version.

Parameters

[in] tag Tag for non-throwing overload.

Returns: <parameter, value> map or std::nullopt if magic is closed.

◆ get_version()

std::string recognition::magic::get_version ( )

staticnodiscardnoexcept

Get the version of the Magic Number Recognition Library.

Returns: The version number as a string.

◆ identify_container_impl() [1/2]

magic::expected_types_of_files_t recognition::magic::identify_container_impl	(	const default_file_container_t &	files,
		const std::nothrow_t &	tag,
		tracker_t	tracker = utility::make_shared_progress_tracker() ) const

nodiscardprivatenoexcept

◆ identify_container_impl() [2/2]

magic::types_of_files_t recognition::magic::identify_container_impl	(	const default_file_container_t &	files,
		tracker_t	tracker = utility::make_shared_progress_tracker() ) const

nodiscardprivate

◆ identify_directory_impl() [1/2]

magic::expected_types_of_files_t recognition::magic::identify_directory_impl	(	const std::filesystem::path &	directory,
		const std::nothrow_t &	tag,
		std::filesystem::directory_options	option,
		tracker_t	tracker = utility::make_shared_progress_tracker() ) const

nodiscardprivatenoexcept

◆ identify_directory_impl() [2/2]

magic::types_of_files_t recognition::magic::identify_directory_impl	(	const std::filesystem::path &	directory,
		std::filesystem::directory_options	option,
		tracker_t	tracker = utility::make_shared_progress_tracker() ) const

nodiscardprivate

◆ identify_file() [1/2]

magic::file_type_t recognition::magic::identify_file ( const std::filesystem::path & path ) const

nodiscard

Identify the type of a file.

Parameters

[in] path The path of the file.

Returns: The type of the file as a string.

Exceptions

magic_is_closed	if magic is closed.
magic_database_not_loaded	if the magic database is not loaded.
empty_path	if the path of the file is empty.
path_does_not_exist	if the path of the file does not exist.
magic_identify_file_error	if identifying the type of the file fails.

◆ identify_file() [2/2]

magic::expected_file_type_t recognition::magic::identify_file	(	const std::filesystem::path &	path,
		const std::nothrow_t &	tag ) const

nodiscardnoexcept

Identify the type of a file, noexcept version.

Parameters

[in]	path	The path of the file.
[in]	tag	Tag for non-throwing overload.

Returns: The type of the file or the error message.

◆ identify_files() [1/8]

expected_types_of_files_t recognition::magic::identify_files	(	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 the types of all files in a directory, noexcept version.

Parameters

[in]	directory	The path of the directory.
[in]	tag	Tag for non-throwing overload.
[in]	option	The directory iteration option, default is follow_directory_symlink.

Returns: The types of each file as a map or an empty map on failure.

◆ identify_files() [2/8]

expected_types_of_files_t recognition::magic::identify_files	(	const std::filesystem::path &	directory,
		const std::nothrow_t &	tag,
		tracker_t	tracker,
		std::filesystem::directory_options	option = std::filesystem:: directory_options::follow_directory_symlink ) const

inlinenodiscardnoexcept

Identify the types of all files in a directory with progress tracking, noexcept version.

Parameters

[in]	directory	The path of the directory.
[in]	tag	Tag for non-throwing overload.
[out]	tracker	The progress tracker to track the progress of the identification. Must not be null.
[in]	option	The directory iteration option, default is follow_directory_symlink.

Returns: The types of each file as a map or an empty map on failure.

◆ identify_files() [3/8]

types_of_files_t recognition::magic::identify_files	(	const std::filesystem::path &	directory,
		std::filesystem::directory_options	option = std::filesystem:: directory_options::follow_directory_symlink ) const

inlinenodiscard

Identify the types of all files in a directory.

Parameters

[in]	directory	The path of the directory.
[in]	option	The directory iteration option, default is follow_directory_symlink.

Returns: The types of each file as a map.

Exceptions

magic_is_closed	if magic is closed.
magic_database_not_loaded	if the magic database is not loaded.
empty_path	if the path of the directory is empty.
path_does_not_exist	if the path of the directory does not exist.
path_is_not_directory	if the path of the directory is not a directory.
filesystem_error	if the underlying std::filesystem OS API fails.
magic_identify_file_error	if identifying the type of the file fails.

◆ identify_files() [4/8]

types_of_files_t recognition::magic::identify_files	(	const std::filesystem::path &	directory,
		tracker_t	tracker,
		std::filesystem::directory_options	option = std::filesystem:: directory_options::follow_directory_symlink ) const

inlinenodiscard

Identify the types of all files in a directory with progress tracking.

Parameters

[in]	directory	The path of the directory.
[out]	tracker	The progress tracker to track the progress of the identification. Must not be null.
[in]	option	The directory iteration option, default is follow_directory_symlink.

Returns: The types of each file as a map.

Exceptions

magic_is_closed	if magic is closed.
magic_database_not_loaded	if the magic database is not loaded.
empty_path	if the path of the directory is empty.
path_does_not_exist	if the path of the directory does not exist.
path_is_not_directory	if the path of the directory is not a directory.
null_tracker	if the tracker is null.
filesystem_error	if the underlying std::filesystem OS API fails.
magic_identify_file_error	if identifying the type of the file fails.

◆ identify_files() [5/8]

types_of_files_t recognition::magic::identify_files ( const utility::file_container auto & files ) const

inlinenodiscard

Identify the types of files.

Parameters

[in] files The container that holds the paths of the files.

Returns: The types of each file as a map.

Exceptions

magic_is_closed	if magic is closed.
magic_database_not_loaded	if the magic database is not loaded.
empty_path	if the path of the file is empty.
path_does_not_exist	if the path of the file does not exist.
magic_identify_file_error	if identifying the type of the file fails.

◆ identify_files() [6/8]

expected_types_of_files_t recognition::magic::identify_files	(	const utility::file_container auto &	files,
		const std::nothrow_t &	tag ) const

inlinenodiscardnoexcept

Identify the types of files, noexcept version.

Parameters

[in]	files	The container that holds the paths of the files.
[in]	tag	Tag for non-throwing overload.

Returns: The types of each file as a map or an empty map on failure.

◆ identify_files() [7/8]

expected_types_of_files_t recognition::magic::identify_files	(	const utility::file_container auto &	files,
		const std::nothrow_t &	tag,
		tracker_t	tracker ) const

inlinenodiscardnoexcept

Identify the types of files with progress tracking, noexcept version.

Parameters

[in]	files	The container that holds the paths of the files.
[in]	tag	Tag for non-throwing overload.
[out]	tracker	The progress tracker to track the progress of the identification.

Returns: The types of each file as a map or an empty map on failure.

◆ identify_files() [8/8]

types_of_files_t recognition::magic::identify_files	(	const utility::file_container auto &	files,
		tracker_t	tracker ) const

inlinenodiscard

Identify the types of files with progress tracking.

Parameters

[in]	files	The container that holds the paths of the files.
[out]	tracker	The progress tracker to track the progress of the identification.

Returns: The types of each file as a map.

Exceptions

magic_is_closed	if magic is closed.
magic_database_not_loaded	if the magic database is not loaded.
empty_path	if the path of the file is empty.
path_does_not_exist	if the path of the file does not exist.
null_tracker	if the tracker is null.
magic_identify_file_error	if identifying the type of the file fails.

◆ is_database_loaded()

bool recognition::magic::is_database_loaded ( ) const

nodiscardnoexcept

Used for testing whether a magic database is loaded or not.

Returns: True if a magic database is loaded, false otherwise.

◆ is_open()

bool recognition::magic::is_open ( ) const

nodiscardnoexcept

Used for testing whether magic is open or closed.

Returns: True if magic is open, false otherwise.

◆ is_valid()

bool recognition::magic::is_valid ( ) const

nodiscardnoexcept

Used for testing whether magic is valid for identifying file types or not.

Returns: True if the magic is valid, i.e., it is open and a magic database file is loaded; false otherwise.

◆ load_database_file() [1/2]

void recognition::magic::load_database_file ( const std::filesystem::path & database_file = default_database_file )

Load a magic database file.

Parameters

[in] database_file The path of the magic database file, default is default_database_file.

Exceptions

magic_is_closed	if magic is closed.
empty_path	if the path of the database file is empty.
path_does_not_exist	if the path of the database file does not exist.
path_is_not_regular_file	if the path of the database file is not a file.
magic_load_database_file_error	if loading the database file fails.

Note: load_database_file() adds “.mgc” to the database filename as appropriate.

◆ load_database_file() [2/2]

bool recognition::magic::load_database_file	(	const std::nothrow_t &	tag,
		const std::filesystem::path &	database_file = default_database_file )

nodiscardnoexcept

Load a magic database file, noexcept version.

Parameters

[in]	tag	Tag for non-throwing overload.
[in]	database_file	The path of the magic database file, default is default_database_file.

Returns: True on success, false otherwise.

Note: load_database_file() adds “.mgc” to the database filename as appropriate.

◆ open() [1/4]

void recognition::magic::open ( const flags_container_t & flags_container )

Open magic using the flags.

Parameters

[in] flags_container Flags.

Exceptions

magic_open_error if opening magic fails.

Note: If magic is open, it will be reopened using the flags after closing it.; A magic database file must be loaded after opening magic.

◆ open() [2/4]

bool recognition::magic::open	(	const flags_container_t &	flags_container,
		const std::nothrow_t &	tag )

nodiscardnoexcept

Open magic using the flags, noexcept version.

Parameters

[in]	flags_container	Flags.
[in]	tag	Tag for non-throwing overload.

Returns: True on success, false otherwise.

Note: If magic is open, it will be reopened using the flags after closing it.; A magic database file must be loaded after opening magic.

◆ open() [3/4]

void recognition::magic::open ( flags_mask_t flags_mask )

Open magic using the flags.

Parameters

[in] flags_mask One of the flags enums or bitwise or of the flags enums.

Exceptions

magic_open_error if opening magic fails.

Note: If magic is open, it will be reopened using the flags after closing it.; A magic database file must be loaded after opening magic.

◆ open() [4/4]

bool recognition::magic::open	(	flags_mask_t	flags_mask,
		const std::nothrow_t &	tag )

nodiscardnoexcept

Open magic using the flags, noexcept version.

Parameters

[in]	flags_mask	One of the flags enums or bitwise or of the flags enums.
[in]	tag	Tag for non-throwing overload.

Returns: True on success, false otherwise.

Note: If magic is open, it will be reopened using the flags after closing it.; A magic database file must be loaded after opening magic.

◆ operator bool()

recognition::magic::operator bool ( ) const

nodiscardnoexcept

Used for testing whether magic is valid for identifying file types or not.

Returns: True if the magic is valid, i.e., it is open and a magic database file is loaded; false otherwise.

◆ operator=() [1/2]

magic & recognition::magic::operator= ( const magic & )

delete

Deleted copy assignment.

◆ operator=() [2/2]

magic & recognition::magic::operator= ( magic && other )

noexcept

Move assign to this magic.

Note: After move construction, the moved-from object (other) is closed. It cannot be used for identifying file types until it is reopened and a magic database file is loaded.

◆ set_flags() [1/4]

void recognition::magic::set_flags ( const flags_container_t & flags_container )

Set the flags of magic.

Parameters

[in] flags_container Flags.

Exceptions

magic_is_closed	if magic is closed.
magic_set_flags_error	if setting the flags of magic fails.

◆ set_flags() [2/4]

bool recognition::magic::set_flags	(	const flags_container_t &	flags_container,
		const std::nothrow_t &	tag )

nodiscardnoexcept

Set the flags of magic, noexcept version.

Parameters

[in]	flags_container	Flags.
[in]	tag	Tag for non-throwing overload.

Returns: True on success, false otherwise.

◆ set_flags() [3/4]

void recognition::magic::set_flags ( flags_mask_t flags_mask )

Set the flags of magic.

Parameters

[in] flags_mask One of the flags enums or bitwise or of the flags enums.

Exceptions

magic_is_closed	if magic is closed.
magic_set_flags_error	if setting the flags of magic fails.

◆ set_flags() [4/4]

bool recognition::magic::set_flags	(	flags_mask_t	flags_mask,
		const std::nothrow_t &	tag )

nodiscardnoexcept

Set the flags of magic, noexcept version.

Parameters

[in]	flags_mask	One of the flags enums or bitwise or of the flags enums.
[in]	tag	Tag for non-throwing overload.

Returns: True on success, false otherwise.

◆ set_parameter() [1/2]

void recognition::magic::set_parameter	(	parameters	parameter,
		std::size_t	value )

Set the value of a parameter of magic.

Parameters

[in]	parameter	One of the parameters enum.
[in]	value	The value of the parameter.

Exceptions

magic_is_closed	if magic is closed.
magic_set_parameter_error	if setting the parameter of magic fails.

◆ set_parameter() [2/2]

bool recognition::magic::set_parameter	(	parameters	parameter,
		std::size_t	value,
		const std::nothrow_t &	tag )

nodiscardnoexcept

Set the value of a parameter of magic, noexcept version.

Parameters

[in]	parameter	One of the parameters enum.
[in]	value	The value of the parameter.
[in]	tag	Tag for non-throwing overload.

Returns: True on success, false otherwise.

◆ set_parameters() [1/2]

void recognition::magic::set_parameters ( const parameter_value_map_t & parameters )

Set the values of the parameters of magic.

Parameters

[in] parameters Parameters with corresponding values.

Exceptions

magic_is_closed	if magic is closed.
magic_set_parameter_error	if setting the parameter of magic fails.

◆ set_parameters() [2/2]

bool recognition::magic::set_parameters	(	const parameter_value_map_t &	parameters,
		const std::nothrow_t &	tag )

nodiscardnoexcept

Set the values of the parameters of magic, noexcept version.

Parameters

[in]	parameters	Parameters with corresponding values.
[in]	tag	Tag for non-throwing overload.

Returns: True on success, false otherwise.

Friends And Related Symbol Documentation

◆ to_string [1/2]

std::string to_string ( magic::flags flag )

friend

Convert the magic::flags to string.

Parameters

[in] flag The flag.

Returns: The flag as a string.

◆ to_string [2/2]

std::string to_string ( magic::parameters parameter )

friend

Convert the magic::parameters to string.

Parameters

[in] parameter The parameter.

Returns: The parameter as a string.

Member Data Documentation

◆ default_database_file

std::string_view recognition::magic::default_database_file {DEFAULT_DATABASE_FILE}

static

The path of the default database file.

◆ m_impl

std::unique_ptr<magic_private> recognition::magic::m_impl

private

The documentation for this class was generated from the following files:

Classes

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Private Types

Private Member Functions

Private Attributes

Friends

Detailed Description

Member Typedef Documentation

◆ default_file_container_t

◆ error_message_t

◆ expected_file_type_t

◆ expected_type_of_a_file_t

◆ expected_types_of_files_t

◆ file_type_t

◆ flags_container_t

◆ flags_mask_t

◆ parameter_value_map_t

◆ parameter_value_t

◆ tracker_t

◆ type_of_a_file_t

◆ types_of_files_t

Member Enumeration Documentation

◆ flags

◆ parameters

Constructor & Destructor Documentation

◆ magic() [1/7]

◆ magic() [2/7]

◆ magic() [3/7]

◆ magic() [4/7]

◆ magic() [5/7]

◆ magic() [6/7]

◆ magic() [7/7]

◆ ~magic()

Member Function Documentation

◆ check()

◆ close()

◆ compile()

◆ get_flags() [1/2]

◆ get_flags() [2/2]

◆ get_parameter() [1/2]

◆ get_parameter() [2/2]

◆ get_parameters() [1/2]

◆ get_parameters() [2/2]

◆ get_version()

◆ identify_container_impl() [1/2]

◆ identify_container_impl() [2/2]

◆ identify_directory_impl() [1/2]

◆ identify_directory_impl() [2/2]

◆ identify_file() [1/2]

◆ identify_file() [2/2]

◆ identify_files() [1/8]

◆ identify_files() [2/8]

◆ identify_files() [3/8]

◆ identify_files() [4/8]

◆ identify_files() [5/8]

◆ identify_files() [6/8]

◆ identify_files() [7/8]

◆ identify_files() [8/8]

◆ is_database_loaded()

◆ is_open()

◆ is_valid()

◆ load_database_file() [1/2]

◆ load_database_file() [2/2]

◆ open() [1/4]

◆ open() [2/4]

◆ open() [3/4]

◆ open() [4/4]

◆ operator bool()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ set_flags() [1/4]

◆ set_flags() [2/4]

◆ set_flags() [3/4]

◆ set_flags() [4/4]

◆ set_parameter() [1/2]

◆ set_parameter() [2/2]

◆ set_parameters() [1/2]