Struct magic::cookie::Cookie

pub struct Cookie<S: State> { /* private fields */ }

Combined configuration of Flags, parameters and databases

A “cookie” is libmagic lingo for a combined configuration of

• cookie::Flags
• parameters (not implemented yet)
• loaded datbases, e.g. cookie::DatabasePaths

A cookie advances through 2 states: opened, then loaded.

// create new cookie in initial opened state with given flags
let cookie = magic::Cookie::open(magic::cookie::Flags::default())?;

// advance cookie into loaded state
let cookie = cookie.load(&magic::cookie::DatabasePaths::default())?;

In either state, you can use operations that do not require already loaded magic databases:

• Cookie::load(), Cookie::load_buffers() to load databases and transition into the loaded state
• Cookie::set_flags() to overwrite the initial flags given in Cookie::open()
• Cookie::compile(), Cookie::check(), Cookie::list() to operate on magic database files

Once in the loaded state, you can perform magic “queries”:

• Cookie::file(), Cookie::buffer()

Implementations

impl Cookie<Open>

Operations that are valid in the Open state

A new cookie created with Cookie::open does not have any databases loaded.

pub fn open(flags: Flags) -> Result<Cookie<Open>, OpenError>

Creates a new configuration cookie, flags specify how other operations on this cookie should behave

This does not load() any databases yet.

The flags can be changed lateron with set_flags().

Examples

// open a new cookie with default flags
let cookie = magic::Cookie::open(Default::default())?;

// open a new cookie with custom flags
let flags = magic::cookie::Flags::COMPRESS | magic::cookie::Flags::DEVICES;
let cookie = magic::Cookie::open(flags)?;

Errors

If there was an libmagic internal error allocating a new cookie, a cookie::OpenError will be returned.

If the given flags are unsupported on the current platform, a cookie::OpenError will be returned.

impl Cookie<Load>

Operations that are valid in the Load state

An opened cookie with loaded databases can inspect files and buffers.

pub fn file<P: AsRef<Path>>(&self, filename: P) -> Result<String, Error>

Returns a textual description of the contents of the file filename

Requires to load() databases before calling.

Examples

// open a new cookie with default flags and database
let cookie = magic::Cookie::open(Default::default())?.load(&Default::default())?;

let file_description = cookie.file("data/tests/rust-logo-128x128-blk.png");

Errors

If there was an libmagic internal error, a cookie::Error will be returned.

Panics

Panics if libmagic violates its API contract, e.g. by not setting the last error.

pub fn buffer(&self, buffer: &[u8]) -> Result<String, Error>

Returns a textual description of the contents of the buffer

Requires to load() databases before calling.

Examples

// open a new cookie with default flags and database
let cookie = magic::Cookie::open(Default::default())?.load(&Default::default())?;

let buffer = b"%PDF-\xE2\x80\xA6";
let buffer_description = cookie.buffer(buffer);

Errors

If there was an libmagic internal error, a cookie::Error will be returned.

Panics

Panics if libmagic violates its API contract, e.g. by not setting the last error.

impl<S: State> Cookie<S>

Operations that are valid in any state

pub fn load( self, filenames: &DatabasePaths ) -> Result<Cookie<Load>, LoadError<S>>

Loads the given database filenames for further queries

Adds “.mgc” to the database filenames as appropriate.

Calling load() or load_buffers() replaces the previously loaded database/s.

This is equivalent to the using the file CLI:

$ file --magic-file 'data/tests/db-images-png:data/tests/db-python' --version
file-5.39
magic file from data/tests/db-images-png:data/tests/db-python

Examples

// open a new cookie with default flags
let cookie = magic::Cookie::open(Default::default())?;

// load the default unnamed database
let database = Default::default();
let cookie = cookie.load(&database)?;

// load databases from files
let databases = ["data/tests/db-images-png", "data/tests/db-python"].try_into()?;
let cookie = cookie.load(&databases)?;

// load precompiled database from file
let database = "data/tests/db-images-png-precompiled.mgc".try_into()?;
let cookie = cookie.load(&database)?;

Errors

If there was an libmagic internal error, a cookie::LoadError will be returned, which contains the cookie in its original state.

Panics

Panics if libmagic violates its API contract, e.g. by not setting the last error or returning undefined data.

pub fn load_buffers( self, buffers: &[&[u8]] ) -> Result<Cookie<Load>, LoadError<S>>

Loads the given compiled databases buffers for further queries

Databases need to be compiled with a compatible libmagic version.

This function can be used in environments where libmagic does not have direct access to the filesystem, but can access the magic database via shared memory or other IPC means.

Calling load_buffers() or load() replaces the previously loaded database/s.

Errors

If there was an libmagic internal error, a cookie::LoadError will be returned, which contains the cookie in its original state.

Panics

Panics if libmagic violates its API contract, e.g. by not setting the last error or returning undefined data.

pub fn set_flags(&self, flags: Flags) -> Result<(), SetFlagsError>

Sets the flags to use for this configuration

Overwrites any previously set flags, e.g. those from load().

Examples

// open a new cookie with initial default flags
let cookie = magic::Cookie::open(Default::default())?;

// overwrite the initial flags
let flags = magic::cookie::Flags::COMPRESS | magic::cookie::Flags::DEVICES;
cookie.set_flags(flags)?;

Errors

If the given flags are unsupported on the current platform, an cookie::SetFlagsError will be returned.

pub fn compile(&self, filenames: &DatabasePaths) -> Result<(), Error>

Compiles the given database files filenames for faster access

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

This is equivalent to the following file CLI command:

$ file --compile --magic-file data/tests/db-images-png:data/tests/db-python

Errors

If there was an libmagic internal error, a cookie::Error will be returned.

Panics

Panics if libmagic violates its API contract, e.g. by not setting the last error or returning undefined data.

pub fn check(&self, filenames: &DatabasePaths) -> Result<(), Error>

Checks the validity of entries in the database files filenames

Errors

If there was an libmagic internal error, a cookie::Error will be returned.

Panics

Panics if libmagic violates its API contract, e.g. by not setting the last error or returning undefined data.

pub fn list(&self, filenames: &DatabasePaths) -> Result<(), Error>

Dumps all magic entries in the given database files filenames in a human readable format

This is equivalent to the following file CLI command:

$ file --checking-printout --magic-file data/tests/db-images-png:data/tests/db-python

Errors

If there was an libmagic internal error, a cookie::Error will be returned.

Panics

Panics if libmagic violates its API contract, e.g. by not setting the last error or returning undefined data.

Trait Implementations

impl<S: Debug + State> Debug for Cookie<S>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<S: State> Drop for Cookie<S>

fn drop(&mut self)

Closes the loaded magic database files and deallocates any resources used