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


-- | HFuse is a binding for the Linux FUSE library.
--   
--   Bindings for the FUSE library, compatible with OSXFUSE.
@package HFuse
@version 0.2.4.1


-- | A binding for the FUSE (Filesystem in USErspace) library
--   (<a>http://fuse.sourceforge.net/</a>), which allows filesystems to be
--   implemented as userspace processes.
--   
--   The binding tries to follow as much as possible current Haskell POSIX
--   interface in <a>System.Posix.Files</a> and
--   <a>System.Posix.Directory</a>.
--   
--   FUSE uses POSIX threads, so any Haskell application using this library
--   must be linked against a threaded runtime system (eg. using the
--   <tt>threaded</tt> GHC option).
module System.Fuse

-- | This record, given to <a>fuseMain</a>, binds each required file system
--   operations.
--   
--   Each field is named against <a>Posix</a> names. Matching Linux system
--   calls are also given as a reference.
--   
--   <tt>fh</tt> is the file handle type returned by <a>fuseOpen</a> and
--   subsequently passed to all other file operations.
data FuseOperations fh
FuseOperations :: (FilePath -> IO (Either Errno FileStat)) -> (FilePath -> IO (Either Errno FilePath)) -> (FilePath -> EntryType -> FileMode -> DeviceID -> IO Errno) -> (FilePath -> FileMode -> IO Errno) -> (FilePath -> IO Errno) -> (FilePath -> IO Errno) -> (FilePath -> FilePath -> IO Errno) -> (FilePath -> FilePath -> IO Errno) -> (FilePath -> FilePath -> IO Errno) -> (FilePath -> FileMode -> IO Errno) -> (FilePath -> UserID -> GroupID -> IO Errno) -> (FilePath -> FileOffset -> IO Errno) -> (FilePath -> EpochTime -> EpochTime -> IO Errno) -> (FilePath -> OpenMode -> OpenFileFlags -> IO (Either Errno fh)) -> (FilePath -> fh -> ByteCount -> FileOffset -> IO (Either Errno ByteString)) -> (FilePath -> fh -> ByteString -> FileOffset -> IO (Either Errno ByteCount)) -> (String -> IO (Either Errno FileSystemStats)) -> (FilePath -> fh -> IO Errno) -> (FilePath -> fh -> IO ()) -> (FilePath -> SyncType -> IO Errno) -> (FilePath -> IO Errno) -> (FilePath -> IO (Either Errno [(FilePath, FileStat)])) -> (FilePath -> IO Errno) -> (FilePath -> SyncType -> IO Errno) -> (FilePath -> Int -> IO Errno) -> IO () -> IO () -> FuseOperations fh

-- | Implements <a>getSymbolicLinkStatus</a> operation (POSIX
--   <tt>lstat(2)</tt>).
fuseGetFileStat :: FuseOperations fh -> FilePath -> IO (Either Errno FileStat)

-- | Implements <a>readSymbolicLink</a> operation (POSIX
--   <tt>readlink(2)</tt>). The returned <a>FilePath</a> might be truncated
--   depending on caller buffer size.
fuseReadSymbolicLink :: FuseOperations fh -> FilePath -> IO (Either Errno FilePath)

-- | Implements <a>createDevice</a> (POSIX <tt>mknod(2)</tt>). This
--   function will also be called for regular file creation.
fuseCreateDevice :: FuseOperations fh -> FilePath -> EntryType -> FileMode -> DeviceID -> IO Errno

-- | Implements <a>createDirectory</a> (POSIX <tt>mkdir(2)</tt>).
fuseCreateDirectory :: FuseOperations fh -> FilePath -> FileMode -> IO Errno

-- | Implements <a>removeLink</a> (POSIX <tt>unlink(2)</tt>).
fuseRemoveLink :: FuseOperations fh -> FilePath -> IO Errno

-- | Implements <a>removeDirectory</a> (POSIX <tt>rmdir(2)</tt>).
fuseRemoveDirectory :: FuseOperations fh -> FilePath -> IO Errno

-- | Implements <a>createSymbolicLink</a> (POSIX <tt>symlink(2)</tt>).
fuseCreateSymbolicLink :: FuseOperations fh -> FilePath -> FilePath -> IO Errno

-- | Implements <a>rename</a> (POSIX <tt>rename(2)</tt>).
fuseRename :: FuseOperations fh -> FilePath -> FilePath -> IO Errno

-- | Implements <a>createLink</a> (POSIX <tt>link(2)</tt>).
fuseCreateLink :: FuseOperations fh -> FilePath -> FilePath -> IO Errno

-- | Implements <a>setFileMode</a> (POSIX <tt>chmod(2)</tt>).
fuseSetFileMode :: FuseOperations fh -> FilePath -> FileMode -> IO Errno

-- | Implements <a>setOwnerAndGroup</a> (POSIX <tt>chown(2)</tt>).
fuseSetOwnerAndGroup :: FuseOperations fh -> FilePath -> UserID -> GroupID -> IO Errno

-- | Implements <a>setFileSize</a> (POSIX <tt>truncate(2)</tt>).
fuseSetFileSize :: FuseOperations fh -> FilePath -> FileOffset -> IO Errno

-- | Implements <a>setFileTimes</a> (POSIX <tt>utime(2)</tt>).
fuseSetFileTimes :: FuseOperations fh -> FilePath -> EpochTime -> EpochTime -> IO Errno

-- | Implements <a>openFd</a> (POSIX <tt>open(2)</tt>). On success, returns
--   <a>Right</a> of a filehandle-like value that will be passed to future
--   file operations; on failure, returns <a>Left</a> of the appropriate
--   <a>Errno</a>.
--   
--   No creation, exclusive access or truncating flags will be passed. This
--   should check that the operation is permitted for the given flags.
fuseOpen :: FuseOperations fh -> FilePath -> OpenMode -> OpenFileFlags -> IO (Either Errno fh)

-- | Implements Unix98 <tt>pread(2)</tt>. It differs from <a>fdRead</a> by
--   the explicit <a>FileOffset</a> argument. The <tt>fuse.h</tt>
--   documentation stipulates that this "should return exactly the number
--   of bytes requested except on EOF or error, otherwise the rest of the
--   data will be substituted with zeroes."
fuseRead :: FuseOperations fh -> FilePath -> fh -> ByteCount -> FileOffset -> IO (Either Errno ByteString)

-- | Implements Unix98 <tt>pwrite(2)</tt>. It differs from <a>fdWrite</a>
--   by the explicit <a>FileOffset</a> argument.
fuseWrite :: FuseOperations fh -> FilePath -> fh -> ByteString -> FileOffset -> IO (Either Errno ByteCount)

-- | Implements <tt>statfs(2)</tt>.
fuseGetFileSystemStats :: FuseOperations fh -> String -> IO (Either Errno FileSystemStats)

-- | Called when <tt>close(2)</tt> has been called on an open file. Note:
--   this does not mean that the file is released. This function may be
--   called more than once for each <tt>open(2)</tt>. The return value is
--   passed on to the <tt>close(2)</tt> system call.
fuseFlush :: FuseOperations fh -> FilePath -> fh -> IO Errno

-- | Called when an open file has all file descriptors closed and all
--   memory mappings unmapped. For every <tt>open</tt> call there will be
--   exactly one <tt>release</tt> call with the same flags. It is possible
--   to have a file opened more than once, in which case only the last
--   release will mean that no more reads or writes will happen on the
--   file.
fuseRelease :: FuseOperations fh -> FilePath -> fh -> IO ()

-- | Implements <tt>fsync(2)</tt>.
fuseSynchronizeFile :: FuseOperations fh -> FilePath -> SyncType -> IO Errno

-- | Implements <tt>opendir(3)</tt>. This method should check if the open
--   operation is permitted for this directory.
fuseOpenDirectory :: FuseOperations fh -> FilePath -> IO Errno

-- | Implements <tt>readdir(3)</tt>. The entire contents of the directory
--   should be returned as a list of tuples (corresponding to the first
--   mode of operation documented in <tt>fuse.h</tt>).
fuseReadDirectory :: FuseOperations fh -> FilePath -> IO (Either Errno [(FilePath, FileStat)])

-- | Implements <tt>closedir(3)</tt>.
fuseReleaseDirectory :: FuseOperations fh -> FilePath -> IO Errno

-- | Synchronize the directory's contents; analogous to
--   <a>fuseSynchronizeFile</a>.
fuseSynchronizeDirectory :: FuseOperations fh -> FilePath -> SyncType -> IO Errno

-- | Check file access permissions; this will be called for the access()
--   system call. If the <tt>default_permissions</tt> mount option is
--   given, this method is not called. This method is also not called under
--   Linux kernel versions 2.4.x
fuseAccess :: FuseOperations fh -> FilePath -> Int -> IO Errno

-- | Initializes the filesystem. This is called before all other
--   operations.
fuseInit :: FuseOperations fh -> IO ()

-- | Called on filesystem exit to allow cleanup.
fuseDestroy :: FuseOperations fh -> IO ()

-- | Empty / default versions of the FUSE operations.
defaultFuseOps :: FuseOperations fh

-- | Main function of FUSE. This is all that has to be called from the
--   <tt>main</tt> function. On top of the <a>FuseOperations</a> record
--   with filesystem implementation, you must give an exception handler
--   converting Haskell exceptions to <a>Errno</a>.
--   
--   This function does the following:
--   
--   <ul>
--   <li>parses command line options (<tt>-d</tt>, <tt>-s</tt> and
--   <tt>-h</tt>) ;</li>
--   <li>passes all options after <tt>--</tt> to the fusermount program
--   ;</li>
--   <li>mounts the filesystem by calling <tt>fusermount</tt> ;</li>
--   <li>installs signal handlers for <a>keyboardSignal</a>,
--   <a>lostConnection</a>, <a>softwareTermination</a> and
--   <a>openEndedPipe</a> ;</li>
--   <li>registers an exit handler to unmount the filesystem on program
--   exit ;</li>
--   <li>registers the operations ;</li>
--   <li>calls FUSE event loop.</li>
--   </ul>
fuseMain :: Exception e => FuseOperations fh -> (e -> IO Errno) -> IO ()
fuseRun :: String -> [String] -> Exception e => FuseOperations fh -> (e -> IO Errno) -> IO ()

-- | Default exception handler. Print the exception on error output and
--   returns <a>eFAULT</a>.
defaultExceptionHandler :: SomeException -> IO Errno

-- | Used by <a>fuseGetFileStat</a>. Corresponds to <tt>struct stat</tt>
--   from <tt>stat.h</tt>; <tt>st_dev</tt>, <tt>st_ino</tt> and
--   <tt>st_blksize</tt> are omitted, since (from the libfuse
--   documentation): "the <tt>st_dev</tt> and <tt>st_blksize</tt> fields
--   are ignored. The <tt>st_ino</tt> field is ignored except if the
--   use_ino mount option is given."
--   
--   <i>TODO: at some point the inode field will probably be needed.</i>
data FileStat
FileStat :: EntryType -> FileMode -> LinkCount -> UserID -> GroupID -> DeviceID -> FileOffset -> Integer -> EpochTime -> EpochTime -> EpochTime -> FileStat
statEntryType :: FileStat -> EntryType
statFileMode :: FileStat -> FileMode
statLinkCount :: FileStat -> LinkCount
statFileOwner :: FileStat -> UserID
statFileGroup :: FileStat -> GroupID
statSpecialDeviceID :: FileStat -> DeviceID
statFileSize :: FileStat -> FileOffset
statBlocks :: FileStat -> Integer
statAccessTime :: FileStat -> EpochTime
statModificationTime :: FileStat -> EpochTime
statStatusChangeTime :: FileStat -> EpochTime

-- | The Unix type of a node in the filesystem.
data EntryType

-- | Unknown entry type
Unknown :: EntryType
NamedPipe :: EntryType
CharacterSpecial :: EntryType
Directory :: EntryType
BlockSpecial :: EntryType
RegularFile :: EntryType
SymbolicLink :: EntryType
Socket :: EntryType

-- | Type used by the <a>fuseGetFileSystemStats</a>.
data FileSystemStats
FileSystemStats :: Integer -> Integer -> Integer -> Integer -> Integer -> Integer -> Integer -> FileSystemStats

-- | Optimal transfer block size. FUSE default is 512.
fsStatBlockSize :: FileSystemStats -> Integer

-- | Total data blocks in file system.
fsStatBlockCount :: FileSystemStats -> Integer

-- | Free blocks in file system.
fsStatBlocksFree :: FileSystemStats -> Integer

-- | Free blocks available to non-superusers.
fsStatBlocksAvailable :: FileSystemStats -> Integer

-- | Total file nodes in file system.
fsStatFileCount :: FileSystemStats -> Integer

-- | Free file nodes in file system.
fsStatFilesFree :: FileSystemStats -> Integer

-- | Maximum length of filenames. FUSE default is 255.
fsStatMaxNameLength :: FileSystemStats -> Integer

-- | Used by <a>fuseSynchronizeFile</a> and
--   <a>fuseSynchronizeDirectory</a>.
data SyncType

-- | Synchronize all in-core parts of a file to disk: file content and
--   metadata.
FullSync :: SyncType

-- | Synchronize only the file content.
DataSync :: SyncType

-- | Returns the context of the program doing the current FUSE call.
getFuseContext :: IO FuseContext

-- | Returned by <a>getFuseContext</a>.
data FuseContext

-- | Converts an <a>EntryType</a> into the corresponding POSIX
--   <a>FileMode</a>.
entryTypeToFileMode :: EntryType -> FileMode
fileModeToEntryType :: FileMode -> EntryType
data OpenMode :: *
ReadOnly :: OpenMode
WriteOnly :: OpenMode
ReadWrite :: OpenMode

-- | Correspond to some of the int flags from C's fcntl.h.
data OpenFileFlags :: *
OpenFileFlags :: Bool -> Bool -> Bool -> Bool -> Bool -> OpenFileFlags

-- | O_APPEND
append :: OpenFileFlags -> Bool

-- | O_EXCL
exclusive :: OpenFileFlags -> Bool

-- | O_NOCTTY
noctty :: OpenFileFlags -> Bool

-- | O_NONBLOCK
nonBlock :: OpenFileFlags -> Bool

-- | O_TRUNC
trunc :: OpenFileFlags -> Bool

-- | Combines two file modes into one that only contains modes that appear
--   in both.
intersectFileModes :: FileMode -> FileMode -> FileMode

-- | Combines the two file modes into one that contains modes that appear
--   in either.
unionFileModes :: FileMode -> FileMode -> FileMode
instance Show EntryType
instance Show FileStat
instance Eq SyncType
instance Enum SyncType
