-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | This package provides a Haskell interface to the C libmagic library.
--   With it, you can determine the type of a file by examining its
--   contents rather than its name. The Haskell interface provides a
--   full-featured binding.
--   
--   Note: this package requires the C libmagic library (part of the
--   <tt>file</tt> package) and its development headers to be installed at
--   build time.
@package magic
@version 2.0.0


-- | The <a>MagicFlags</a> bit-mask, mapping the C <tt>libmagic</tt>
--   <tt>MAGIC_*</tt> constants to Haskell. Flags are combined with
--   <tt>(<a>&lt;&gt;</a>)</tt>, tested with <a>hasFlag</a>, and narrowed
--   with <a>removeFlags</a>; the empty set (<a>mempty</a>) is
--   <a>MagicNone</a>.
module Magic.Data

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

-- | <tt><a>hasFlag</a> fs flag</tt> is <a>True</a> when every bit of
--   <tt>flag</tt> is set in <tt>fs</tt>. Works for composite flags too
--   (e.g. <tt>fs `hasFlag` <a>MagicMime</a></tt>). Note that <tt>fs
--   `hasFlag` <a>MagicNone</a></tt> is always <a>True</a> (the empty set
--   is a subset of everything).
hasFlag :: MagicFlags -> MagicFlags -> Bool

-- | <tt><a>removeFlags</a> fs drop</tt> clears every bit of <tt>drop</tt>
--   from <tt>fs</tt> (set difference), e.g. <tt>flags `removeFlags`
--   <a>MagicError</a></tt>.
removeFlags :: MagicFlags -> MagicFlags -> MagicFlags

-- | No special handling; return a textual description (the default). This
--   is <a>mempty</a>.
pattern MagicNone :: MagicFlags

-- | Print debugging messages to stderr.
pattern MagicDebug :: MagicFlags

-- | Follow symbolic links.
pattern MagicSymlink :: MagicFlags

-- | Look inside compressed files.
pattern MagicCompress :: MagicFlags

-- | Look at the contents of block or character special devices.
pattern MagicDevices :: MagicFlags

-- | Return a MIME type string instead of a textual description.
pattern MagicMimeType :: MagicFlags

-- | Return the MIME encoding (character set) instead of a textual
--   description.
pattern MagicMimeEncoding :: MagicFlags

-- | Return both the MIME type and the encoding (<tt><a>MagicMimeType</a>
--   <a>&lt;&gt;</a> <a>MagicMimeEncoding</a></tt>).
pattern MagicMime :: MagicFlags

-- | Return all matches, not just the first.
pattern MagicContinue :: MagicFlags

-- | Check the magic database for consistency and report problems.
pattern MagicCheck :: MagicFlags

-- | Preserve the access time of examined files.
pattern MagicPreserveAtime :: MagicFlags

-- | Do not translate unprintable characters to octal escapes.
pattern MagicRaw :: MagicFlags

-- | Treat errors while examining a file as real errors instead of
--   embedding them in the result.
pattern MagicError :: MagicFlags

-- | Return the Apple creator and type.
pattern MagicApple :: MagicFlags

-- | Return a slash-separated list of valid file extensions for the
--   detected type.
pattern MagicExtension :: MagicFlags

-- | Report on the compressed contents only, without mentioning the
--   compression itself (transparent decompression).
pattern MagicCompressTransp :: MagicFlags

-- | Do not allow decompression that requires forking a helper process.
pattern MagicNoCompressFork :: MagicFlags

-- | Composite of <a>MagicExtension</a>, <a>MagicMime</a> and
--   <a>MagicApple</a>: return identifiers rather than a textual
--   description.
pattern MagicNodesc :: MagicFlags

-- | Do not look inside compressed files.
pattern MagicNoCheckCompress :: MagicFlags

-- | Do not examine tar archives.
pattern MagicNoCheckTar :: MagicFlags

-- | Do not consult the magic database entries (soft magic).
pattern MagicNoCheckSoft :: MagicFlags

-- | Do not check for an application type (e.g. EMX).
pattern MagicNoCheckApptype :: MagicFlags

-- | Do not examine ELF details.
pattern MagicNoCheckElf :: MagicFlags

-- | Do not examine text files.
pattern MagicNoCheckText :: MagicFlags

-- | Do not examine CDF (Microsoft Compound Document) files.
pattern MagicNoCheckCdf :: MagicFlags

-- | Do not examine CSV files.
pattern MagicNoCheckCsv :: MagicFlags

-- | Do not look for known text tokens.
pattern MagicNoCheckTokens :: MagicFlags

-- | Do not check text encodings.
pattern MagicNoCheckEncoding :: MagicFlags

-- | Do not examine JSON files.
pattern MagicNoCheckJson :: MagicFlags

-- | Do not examine SIMH tape files.
pattern MagicNoCheckSimh :: MagicFlags

-- | Disable all built-in tests; consult only the magic database.
pattern MagicNoCheckBuiltin :: MagicFlags
instance GHC.Classes.Eq Magic.Data.MagicFlags
instance GHC.Internal.Generics.Generic Magic.Data.MagicFlags
instance GHC.Internal.Base.Monoid Magic.Data.MagicFlags
instance Control.DeepSeq.NFData Magic.Data.MagicFlags
instance GHC.Classes.Ord Magic.Data.MagicFlags
instance GHC.Internal.Base.Semigroup Magic.Data.MagicFlags
instance GHC.Internal.Show.Show Magic.Data.MagicFlags


-- | Creating a magic handle and loading magic databases into it. A handle
--   returned by <a>magicOpen</a> must be given a database with
--   <a>magicLoadDefault</a> or <a>magicLoad</a> before it can be queried
--   with the functions in <a>Magic.Operations</a>.
--   
--   Written by John Goerzen.
module Magic.Init

-- | Create a new magic handle configured with the given flags. Combine
--   flags with <tt>(<a>&lt;&gt;</a>)</tt> (see <a>MagicFlags</a>), or pass
--   <a>mempty</a> for the defaults. Before querying anything you must load
--   a database with <a>magicLoadDefault</a> or <a>magicLoad</a>.
--   
--   The handle is freed automatically when it is garbage-collected. Raises
--   an <a>IOError</a> if the handle cannot be created.
magicOpen :: MagicFlags -> IO Magic

-- | Load the given magic database(s) into the handle. Pass the empty list
--   to load the system default (equivalent to <a>magicLoadDefault</a>).
--   Raises a <tt>MagicException</tt> if a database cannot be loaded.
--   
--   (libmagic joins the list with the platform search-path separator, so a
--   path that itself contains that separator cannot be represented.)
magicLoad :: Magic -> [OsPath] -> IO ()

-- | Load the system's default magic database into the handle. Raises a
--   <tt>MagicException</tt> if the database cannot be loaded.
magicLoadDefault :: Magic -> IO ()


-- | The core types of the binding: the opaque <a>Magic</a> handle, the
--   <a>MagicException</a> error type (both defined in
--   <a>Magic.Internal</a>), and the <a>MagicParam</a> tunables. The flag
--   bit-mask lives in <a>Magic.Data</a>.
module Magic.Types

-- | The magic handle: an opaque cookie obtained from <tt>magicOpen</tt>
--   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.
--   
--   <b>Thread safety.</b> 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 (<tt>-threaded</tt>).
data Magic

-- | The exception raised when a <tt>libmagic</tt> operation fails. Carries
--   the name of the operation that failed and the message reported by
--   <tt>libmagic</tt>.
data MagicException
MagicException :: !Text -> !Text -> MagicException

-- | the operation that failed, e.g. <tt>"magicFile"</tt>
[magicErrorContext] :: MagicException -> !Text

-- | <tt>libmagic</tt>'s error message
[magicErrorMessage] :: MagicException -> !Text

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

-- | Maximum number of levels of recursion when following indirect magic.
--   (Default: 15.)
MagicParamIndirMax :: MagicParam

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

-- | Maximum number of ELF program header sections processed. (Default:
--   128.)
MagicParamElfPhnumMax :: MagicParam

-- | Maximum number of ELF section header sections processed. (Default:
--   32768.)
MagicParamElfShnumMax :: MagicParam

-- | Maximum number of ELF notes processed. (Default: 256.)
MagicParamElfNotesMax :: MagicParam

-- | Maximum length of a regex search. (Default: 8192.)
MagicParamRegexMax :: MagicParam

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

-- | Maximum number of bytes scanned when guessing a text encoding.
MagicParamEncodingMax :: MagicParam

-- | Maximum size of an ELF section processed.
MagicParamElfShsizeMax :: MagicParam
instance GHC.Internal.Enum.Bounded Magic.Types.MagicParam
instance GHC.Internal.Enum.Enum Magic.Types.MagicParam
instance GHC.Classes.Eq Magic.Types.MagicParam
instance GHC.Internal.Generics.Generic Magic.Types.MagicParam
instance Control.DeepSeq.NFData Magic.Types.MagicParam
instance GHC.Classes.Ord Magic.Types.MagicParam
instance GHC.Internal.Show.Show Magic.Types.MagicParam


-- | Querying the type of files and in-memory data, and other operations on
--   a magic handle. The handle must first be created with
--   <tt>magicOpen</tt> and populated with <tt>magicLoadDefault</tt> or
--   <tt>magicLoad</tt> (see <a>Magic.Init</a>).
--   
--   Written by John Goerzen.
module Magic.Operations

-- | Identify the file at the given path. The result is in the form
--   selected by the handle's flags (a textual description, a MIME type, an
--   encoding, and so on; see <a>MagicFlags</a>). Raises a
--   <tt>MagicException</tt> if the file cannot be examined.
magicFile :: Magic -> OsPath -> IO Text

-- | Identify the data available on standard input, as <a>magicFile</a>
--   does for a named file. Raises a <tt>MagicException</tt> if the data
--   cannot be examined.
magicStdin :: Magic -> IO Text

-- | Identify the data behind an open file descriptor, as <a>magicFile</a>
--   does for a named file. Useful for sockets, pipes, or files you have
--   already opened. Raises a <tt>MagicException</tt> if the descriptor
--   cannot be examined.
magicDescriptor :: Magic -> Fd -> IO Text

-- | Identify the contents of a C string buffer (a pointer and a length).
--   The lowest-level in-memory primitive; for ordinary use prefer
--   <a>magicByteString</a>. Raises a <tt>MagicException</tt> if the data
--   cannot be examined.
magicCString :: Magic -> CStringLen -> IO Text

-- | Identify the contents of a strict <a>ByteString</a>. Does no encoding
--   conversion, so it is the right way to examine in-memory data. Raises a
--   <tt>MagicException</tt> if the data cannot be examined.
magicByteString :: Magic -> ByteString -> IO Text

-- | Change the flags (see <a>MagicFlags</a>) on an existing handle, for
--   example to switch between textual descriptions and MIME types. Raises
--   a <tt>MagicException</tt> on failure.
magicSetFlags :: Magic -> MagicFlags -> IO ()

-- | Read the flags currently set on the handle (see <a>magicSetFlags</a>).
--   Test the result with <tt>hasFlag</tt>. Raises a
--   <tt>MagicException</tt> if the running <tt>libmagic</tt> does not
--   support querying flags.
magicGetFlags :: Magic -> IO MagicFlags

-- | Read a tunable parameter (see <a>MagicParam</a>).
magicGetParam :: Magic -> MagicParam -> IO Int

-- | Set a tunable parameter (see <a>MagicParam</a>), for example to cap
--   the number of bytes scanned in untrusted input. Raises a
--   <tt>MagicException</tt> on failure.
magicSetParam :: Magic -> MagicParam -> Int -> IO ()

-- | Compile the given magic database file(s) into the binary <tt>.mgc</tt>
--   form. Each compiled file is named after its source with <tt>.mgc</tt>
--   appended. Pass the empty list to compile the default database. Raises
--   a <tt>MagicException</tt> on failure.
--   
--   (libmagic joins the list with the platform search-path separator, so a
--   path that itself contains that separator cannot be represented.)
magicCompile :: Magic -> [OsPath] -> IO ()

-- | Check the validity of the given magic database file(s) without
--   compiling them, as <tt>file -c</tt> does. Pass the empty list for the
--   default database. Returns <a>True</a> if the database is valid.
--   (libmagic joins the list with the platform search-path separator, so a
--   path that itself contains that separator cannot be represented.)
magicCheck :: Magic -> [OsPath] -> IO Bool

-- | Load magic from one or more in-memory compiled databases (the
--   <tt>.mgc</tt> binary form produced by <a>magicCompile</a>), rather
--   than from files. This lets a program embed its magic database.
--   
--   <tt>libmagic</tt> keeps (does not copy) the supplied buffers for the
--   lifetime of the handle, so the handle retains references to the given
--   <a>ByteString</a>s to keep their memory alive until it is closed.
--   Raises a <tt>MagicException</tt> on failure.
magicLoadBuffers :: Magic -> [ByteString] -> IO ()

-- | The default magic database search path, honouring the <tt>MAGIC</tt>
--   environment variable, as a list of paths.
magicGetPath :: IO [OsPath]

-- | The version of the <tt>libmagic</tt> library in use, encoded as a
--   single integer (for example <tt>545</tt> for version 5.45).
magicVersion :: IO Int

-- | The <tt>errno</tt> recorded by the last failing operation on the
--   handle, or <tt>0</tt> if the last failure was not caused by a system
--   error.
magicErrno :: Magic -> IO Int


-- | Haskell bindings to the C <tt>libmagic</tt> library, which identifies
--   the type of a file by inspecting its contents rather than its name. It
--   can report a textual description, a MIME type, or a character-set
--   encoding.
--   
--   This top-level module re-exports the whole interface: the types in
--   <a>Magic.Types</a>, the initialization functions in <a>Magic.Init</a>,
--   and the querying functions in <a>Magic.Operations</a>.
--   
--   If you just want to pass ordinary <tt>String</tt> paths, start with
--   <a>Magic.FilePath</a>, a drop-in facade over this module. The
--   functions here take <a>OsPath</a> instead, which represents any
--   filename losslessly and independently of the locale (see the note
--   below).
--   
--   A typical session creates a handle, loads the system magic database,
--   then queries files or in-memory data. The flags passed to
--   <a>magicOpen</a> choose what kind of answer comes back (see
--   <a>MagicFlags</a>); combine them with <tt>(<a>&lt;&gt;</a>)</tt> and
--   use <a>mempty</a> (i.e. <a>MagicNone</a>) for the defaults:
--   
--   <pre>
--   {-# LANGUAGE QuasiQuotes #-}
--   import Magic
--   import System.OsPath (osp)
--   import qualified Data.Text.IO as T
--   
--   main :: IO ()
--   main = do
--     magic &lt;- magicOpen MagicMimeType     -- ask for MIME types
--     magicLoadDefault magic               -- load the system database
--     mime &lt;- magicFile magic [osp|/etc/passwd|]
--     T.putStrLn mime                      -- e.g. "text/plain"
--   </pre>
--   
--   Paths here are <a>OsPath</a>, which stores the OS-native path bytes
--   verbatim and so represents any path the system can, without a lossy
--   locale round-trip. The <a>Magic.FilePath</a> facade offers the same
--   API with <tt>String</tt> paths for convenience; it is fine for
--   ordinary filenames, but cannot faithfully represent names whose bytes
--   are invalid in the current locale.
--   
--   Handles are closed and their memory freed automatically when they are
--   garbage-collected (see <a>Magic</a>); there is no explicit close. On
--   failure, most operations raise a <a>MagicException</a>;
--   <a>magicOpen</a> raises an <a>IOError</a> (from <tt>errno</tt>) if the
--   handle cannot be allocated.
--   
--   Originally written by John Goerzen.
module Magic


-- | A convenience facade over <a>Magic</a> that takes ordinary
--   <a>FilePath</a>s instead of <a>OsPath</a>s. Import this module
--   <i>instead of</i> <a>Magic</a> if you prefer <tt>String</tt> paths:
--   
--   <pre>
--   import Magic.FilePath
--   </pre>
--   
--   Everything else (the handle, flags, in-memory and descriptor queries,
--   and so on) is re-exported unchanged from <a>Magic</a>.
--   
--   The <a>FilePath</a> wrappers convert with <a>encodeFS</a> /
--   <a>decodeFS</a>, which go through the locale's filesystem encoding.
--   For ordinary ASCII/UTF-8 filenames under a UTF-8 locale this is fine.
--   But a <a>FilePath</a> 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
--   <tt>OsPath</tt> functions in <a>Magic</a> store the path bytes
--   verbatim and avoid this entirely; prefer them when correctness on
--   arbitrary filenames matters.
module Magic.FilePath

-- | Return the Apple creator and type.
pattern MagicApple :: MagicFlags

-- | Check the magic database for consistency and report problems.
pattern MagicCheck :: MagicFlags

-- | Look inside compressed files.
pattern MagicCompress :: MagicFlags

-- | Report on the compressed contents only, without mentioning the
--   compression itself (transparent decompression).
pattern MagicCompressTransp :: MagicFlags

-- | Return all matches, not just the first.
pattern MagicContinue :: MagicFlags

-- | Print debugging messages to stderr.
pattern MagicDebug :: MagicFlags

-- | Look at the contents of block or character special devices.
pattern MagicDevices :: MagicFlags

-- | Treat errors while examining a file as real errors instead of
--   embedding them in the result.
pattern MagicError :: MagicFlags

-- | Return a slash-separated list of valid file extensions for the
--   detected type.
pattern MagicExtension :: MagicFlags

-- | Return both the MIME type and the encoding (<tt><a>MagicMimeType</a>
--   <a>&lt;&gt;</a> <a>MagicMimeEncoding</a></tt>).
pattern MagicMime :: MagicFlags

-- | Return the MIME encoding (character set) instead of a textual
--   description.
pattern MagicMimeEncoding :: MagicFlags

-- | Return a MIME type string instead of a textual description.
pattern MagicMimeType :: MagicFlags

-- | Do not check for an application type (e.g. EMX).
pattern MagicNoCheckApptype :: MagicFlags

-- | Disable all built-in tests; consult only the magic database.
pattern MagicNoCheckBuiltin :: MagicFlags

-- | Do not examine CDF (Microsoft Compound Document) files.
pattern MagicNoCheckCdf :: MagicFlags

-- | Do not look inside compressed files.
pattern MagicNoCheckCompress :: MagicFlags

-- | Do not examine CSV files.
pattern MagicNoCheckCsv :: MagicFlags

-- | Do not examine ELF details.
pattern MagicNoCheckElf :: MagicFlags

-- | Do not check text encodings.
pattern MagicNoCheckEncoding :: MagicFlags

-- | Do not examine JSON files.
pattern MagicNoCheckJson :: MagicFlags

-- | Do not examine SIMH tape files.
pattern MagicNoCheckSimh :: MagicFlags

-- | Do not consult the magic database entries (soft magic).
pattern MagicNoCheckSoft :: MagicFlags

-- | Do not examine tar archives.
pattern MagicNoCheckTar :: MagicFlags

-- | Do not examine text files.
pattern MagicNoCheckText :: MagicFlags

-- | Do not look for known text tokens.
pattern MagicNoCheckTokens :: MagicFlags

-- | Do not allow decompression that requires forking a helper process.
pattern MagicNoCompressFork :: MagicFlags

-- | Composite of <a>MagicExtension</a>, <a>MagicMime</a> and
--   <a>MagicApple</a>: return identifiers rather than a textual
--   description.
pattern MagicNodesc :: MagicFlags

-- | No special handling; return a textual description (the default). This
--   is <a>mempty</a>.
pattern MagicNone :: MagicFlags

-- | Preserve the access time of examined files.
pattern MagicPreserveAtime :: MagicFlags

-- | Do not translate unprintable characters to octal escapes.
pattern MagicRaw :: MagicFlags

-- | Follow symbolic links.
pattern MagicSymlink :: MagicFlags

-- | <tt><a>hasFlag</a> fs flag</tt> is <a>True</a> when every bit of
--   <tt>flag</tt> is set in <tt>fs</tt>. Works for composite flags too
--   (e.g. <tt>fs `hasFlag` <a>MagicMime</a></tt>). Note that <tt>fs
--   `hasFlag` <a>MagicNone</a></tt> is always <a>True</a> (the empty set
--   is a subset of everything).
hasFlag :: MagicFlags -> MagicFlags -> Bool

-- | <tt><a>removeFlags</a> fs drop</tt> clears every bit of <tt>drop</tt>
--   from <tt>fs</tt> (set difference), e.g. <tt>flags `removeFlags`
--   <a>MagicError</a></tt>.
removeFlags :: MagicFlags -> MagicFlags -> MagicFlags

-- | Load the system's default magic database into the handle. Raises a
--   <tt>MagicException</tt> if the database cannot be loaded.
magicLoadDefault :: Magic -> IO ()

-- | Create a new magic handle configured with the given flags. Combine
--   flags with <tt>(<a>&lt;&gt;</a>)</tt> (see <a>MagicFlags</a>), or pass
--   <a>mempty</a> for the defaults. Before querying anything you must load
--   a database with <a>magicLoadDefault</a> or <a>magicLoad</a>.
--   
--   The handle is freed automatically when it is garbage-collected. Raises
--   an <a>IOError</a> if the handle cannot be created.
magicOpen :: MagicFlags -> IO Magic

-- | Identify the contents of a strict <a>ByteString</a>. Does no encoding
--   conversion, so it is the right way to examine in-memory data. Raises a
--   <tt>MagicException</tt> if the data cannot be examined.
magicByteString :: Magic -> ByteString -> IO Text

-- | Identify the contents of a C string buffer (a pointer and a length).
--   The lowest-level in-memory primitive; for ordinary use prefer
--   <a>magicByteString</a>. Raises a <tt>MagicException</tt> if the data
--   cannot be examined.
magicCString :: Magic -> CStringLen -> IO Text

-- | Identify the data behind an open file descriptor, as <a>magicFile</a>
--   does for a named file. Useful for sockets, pipes, or files you have
--   already opened. Raises a <tt>MagicException</tt> if the descriptor
--   cannot be examined.
magicDescriptor :: Magic -> Fd -> IO Text

-- | The <tt>errno</tt> recorded by the last failing operation on the
--   handle, or <tt>0</tt> if the last failure was not caused by a system
--   error.
magicErrno :: Magic -> IO Int

-- | Read the flags currently set on the handle (see <a>magicSetFlags</a>).
--   Test the result with <tt>hasFlag</tt>. Raises a
--   <tt>MagicException</tt> if the running <tt>libmagic</tt> does not
--   support querying flags.
magicGetFlags :: Magic -> IO MagicFlags

-- | Read a tunable parameter (see <a>MagicParam</a>).
magicGetParam :: Magic -> MagicParam -> IO Int

-- | Load magic from one or more in-memory compiled databases (the
--   <tt>.mgc</tt> binary form produced by <a>magicCompile</a>), rather
--   than from files. This lets a program embed its magic database.
--   
--   <tt>libmagic</tt> keeps (does not copy) the supplied buffers for the
--   lifetime of the handle, so the handle retains references to the given
--   <a>ByteString</a>s to keep their memory alive until it is closed.
--   Raises a <tt>MagicException</tt> on failure.
magicLoadBuffers :: Magic -> [ByteString] -> IO ()

-- | Change the flags (see <a>MagicFlags</a>) on an existing handle, for
--   example to switch between textual descriptions and MIME types. Raises
--   a <tt>MagicException</tt> on failure.
magicSetFlags :: Magic -> MagicFlags -> IO ()

-- | Set a tunable parameter (see <a>MagicParam</a>), for example to cap
--   the number of bytes scanned in untrusted input. Raises a
--   <tt>MagicException</tt> on failure.
magicSetParam :: Magic -> MagicParam -> Int -> IO ()

-- | Identify the data available on standard input, as <a>magicFile</a>
--   does for a named file. Raises a <tt>MagicException</tt> if the data
--   cannot be examined.
magicStdin :: Magic -> IO Text

-- | The version of the <tt>libmagic</tt> library in use, encoded as a
--   single integer (for example <tt>545</tt> for version 5.45).
magicVersion :: IO Int

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

-- | The magic handle: an opaque cookie obtained from <tt>magicOpen</tt>
--   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.
--   
--   <b>Thread safety.</b> 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 (<tt>-threaded</tt>).
data Magic

-- | The exception raised when a <tt>libmagic</tt> operation fails. Carries
--   the name of the operation that failed and the message reported by
--   <tt>libmagic</tt>.
data MagicException
MagicException :: !Text -> !Text -> MagicException

-- | the operation that failed, e.g. <tt>"magicFile"</tt>
[magicErrorContext] :: MagicException -> !Text

-- | <tt>libmagic</tt>'s error message
[magicErrorMessage] :: MagicException -> !Text

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

-- | Maximum number of levels of recursion when following indirect magic.
--   (Default: 15.)
MagicParamIndirMax :: MagicParam

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

-- | Maximum number of ELF program header sections processed. (Default:
--   128.)
MagicParamElfPhnumMax :: MagicParam

-- | Maximum number of ELF section header sections processed. (Default:
--   32768.)
MagicParamElfShnumMax :: MagicParam

-- | Maximum number of ELF notes processed. (Default: 256.)
MagicParamElfNotesMax :: MagicParam

-- | Maximum length of a regex search. (Default: 8192.)
MagicParamRegexMax :: MagicParam

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

-- | Maximum number of bytes scanned when guessing a text encoding.
MagicParamEncodingMax :: MagicParam

-- | Maximum size of an ELF section processed.
MagicParamElfShsizeMax :: MagicParam

-- | <a>magicFile</a> taking a <a>FilePath</a>.
magicFile :: Magic -> FilePath -> IO Text

-- | <a>magicLoad</a> taking <a>FilePath</a>s (empty list = the default
--   database).
magicLoad :: Magic -> [FilePath] -> IO ()

-- | <a>magicCompile</a> taking <a>FilePath</a>s (empty list = the default
--   database).
magicCompile :: Magic -> [FilePath] -> IO ()

-- | <a>magicCheck</a> taking <a>FilePath</a>s (empty list = the default
--   database).
magicCheck :: Magic -> [FilePath] -> IO Bool

-- | <a>magicGetPath</a> returning <a>FilePath</a>s.
magicGetPath :: IO [FilePath]
