Comprehensive examples demonstrating libmagicxx usage. More...

#include <iostream>
#include <magic.hpp>
#include <print>

Include dependency graph for magic_examples.cpp:

Functions
void	ExampleBasicIdentify ()
	Example 1: Basic file identification with exception handling.
void	ExampleNoexceptIdentify ()
	Example 2: File identification using the noexcept API.
void	ExampleIdentifyDirectory ()
	Example 3: Batch identification of files in a directory.
void	ExampleCustomFlagsParameters ()
	Example 4: Configuring flags and parameters.
void	ExampleCheckAndCompile ()
	Example 5: Database validation and compilation.
void	ExampleProgressTracking ()
	Example 6: Progress tracking for batch operations.
void	ExampleContainerIdentify ()
	Example 7: Identify specific files from a container.
void	ExampleLifecycleManagement ()
	Example 8: Manual lifecycle and state queries.
void	ExampleVersionAndAllParameters ()
	Example 9: Get version and all parameters.
auto	main () -> int
	Main entry point for the examples program.

Detailed Description

Comprehensive examples demonstrating libmagicxx usage.

This file contains practical examples showing how to use libmagicxx — a modern C++23 wrapper for libmagic, the library that powers the Unix file command. Each example demonstrates a different aspect of the library's functionality.

Examples Overview

Example	Description
ExampleBasicIdentify()	Basic file identification with exception handling
ExampleNoexceptIdentify()	File identification using noexcept API
ExampleIdentifyDirectory()	Batch identification of files in a directory
ExampleCustomFlagsParameters()	Configuring flags and parameters
ExampleCheckAndCompile()	Database validation and compilation
ExampleProgressTracking()	Progress tracking for batch operations
ExampleContainerIdentify()	Identify specific files from a container
ExampleLifecycleManagement()	Manual lifecycle and state queries
ExampleVersionAndAllParameters()	Get version and all parameters

Building the Examples

Build the examples using CMake with the examples preset:

./scripts/workflows.sh -p linux-x86_64-clang-examples

Running the Examples

After building, run the examples executable:

./build/examples/magic_examples

See also: Recognition::Magic; Recognition::MagicException

Function Documentation

◆ ExampleBasicIdentify()

void ExampleBasicIdentify ( )

Example 1: Basic file identification with exception handling.

This example demonstrates the most common usage pattern:

Creating a Magic instance with MIME output format
Validating the instance before use
Identifying a file's type
Handling exceptions properly

Note: The Magic constructor automatically opens and loads the database.

See also: Magic::Magic(FlagsMaskT, const std::filesystem::path&); Magic::IdentifyFile(); MagicException

Examples: magic_examples.cpp.

◆ ExampleCheckAndCompile()

void ExampleCheckAndCompile ( )

Example 5: Database validation and compilation.

This example demonstrates database management:

Checking database validity with Magic::Check()
Compiling a magic database with Magic::Compile()

These are static methods that don't require a Magic instance. They operate on the default database file unless a path is specified.

Use Cases

Check(): Validate database integrity before deployment
Compile(): Create .mgc compiled database from source magic file

Note: Compile() creates a new .mgc file alongside the source file.

See also: Magic::Check(); Magic::Compile(); Magic::DEFAULT_DATABASE_FILE

Examples: magic_examples.cpp.

◆ ExampleContainerIdentify()

void ExampleContainerIdentify ( )

Example 7: Identify specific files from a container.

This example demonstrates batch file identification:

Creating a vector of specific file paths
Identifying all files in the container at once
Processing results as a map

Use this pattern when you have a known list of files rather than scanning a directory.

See also: Magic::IdentifyFiles(container); Utility::FileContainer

Examples: magic_examples.cpp.

◆ ExampleCustomFlagsParameters()

void ExampleCustomFlagsParameters ( )

Example 4: Configuring flags and parameters.

This example demonstrates advanced configuration:

Opening with multiple flags using a container
Setting parameters to tune identification behavior
Retrieving current flag and parameter values

Flags Used

Mime: Return MIME type with encoding (e.g., "text/plain; charset=utf-8")
Compress: Decompress files before identification

Parameters Modified

BytesMax: Maximum bytes to read from file (set to 2KB for demo)

See also: Magic::Flags; Magic::Parameters; Magic::SetParameter(); Magic::GetParameter()

Examples: magic_examples.cpp.

◆ ExampleIdentifyDirectory()

void ExampleIdentifyDirectory ( )

Example 3: Batch identification of files in a directory.

This example demonstrates directory scanning:

Identifying all files in a directory recursively
Processing results as a map of paths to types
Using std::views for result filtering

The IdentifyFiles() method recursively scans the directory and returns a map from file paths to their identified types.

Note: For large directories, consider using the progress tracker overload to monitor identification progress.

See also: Magic::IdentifyFiles(const std::filesystem::path&, std::filesystem::directory_options); Magic::FileTypeMapT

Examples: magic_examples.cpp.

◆ ExampleLifecycleManagement()

void ExampleLifecycleManagement ( )

Example 8: Manual lifecycle and state queries.

This example demonstrates lifecycle management:

Default construction (Closed state)
State queries: IsOpen(), IsDatabaseLoaded(), IsValid()
Manual Open() and LoadDatabaseFile()
SetFlags() to change flags after construction
Close() to release resources

State Transitions

Closed -> Open() -> Opened -> LoadDatabaseFile() -> Valid -> Close() -> Closed

See also: Magic::IsOpen(); Magic::IsDatabaseLoaded(); Magic::IsValid(); Magic::Close(); Magic::SetFlags()

Examples: magic_examples.cpp.

◆ ExampleNoexceptIdentify()

void ExampleNoexceptIdentify ( )

Example 2: File identification using the noexcept API.

This example demonstrates the non-throwing API pattern:

Manual Open() and LoadDatabaseFile() with std::nothrow
Checking return values instead of catching exceptions
Using IdentifyFile() with std::nothrow returning std::expected

The noexcept API is useful when:

Exceptions are disabled or expensive in your environment
You prefer explicit error checking over exception handling
Performance is critical and you want to avoid exception overhead

See also: Magic::Open(FlagsMaskT, const std::nothrow_t&); Magic::LoadDatabaseFile(const std::nothrow_t&, const std::filesystem::path&); Magic::IdentifyFile(const std::filesystem::path&, const std::nothrow_t&)

Examples: magic_examples.cpp.

◆ ExampleProgressTracking()

void ExampleProgressTracking ( )

Example 6: Progress tracking for batch operations.

This example demonstrates progress monitoring:

Creating a shared progress tracker
Passing it to IdentifyFiles() for monitoring
Checking completion status and percentage

Progress tracking is useful for:

Large directories with many files
Providing user feedback during long operations
Implementing progress bars or status updates

See also: Utility::MakeSharedProgressTracker(); Utility::ProgressTracker; Magic::IdentifyFiles(directory, progress_tracker)

Examples: magic_examples.cpp.

◆ ExampleVersionAndAllParameters()

void ExampleVersionAndAllParameters ( )

Example 9: Get version and all parameters.

This example demonstrates:

Getting the libmagic version with GetVersion()
Getting all parameters at once with GetParameters()
Setting multiple parameters with SetParameters()

See also: Magic::GetVersion(); Magic::GetParameters(); Magic::SetParameters()

Examples: magic_examples.cpp.

◆ main()

auto main ( ) -> int

Main entry point for the examples program.

Runs all example functions sequentially, demonstrating various features of the libmagicxx library.

Returns: 0 on successful completion.

Examples: magic_examples.cpp.

Functions