The magic class provides a C++ wrapper over the Magic Number Recognition Library. The magic class is used to identify the type of a file, if the following steps have been completed;. 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 }
	The parameters enums are used for displaying or modifying the parameters of a magic. More...

using	flags_mask_t = std::bitset<30uz>
	The flags_mask_t typedef.

using	file_type_t = std::string
	The file_type_t typedef.

using	error_message_t = std::string
	The error_message_t typedef.

using	expected_file_type_t = std::expected<file_type_t, error_message_t>
	The expected_file_type_t typedef.

using	types_of_files_t = std::map<std::filesystem::path, file_type_t>
	The types_of_files_t typedef.

using	expected_types_of_files_t = std::map<std::filesystem::path, expected_file_type_t>
	The expected_types_of_files_t typedef.

using	flags_container_t = std::vector<flags>
	The flags_container_t typedef.

using	parameter_value_map_t = std::map<parameters, std::size_t>
	The parameter_value_map_t typedef.

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 (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 (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 open or closed.

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

void	close () noexcept
	Close magic.

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

flags_container_t	get_flags () const
	Get the flags of magic.

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

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

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, std::nothrow_t) 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.

expected_types_of_files_t	identify_files (const std::filesystem::path &directory, std::nothrow_t, 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.

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

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

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

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

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

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

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

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

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

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

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

Static Public Attributes
static constexpr auto	default_database_file = "/usr/share/misc/magic"
	The path of the default database file.

Private Member Functions
types_of_files_t	identify_files_impl (const std::ranges::range auto &files) const

expected_types_of_files_t	identify_files_impl (const std::ranges::range auto &files, std::nothrow_t) const noexcept

Private Attributes
std::unique_ptr< magic_private >	m_impl

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

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

Detailed Description

The magic class provides a C++ wrapper over the Magic Number Recognition Library. The magic class is used to identify the type of a file, if the following steps have been completed;.

magic must be opened.
A magic database file must be loaded.

Member Typedef Documentation

◆ error_message_t

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

The error_message_t typedef.

◆ expected_file_type_t

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

The expected_file_type_t typedef.

◆ expected_types_of_files_t

using recognition::magic::expected_types_of_files_t = std::map<std::filesystem::path, expected_file_type_t>

The expected_types_of_files_t typedef.

◆ file_type_t

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

The file_type_t typedef.

◆ flags_container_t

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

The flags_container_t typedef.

◆ flags_mask_t

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

The flags_mask_t typedef.

◆ parameter_value_map_t

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

The parameter_value_map_t typedef.

◆ types_of_files_t

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

The types_of_files_t typedef.

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	No special handling.
debug	Print debugging messages to stderr.
symlink	If the file queried is a symlink, follow it.
compress	If the file is compressed, unpack it and look at the contents.
devices	If the file is a block or character special device, then open the device and try to look in its contents.
mime_type	Return a MIME type string, instead of a textual description.
continue_search	Return all matches, not just the first.
check_database	Check the magic database for consistency and print warnings to stderr.
preserve_atime	On systems that support utime(3) or utimes(2), attempt to preserve the access time of files analysed.
raw	Don't translate unprintable characters to a \ooo octal representation.
error	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	Return a MIME encoding, instead of a textual description.
mime	A shorthand for mime_type\|mime_encoding.
apple	Return the Apple creator and type.
extension	Return a slash-separated list of extensions for this file type.
compress_transp	Don't report on compression, only report about the uncompressed data.
no_compress_fork	Don't allow decompressors that use fork.
nodesc	A shorthand for extension\|mime\|apple
no_check_compress	Don't look inside compressed files.
no_check_tar	Don't examine tar files.
no_check_soft	Don't consult magic files.
no_check_apptype	Don't check for EMX application type (only on EMX).
no_check_elf	Don't print ELF details.
no_check_text	Don't check for various types of text files.
no_check_cdf	Don't get extra information on MS Composite Document Files.
no_check_csv	Don't examine CSV files.
no_check_tokens	Don't look for known tokens inside ascii files.
no_check_encoding	Don't check text encodings.
no_check_json	Don't examine JSON files.
no_check_simh	Don't examine SIMH tape files.
no_check_builtin	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	Recursion limit for indirection (default is 50).
name_max	Use limit for name/use magic (default is 50).
elf_phnum_max	Max ELF program sections processed (default is 2048).
elf_shnum_max	Max ELF sections processed (default is 32768).
elf_notes_max	Max ELF notes processed (default is 256).
regex_max	Max length limit for REGEX searches (default is 8192).
bytes_max	Max bytes to look inside file (default is 7340032).
encoding_max	Max bytes to scan for encoding (default is 65536).
elf_shsize_max	Max ELF section size (default is 134217728).

Constructor & Destructor Documentation

◆ magic() [1/5]

recognition::magic::magic ( )

noexcept

Construct magic without opening it.

◆ magic() [2/5]

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 /usr/share/misc/magic.

Exceptions

magic_open_error	if opening magic fails.
invalid_path	if the path of the magic database file is not a file.
magic_load_error	if loading the magic database file fails.

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

◆ magic() [3/5]

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 /usr/share/misc/magic.

Exceptions

magic_open_error	if opening magic fails.
invalid_path	if the path of the magic database file is not a file.
magic_load_error	if loading the magic database file fails.

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

◆ magic() [4/5]

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

noexcept

Move construct magic.

Note: other is valid as a default constructed magic.

◆ magic() [5/5]

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 ) const

noexcept

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 /usr/share/misc/magic.

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

◆ close()

void recognition::magic::close ( )

noexcept

Close magic.

Note: magic is valid as a default constructed magic.

◆ compile()

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

noexcept

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

Parameters

[in] database_file The file to compile, default is /usr/share/misc/magic.

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()

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

Get the flags of magic.

Returns: flags_container_t

Exceptions

magic_is_closed if magic is closed.

◆ get_parameter()

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

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_parameters()

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

Get the values of all parameters of magic.

Returns: <parameters, value> map.

Exceptions

magic_is_closed if magic is closed.

◆ get_version()

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

staticnoexcept

Get the version of the Magic Number Recognition Library.

Returns: The version number as a string.

◆ identify_file() [1/2]

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

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.
empty_path	if the path of the file is empty.
magic_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,
		std::nothrow_t	) const

noexcept

Identify the type of a file, noexcept version.

Parameters

[in] path The path of the file.

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

◆ identify_files() [1/4]

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

inline

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.
empty_path	if the path of the file is empty.
magic_file_error	if identifying the type of the file fails.

◆ identify_files() [2/4]

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

inlinenoexcept

Identify the types of files, noexcept version.

Parameters

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

Returns: The types of each file as a map.

◆ identify_files() [3/4]

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

inline

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.
empty_path	if the path of the file is empty.
magic_file_error	if identifying the type of the file fails.

◆ identify_files() [4/4]

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

inlinenoexcept

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

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.

◆ identify_files_impl() [1/2]

types_of_files_t recognition::magic::identify_files_impl ( const std::ranges::range auto & files ) const

inlineprivate

◆ identify_files_impl() [2/2]

expected_types_of_files_t recognition::magic::identify_files_impl	(	const std::ranges::range auto &	files,
		std::nothrow_t	) const

inlineprivatenoexcept

◆ is_open()

bool recognition::magic::is_open ( ) const

noexcept

Used for testing whether magic is open or closed.

Returns: True if magic is open, false otherwise.

◆ load_database_file()

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 /usr/share/misc/magic.

Exceptions

magic_is_closed	if magic is closed.
empty_path	if the path of the database file is empty.
invalid_path	if the path of the database file is not a file.
magic_load_error	if loading the database file fails.

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

◆ open() [1/2]

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.

◆ open() [2/2]

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.

◆ operator bool()

recognition::magic::operator bool ( ) const

noexcept

Used for testing whether magic is open or closed.

Returns: True if magic is open, 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: other is valid as a default constructed magic.

◆ set_flags() [1/2]

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/2]

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_parameter()

void recognition::magic::set_parameter	(	magic::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_param_error	if setting the parameter of magic fails.

◆ set_parameters()

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_param_error	if setting the parameter of magic fails.

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

constexpr auto recognition::magic::default_database_file = "/usr/share/misc/magic"

staticconstexpr

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 Member Functions

Private Attributes

Friends

Detailed Description

Member Typedef Documentation

◆ error_message_t

◆ expected_file_type_t

◆ expected_types_of_files_t

◆ file_type_t

◆ flags_container_t

◆ flags_mask_t

◆ parameter_value_map_t

◆ types_of_files_t

Member Enumeration Documentation

◆ flags

◆ parameters

Constructor & Destructor Documentation

◆ magic() [1/5]

◆ magic() [2/5]

◆ magic() [3/5]

◆ magic() [4/5]

◆ magic() [5/5]

◆ ~magic()

Member Function Documentation

◆ check()

◆ close()

◆ compile()

◆ get_flags()

◆ get_parameter()

◆ get_parameters()

◆ get_version()

◆ identify_file() [1/2]

◆ identify_file() [2/2]

◆ identify_files() [1/4]

◆ identify_files() [2/4]

◆ identify_files() [3/4]

◆ identify_files() [4/4]

◆ identify_files_impl() [1/2]

◆ identify_files_impl() [2/2]

◆ is_open()

◆ load_database_file()

◆ open() [1/2]

◆ open() [2/2]

◆ operator bool()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ set_flags() [1/2]

◆ set_flags() [2/2]

◆ set_parameter()

◆ set_parameters()

Friends And Related Symbol Documentation

◆ to_string [1/2]

◆ to_string [2/2]

Member Data Documentation

◆ default_database_file

◆ m_impl