| Copyright | Copyright (C) 2005 John Goerzen |
|---|---|
| License | BSD-3-Clause |
| Maintainer | Philippe <philippedev101\@gmail.com> |
| Stability | provisional |
| Portability | portable |
| Safe Haskell | None |
| Language | Haskell2010 |
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
- pattern MagicApple :: MagicFlags
- pattern MagicCheck :: MagicFlags
- pattern MagicCompress :: MagicFlags
- pattern MagicCompressTransp :: MagicFlags
- pattern MagicContinue :: MagicFlags
- pattern MagicDebug :: MagicFlags
- pattern MagicDevices :: MagicFlags
- pattern MagicError :: MagicFlags
- pattern MagicExtension :: MagicFlags
- pattern MagicMime :: MagicFlags
- pattern MagicMimeEncoding :: MagicFlags
- pattern MagicMimeType :: MagicFlags
- pattern MagicNoCheckApptype :: MagicFlags
- pattern MagicNoCheckBuiltin :: MagicFlags
- pattern MagicNoCheckCdf :: MagicFlags
- pattern MagicNoCheckCompress :: MagicFlags
- pattern MagicNoCheckCsv :: MagicFlags
- pattern MagicNoCheckElf :: MagicFlags
- pattern MagicNoCheckEncoding :: MagicFlags
- pattern MagicNoCheckJson :: MagicFlags
- pattern MagicNoCheckSimh :: MagicFlags
- pattern MagicNoCheckSoft :: MagicFlags
- pattern MagicNoCheckTar :: MagicFlags
- pattern MagicNoCheckText :: MagicFlags
- pattern MagicNoCheckTokens :: MagicFlags
- pattern MagicNoCompressFork :: MagicFlags
- pattern MagicNodesc :: MagicFlags
- pattern MagicNone :: MagicFlags
- pattern MagicPreserveAtime :: MagicFlags
- pattern MagicRaw :: MagicFlags
- pattern MagicSymlink :: MagicFlags
- hasFlag :: MagicFlags -> MagicFlags -> Bool
- removeFlags :: MagicFlags -> MagicFlags -> MagicFlags
- magicLoadDefault :: Magic -> IO ()
- magicOpen :: MagicFlags -> IO Magic
- magicByteString :: Magic -> ByteString -> IO Text
- magicCString :: Magic -> CStringLen -> IO Text
- magicDescriptor :: Magic -> Fd -> IO Text
- magicErrno :: Magic -> IO Int
- magicGetFlags :: Magic -> IO MagicFlags
- magicGetParam :: Magic -> MagicParam -> IO Int
- magicLoadBuffers :: Magic -> [ByteString] -> IO ()
- magicSetFlags :: Magic -> MagicFlags -> IO ()
- magicSetParam :: Magic -> MagicParam -> Int -> IO ()
- magicStdin :: Magic -> IO Text
- magicVersion :: IO Int
- newtype MagicFlags = MagicFlags CInt
- data Magic
- data MagicException = MagicException {
- magicErrorContext :: !Text
- magicErrorMessage :: !Text
- data MagicParam
- magicFile :: Magic -> FilePath -> IO Text
- magicLoad :: Magic -> [FilePath] -> IO ()
- magicCompile :: Magic -> [FilePath] -> IO ()
- magicCheck :: Magic -> [FilePath] -> IO Bool
- magicGetPath :: IO [FilePath]
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 #
removeFlags :: MagicFlags -> MagicFlags -> MagicFlags Source #
clears every bit of removeFlags fs dropdrop 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
| NFData MagicFlags Source # | |||||
Defined in Magic.Data Methods rnf :: MagicFlags -> () | |||||
| Monoid MagicFlags Source # |
| ||||
Defined in Magic.Data Methods mempty :: MagicFlags mappend :: MagicFlags -> MagicFlags -> MagicFlags mconcat :: [MagicFlags] -> MagicFlags | |||||
| Semigroup MagicFlags Source # | Flags combine by bitwise-or. | ||||
Defined in Magic.Data Methods (<>) :: MagicFlags -> MagicFlags -> MagicFlags sconcat :: NonEmpty MagicFlags -> MagicFlags stimes :: Integral b => b -> MagicFlags -> MagicFlags | |||||
| Generic MagicFlags Source # | |||||
Defined in Magic.Data Associated Types
| |||||
| Show MagicFlags Source # | Prints the set flags by name (e.g. | ||||
Defined in Magic.Data Methods showsPrec :: Int -> MagicFlags -> ShowS show :: MagicFlags -> String showList :: [MagicFlags] -> ShowS | |||||
| Eq MagicFlags Source # | |||||
Defined in Magic.Data | |||||
| Ord MagicFlags Source # | |||||
Defined in Magic.Data Methods compare :: MagicFlags -> MagicFlags -> Ordering (<) :: MagicFlags -> MagicFlags -> Bool (<=) :: MagicFlags -> MagicFlags -> Bool (>) :: MagicFlags -> MagicFlags -> Bool (>=) :: MagicFlags -> MagicFlags -> Bool max :: MagicFlags -> MagicFlags -> MagicFlags min :: MagicFlags -> MagicFlags -> MagicFlags | |||||
| type Rep MagicFlags Source # | |||||
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))) | |||||
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).
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
| NFData MagicException Source # | |||||
Defined in Magic.Internal Methods rnf :: MagicException -> () | |||||
| Exception MagicException Source # | |||||
Defined in Magic.Internal Methods toException :: MagicException -> SomeException fromException :: SomeException -> Maybe MagicException displayException :: MagicException -> String backtraceDesired :: MagicException -> Bool | |||||
| Generic MagicException Source # | |||||
Defined in Magic.Internal Associated Types
| |||||
| Show MagicException Source # | |||||
Defined in Magic.Internal Methods showsPrec :: Int -> MagicException -> ShowS show :: MagicException -> String showList :: [MagicException] -> ShowS | |||||
| Eq MagicException Source # | |||||
Defined in Magic.Internal Methods (==) :: MagicException -> MagicException -> Bool (/=) :: MagicException -> MagicException -> Bool | |||||
| type Rep MagicException Source # | |||||
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
| NFData MagicParam Source # | |||||
Defined in Magic.Types Methods rnf :: MagicParam -> () | |||||
| Bounded MagicParam Source # | |||||
Defined in Magic.Types | |||||
| Enum MagicParam Source # | |||||
Defined in Magic.Types Methods succ :: MagicParam -> MagicParam pred :: MagicParam -> MagicParam toEnum :: Int -> MagicParam fromEnum :: MagicParam -> Int enumFrom :: MagicParam -> [MagicParam] enumFromThen :: MagicParam -> MagicParam -> [MagicParam] enumFromTo :: MagicParam -> MagicParam -> [MagicParam] enumFromThenTo :: MagicParam -> MagicParam -> MagicParam -> [MagicParam] | |||||
| Generic MagicParam Source # | |||||
Defined in Magic.Types Associated Types
| |||||
| Show MagicParam Source # | |||||
Defined in Magic.Types Methods showsPrec :: Int -> MagicParam -> ShowS show :: MagicParam -> String showList :: [MagicParam] -> ShowS | |||||
| Eq MagicParam Source # | |||||
Defined in Magic.Types | |||||
| Ord MagicParam Source # | |||||
Defined in Magic.Types Methods compare :: MagicParam -> MagicParam -> Ordering (<) :: MagicParam -> MagicParam -> Bool (<=) :: MagicParam -> MagicParam -> Bool (>) :: MagicParam -> MagicParam -> Bool (>=) :: MagicParam -> MagicParam -> Bool max :: MagicParam -> MagicParam -> MagicParam min :: MagicParam -> MagicParam -> MagicParam | |||||
| type Rep MagicParam Source # | |||||
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))))) | |||||
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.