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


-- | Memory mapped files for POSIX and Windows
--   
--   This library provides a wrapper to mmap(2) or MapViewOfFile, allowing
--   files or devices to be lazily loaded into memory as strict or lazy
--   ByteStrings, ForeignPtrs or plain Ptrs, using the virtual memory
--   subsystem to do on-demand loading. Modifications are also supported.
@package mmap
@version 0.5.9


-- | This library provides a wrapper to mmap(2) or MapViewOfFile, allowing
--   files or devices to be lazily loaded into memory as strict or lazy
--   ByteStrings, ForeignPtrs or plain Ptrs, using the virtual memory
--   subsystem to do on-demand loading. Modifications are also supported.
module System.IO.MMap

-- | Mode of mapping. Four cases are supported.
data Mode

-- | file is mapped read-only, file must exist
ReadOnly :: Mode

-- | file is mapped read-write, file must exist
ReadWrite :: Mode

-- | file is mapped read-write, but changes aren't propagated to disk, file
--   must exist
WriteCopy :: Mode

-- | file is mapped read-write, if file does not exist it will be created
--   with default permissions, region parameter specifies size, if file
--   size is lower it will be extended with zeros
ReadWriteEx :: Mode

-- | The <a>mmapFilePtr</a> function maps a file or device into memory,
--   returning a tuple <tt>(ptr,rawsize,offset,size)</tt> where:
--   
--   <ul>
--   <li><tt>ptr</tt> is pointer to mmapped region</li>
--   <li><tt>rawsize</tt> is length (in bytes) of mapped data, rawsize
--   might be greater than size because of alignment</li>
--   <li><tt>offset</tt> tell where your data lives: <tt>plusPtr ptr
--   offset</tt></li>
--   <li><tt>size</tt> your data length (in bytes)</li>
--   </ul>
--   
--   If <a>mmapFilePtr</a> fails for some reason, a <a>throwErrno</a> is
--   used.
--   
--   Use <tt>munmapFilePtr ptr rawsize</tt> to unmap memory.
--   
--   Memory mapped files will behave as if they were read lazily pages from
--   the file will be loaded into memory on demand.
mmapFilePtr :: FilePath -> Mode -> Maybe (Int64, Int) -> IO (Ptr a, Int, Int, Int)

-- | Memory map region of file using autounmap semantics. See
--   <a>mmapFilePtr</a> for description of parameters. The <tt>action</tt>
--   will be executed with tuple <tt>(ptr,size)</tt> as single argument.
--   This is the pointer to mapped data already adjusted and size of
--   requested region. Return value is that of action.
mmapWithFilePtr :: FilePath -> Mode -> Maybe (Int64, Int) -> ((Ptr (), Int) -> IO a) -> IO a

-- | Maps region of file and returns it as <a>ForeignPtr</a>. See
--   <a>mmapFilePtr</a> for details.
mmapFileForeignPtr :: FilePath -> Mode -> Maybe (Int64, Int) -> IO (ForeignPtr a, Int, Int)

-- | Maps region of file and returns it as <a>ByteString</a>. File is
--   mapped in in <a>ReadOnly</a> mode. See <a>mmapFilePtr</a> for details.
mmapFileByteString :: FilePath -> Maybe (Int64, Int) -> IO ByteString

-- | Unmaps memory region. As parameters use values marked as ptr and
--   rawsize in description of <a>mmapFilePtr</a>.
munmapFilePtr :: Ptr a -> Int -> IO ()

-- | The <a>mmapFileForeignPtrLazy</a> function maps a file or device into
--   memory, returning a list of tuples with the same meaning as in
--   function <a>mmapFileForeignPtr</a>.
--   
--   Chunks are really mapped into memory at the first inspection of a
--   chunk. They are kept in memory while they are referenced, garbage
--   collector takes care of the later.
mmapFileForeignPtrLazy :: FilePath -> Mode -> Maybe (Int64, Int64) -> IO [(ForeignPtr a, Int, Int)]

-- | Maps region of file and returns it as <a>ByteString</a>. File is
--   mapped in in <a>ReadOnly</a> mode. See <a>mmapFileForeignPtrLazy</a>
--   for details.
mmapFileByteStringLazy :: FilePath -> Maybe (Int64, Int64) -> IO ByteString
instance GHC.Read.Read System.IO.MMap.Mode
instance GHC.Show.Show System.IO.MMap.Mode
instance GHC.Enum.Enum System.IO.MMap.Mode
instance GHC.Classes.Ord System.IO.MMap.Mode
instance GHC.Classes.Eq System.IO.MMap.Mode
