magic
CopyrightCopyright (C) 2005 John Goerzen
LicenseBSD-3-Clause
MaintainerPhilippe <philippedev101\@gmail.com>
Stabilityprovisional
Portabilityportable
Safe HaskellNone
LanguageHaskell2010

Magic.FilePath

Description

A convenience facade over Magic that takes ordinary FilePaths instead of OsPaths. Import this module instead of Magic if you prefer String paths:

import Magic.FilePath

Everything else (the handle, flags, in-memory and descriptor queries, and so on) is re-exported unchanged from Magic.

The FilePath wrappers convert with encodeFS / decodeFS, which go through the locale's filesystem encoding. For ordinary ASCII/UTF-8 filenames under a UTF-8 locale this is fine. But a FilePath cannot faithfully represent every path the operating system can: names whose bytes are not valid in the current locale (raw non-UTF-8 bytes on Unix, or names created under a different locale) may be corrupted or fail to round-trip, so a call can fail to open a file that exists, or open the wrong one. The OsPath functions in Magic store the path bytes verbatim and avoid this entirely; prefer them when correctness on arbitrary filenames matters.

Since: 2.0.0

Synopsis

Documentation

pattern MagicApple :: MagicFlags Source #

Return the Apple creator and type.

pattern MagicCheck :: MagicFlags Source #

Check the magic database for consistency and report problems.

pattern MagicCompress :: MagicFlags Source #

Look inside compressed files.

pattern MagicCompressTransp :: MagicFlags Source #

Report on the compressed contents only, without mentioning the compression itself (transparent decompression).

pattern MagicContinue :: MagicFlags Source #

Return all matches, not just the first.

pattern MagicDebug :: MagicFlags Source #

Print debugging messages to stderr.

pattern MagicDevices :: MagicFlags Source #

Look at the contents of block or character special devices.

pattern MagicError :: MagicFlags Source #

Treat errors while examining a file as real errors instead of embedding them in the result.

pattern MagicExtension :: MagicFlags Source #

Return a slash-separated list of valid file extensions for the detected type.

pattern MagicMime :: MagicFlags Source #

Return both the MIME type and the encoding (MagicMimeType <> MagicMimeEncoding).

pattern MagicMimeEncoding :: MagicFlags Source #

Return the MIME encoding (character set) instead of a textual description.

pattern MagicMimeType :: MagicFlags Source #

Return a MIME type string instead of a textual description.

pattern MagicNoCheckApptype :: MagicFlags Source #

Do not check for an application type (e.g. EMX).

pattern MagicNoCheckBuiltin :: MagicFlags Source #

Disable all built-in tests; consult only the magic database.

pattern MagicNoCheckCdf :: MagicFlags Source #

Do not examine CDF (Microsoft Compound Document) files.

pattern MagicNoCheckCompress :: MagicFlags Source #

Do not look inside compressed files.

pattern MagicNoCheckCsv :: MagicFlags Source #

Do not examine CSV files.

pattern MagicNoCheckElf :: MagicFlags Source #

Do not examine ELF details.

pattern MagicNoCheckEncoding :: MagicFlags Source #

Do not check text encodings.

pattern MagicNoCheckJson :: MagicFlags Source #

Do not examine JSON files.

pattern MagicNoCheckSimh :: MagicFlags Source #

Do not examine SIMH tape files.

pattern MagicNoCheckSoft :: MagicFlags Source #

Do not consult the magic database entries (soft magic).

pattern MagicNoCheckTar :: MagicFlags Source #

Do not examine tar archives.

pattern MagicNoCheckText :: MagicFlags Source #

Do not examine text files.

pattern MagicNoCheckTokens :: MagicFlags Source #

Do not look for known text tokens.

pattern MagicNoCompressFork :: MagicFlags Source #

Do not allow decompression that requires forking a helper process.

pattern MagicNodesc :: MagicFlags Source #

Composite of MagicExtension, MagicMime and MagicApple: return identifiers rather than a textual description.

pattern MagicNone :: MagicFlags Source #

No special handling; return a textual description (the default). This is mempty.

pattern MagicPreserveAtime :: MagicFlags Source #

Preserve the access time of examined files.

pattern MagicRaw :: MagicFlags Source #

Do not translate unprintable characters to octal escapes.

pattern MagicSymlink :: MagicFlags Source #

Follow symbolic links.

hasFlag :: MagicFlags -> MagicFlags -> Bool Source #

hasFlag fs flag is True when every bit of flag is set in fs. Works for composite flags too (e.g. fs `hasFlag` MagicMime). Note that fs `hasFlag` MagicNone is always True (the empty set is a subset of everything).

Since: 2.0.0

removeFlags :: MagicFlags -> MagicFlags -> MagicFlags Source #

removeFlags fs drop clears every bit of drop from fs (set difference), e.g. flags `removeFlags` MagicError.

Since: 2.0.0

magicLoadDefault :: Magic -> IO () Source #

Load the system's default magic database into the handle. Raises a MagicException if the database cannot be loaded.

magicOpen :: MagicFlags -> IO Magic Source #

Create a new magic handle configured with the given flags. Combine flags with (<>) (see MagicFlags), or pass mempty for the defaults. Before querying anything you must load a database with magicLoadDefault or magicLoad.

The handle is freed automatically when it is garbage-collected. Raises an IOError if the handle cannot be created.

magicByteString :: Magic -> ByteString -> IO Text Source #

Identify the contents of a strict ByteString. Does no encoding conversion, so it is the right way to examine in-memory data. Raises a MagicException if the data cannot be examined.

Since: 1.1.2

magicCString :: Magic -> CStringLen -> IO Text Source #

Identify the contents of a C string buffer (a pointer and a length). The lowest-level in-memory primitive; for ordinary use prefer magicByteString. Raises a MagicException if the data cannot be examined.

magicDescriptor :: Magic -> Fd -> IO Text Source #

Identify the data behind an open file descriptor, as magicFile does for a named file. Useful for sockets, pipes, or files you have already opened. Raises a MagicException if the descriptor cannot be examined.

Since: 1.1.2

magicErrno :: Magic -> IO Int Source #

The errno recorded by the last failing operation on the handle, or 0 if the last failure was not caused by a system error.

Since: 1.1.2

magicGetFlags :: Magic -> IO MagicFlags Source #

Read the flags currently set on the handle (see magicSetFlags). Test the result with hasFlag. Raises a MagicException if the running libmagic does not support querying flags.

Since: 1.1.2

magicGetParam :: Magic -> MagicParam -> IO Int Source #

Read a tunable parameter (see MagicParam).

Since: 1.1.2

magicLoadBuffers :: Magic -> [ByteString] -> IO () Source #

Load magic from one or more in-memory compiled databases (the .mgc binary form produced by magicCompile), rather than from files. This lets a program embed its magic database.

libmagic keeps (does not copy) the supplied buffers for the lifetime of the handle, so the handle retains references to the given ByteStrings to keep their memory alive until it is closed. Raises a MagicException on failure.

Since: 2.0.0

magicSetFlags :: Magic -> MagicFlags -> IO () Source #

Change the flags (see MagicFlags) on an existing handle, for example to switch between textual descriptions and MIME types. Raises a MagicException on failure.

magicSetParam :: Magic -> MagicParam -> Int -> IO () Source #

Set a tunable parameter (see MagicParam), for example to cap the number of bytes scanned in untrusted input. Raises a MagicException on failure.

Since: 1.1.2

magicStdin :: Magic -> IO Text Source #

Identify the data available on standard input, as magicFile does for a named file. Raises a MagicException if the data cannot be examined.

magicVersion :: IO Int Source #

The version of the libmagic library in use, encoded as a single integer (for example 545 for version 5.45).

Since: 1.1.2

newtype MagicFlags Source #

A set of libmagic flags, represented as the underlying C bit-mask. Combine flags with (<>), start from mempty (no flags), test membership with hasFlag, and narrow with removeFlags. The MagicFlags constructor is an escape hatch for passing a raw mask; prefer the pattern synonyms below.

Since: 2.0.0

Constructors

MagicFlags CInt 

Instances

Instances details
NFData MagicFlags Source # 
Instance details

Defined in Magic.Data

Methods

rnf :: MagicFlags -> ()

Monoid MagicFlags Source #

mempty is the empty flag set (MagicNone).

Instance details

Defined in Magic.Data

Semigroup MagicFlags Source #

Flags combine by bitwise-or.

Instance details

Defined in Magic.Data

Methods

(<>) :: MagicFlags -> MagicFlags -> MagicFlags

sconcat :: NonEmpty MagicFlags -> MagicFlags

stimes :: Integral b => b -> MagicFlags -> MagicFlags

Generic MagicFlags Source # 
Instance details

Defined in Magic.Data

Associated Types

type Rep MagicFlags 
Instance details

Defined in Magic.Data

type Rep MagicFlags = D1 ('MetaData "MagicFlags" "Magic.Data" "magic-2.0.0-A9TYcUdA1HUI3Y62VpQyfB" 'True) (C1 ('MetaCons "MagicFlags" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 CInt)))

Methods

from :: MagicFlags -> Rep MagicFlags x

to :: Rep MagicFlags x -> MagicFlags

Show MagicFlags Source #

Prints the set flags by name (e.g. MagicMimeType <> MagicError), or MagicNone when empty. Any bits not corresponding to a known flag are shown as a raw MagicFlags n term.

Instance details

Defined in Magic.Data

Methods

showsPrec :: Int -> MagicFlags -> ShowS

show :: MagicFlags -> String

showList :: [MagicFlags] -> ShowS

Eq MagicFlags Source # 
Instance details

Defined in Magic.Data

Methods

(==) :: MagicFlags -> MagicFlags -> Bool

(/=) :: MagicFlags -> MagicFlags -> Bool

Ord MagicFlags Source # 
Instance details

Defined in Magic.Data

type Rep MagicFlags Source # 
Instance details

Defined in Magic.Data

type Rep MagicFlags = D1 ('MetaData "MagicFlags" "Magic.Data" "magic-2.0.0-A9TYcUdA1HUI3Y62VpQyfB" 'True) (C1 ('MetaCons "MagicFlags" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 CInt)))

data Magic Source #

The magic handle: an opaque cookie obtained from magicOpen and passed to the loading and querying functions.

Handles are closed (and their memory freed) automatically when they are garbage-collected; there is no need to close them explicitly.

Thread safety. Operations on a single handle are serialised by an internal lock, so it is safe to share one handle across threads (concurrent calls simply take turns). For genuine parallelism, use one handle per thread; distinct handles are independent. Programs doing blocking work (loading databases, examining files) should use the threaded runtime (-threaded).

Instances

Instances details
Show Magic Source #

The handle is opaque; it shows as a fixed placeholder.

Instance details

Defined in Magic.Internal

Methods

showsPrec :: Int -> Magic -> ShowS

show :: Magic -> String

showList :: [Magic] -> ShowS

data MagicException Source #

The exception raised when a libmagic operation fails. Carries the name of the operation that failed and the message reported by libmagic.

Since: 2.0.0

Constructors

MagicException 

Fields

Instances

Instances details
NFData MagicException Source # 
Instance details

Defined in Magic.Internal

Methods

rnf :: MagicException -> ()

Exception MagicException Source # 
Instance details

Defined in Magic.Internal

Methods

toException :: MagicException -> SomeException

fromException :: SomeException -> Maybe MagicException

displayException :: MagicException -> String

backtraceDesired :: MagicException -> Bool

Generic MagicException Source # 
Instance details

Defined in Magic.Internal

Associated Types

type Rep MagicException 
Instance details

Defined in Magic.Internal

type Rep MagicException = D1 ('MetaData "MagicException" "Magic.Internal" "magic-2.0.0-A9TYcUdA1HUI3Y62VpQyfB" 'False) (C1 ('MetaCons "MagicException" 'PrefixI 'True) (S1 ('MetaSel ('Just "magicErrorContext") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Text) :*: S1 ('MetaSel ('Just "magicErrorMessage") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Text)))
Show MagicException Source # 
Instance details

Defined in Magic.Internal

Methods

showsPrec :: Int -> MagicException -> ShowS

show :: MagicException -> String

showList :: [MagicException] -> ShowS

Eq MagicException Source # 
Instance details

Defined in Magic.Internal

type Rep MagicException Source # 
Instance details

Defined in Magic.Internal

type Rep MagicException = D1 ('MetaData "MagicException" "Magic.Internal" "magic-2.0.0-A9TYcUdA1HUI3Y62VpQyfB" 'False) (C1 ('MetaCons "MagicException" 'PrefixI 'True) (S1 ('MetaSel ('Just "magicErrorContext") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Text) :*: S1 ('MetaSel ('Just "magicErrorMessage") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Text)))

data MagicParam Source #

Tunable limits that bound how hard libmagic works when examining data, read and written with magicGetParam and magicSetParam (see Magic.Operations). Lowering these (especially MagicParamBytesMax) is a way to cap the effort spent on untrusted input. Defaults below are those documented for libmagic 5.45.

Since: 1.1.2

Constructors

MagicParamIndirMax

Maximum number of levels of recursion when following indirect magic. (Default: 15.)

MagicParamNameMax

Maximum length of a name used by name/use magic. (Default: 30.)

MagicParamElfPhnumMax

Maximum number of ELF program header sections processed. (Default: 128.)

MagicParamElfShnumMax

Maximum number of ELF section header sections processed. (Default: 32768.)

MagicParamElfNotesMax

Maximum number of ELF notes processed. (Default: 256.)

MagicParamRegexMax

Maximum length of a regex search. (Default: 8192.)

MagicParamBytesMax

Maximum number of bytes read from a file before giving up. (Default: 1048576, i.e. 1 MiB.)

MagicParamEncodingMax

Maximum number of bytes scanned when guessing a text encoding.

MagicParamElfShsizeMax

Maximum size of an ELF section processed.

Instances

Instances details
NFData MagicParam Source # 
Instance details

Defined in Magic.Types

Methods

rnf :: MagicParam -> ()

Bounded MagicParam Source # 
Instance details

Defined in Magic.Types

Enum MagicParam Source # 
Instance details

Defined in Magic.Types

Generic MagicParam Source # 
Instance details

Defined in Magic.Types

Associated Types

type Rep MagicParam 
Instance details

Defined in Magic.Types

type Rep MagicParam = D1 ('MetaData "MagicParam" "Magic.Types" "magic-2.0.0-A9TYcUdA1HUI3Y62VpQyfB" 'False) (((C1 ('MetaCons "MagicParamIndirMax" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "MagicParamNameMax" 'PrefixI 'False) (U1 :: Type -> Type)) :+: (C1 ('MetaCons "MagicParamElfPhnumMax" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "MagicParamElfShnumMax" 'PrefixI 'False) (U1 :: Type -> Type))) :+: ((C1 ('MetaCons "MagicParamElfNotesMax" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "MagicParamRegexMax" 'PrefixI 'False) (U1 :: Type -> Type)) :+: (C1 ('MetaCons "MagicParamBytesMax" 'PrefixI 'False) (U1 :: Type -> Type) :+: (C1 ('MetaCons "MagicParamEncodingMax" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "MagicParamElfShsizeMax" 'PrefixI 'False) (U1 :: Type -> Type)))))

Methods

from :: MagicParam -> Rep MagicParam x

to :: Rep MagicParam x -> MagicParam

Show MagicParam Source # 
Instance details

Defined in Magic.Types

Methods

showsPrec :: Int -> MagicParam -> ShowS

show :: MagicParam -> String

showList :: [MagicParam] -> ShowS

Eq MagicParam Source # 
Instance details

Defined in Magic.Types

Methods

(==) :: MagicParam -> MagicParam -> Bool

(/=) :: MagicParam -> MagicParam -> Bool

Ord MagicParam Source # 
Instance details

Defined in Magic.Types

type Rep MagicParam Source # 
Instance details

Defined in Magic.Types

type Rep MagicParam = D1 ('MetaData "MagicParam" "Magic.Types" "magic-2.0.0-A9TYcUdA1HUI3Y62VpQyfB" 'False) (((C1 ('MetaCons "MagicParamIndirMax" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "MagicParamNameMax" 'PrefixI 'False) (U1 :: Type -> Type)) :+: (C1 ('MetaCons "MagicParamElfPhnumMax" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "MagicParamElfShnumMax" 'PrefixI 'False) (U1 :: Type -> Type))) :+: ((C1 ('MetaCons "MagicParamElfNotesMax" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "MagicParamRegexMax" 'PrefixI 'False) (U1 :: Type -> Type)) :+: (C1 ('MetaCons "MagicParamBytesMax" 'PrefixI 'False) (U1 :: Type -> Type) :+: (C1 ('MetaCons "MagicParamEncodingMax" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "MagicParamElfShsizeMax" 'PrefixI 'False) (U1 :: Type -> Type)))))

magicFile :: Magic -> FilePath -> IO Text Source #

magicFile taking a FilePath.

magicLoad :: Magic -> [FilePath] -> IO () Source #

magicLoad taking FilePaths (empty list = the default database).

magicCompile :: Magic -> [FilePath] -> IO () Source #

magicCompile taking FilePaths (empty list = the default database).

magicCheck :: Magic -> [FilePath] -> IO Bool Source #

magicCheck taking FilePaths (empty list = the default database).

magicGetPath :: IO [FilePath] Source #

magicGetPath returning FilePaths.