HFuse-0.2.1: HFuse is a binding for the Linux FUSE library.Source codeContentsIndex
System.Fuse
PortabilityGHC 6.4
Stabilityexperimental
Maintainerjeremy.bobbio@etu.upmc.fr
Contents
Using FUSE
Operations datatypes
FUSE Context
File modes
Description

A binding for the FUSE (Filesystem in USErspace) library (http://fuse.sourceforge.net/), which allows filesystems to be implemented as userspace processes.

The binding tries to follow as much as possible current Haskell POSIX interface in System.Posix.Files and System.Posix.Directory.

FUSE uses POSIX threads, so any Haskell application using this library must be linked against a threaded runtime system (eg. using the threaded GHC option).

Synopsis
module Foreign.C.Error
data FuseOperations fh = FuseOperations {
fuseGetFileStat :: FilePath -> IO (Either Errno FileStat)
fuseReadSymbolicLink :: FilePath -> IO (Either Errno FilePath)
fuseCreateDevice :: FilePath -> EntryType -> FileMode -> DeviceID -> IO Errno
fuseCreateDirectory :: FilePath -> FileMode -> IO Errno
fuseRemoveLink :: FilePath -> IO Errno
fuseRemoveDirectory :: FilePath -> IO Errno
fuseCreateSymbolicLink :: FilePath -> FilePath -> IO Errno
fuseRename :: FilePath -> FilePath -> IO Errno
fuseCreateLink :: FilePath -> FilePath -> IO Errno
fuseSetFileMode :: FilePath -> FileMode -> IO Errno
fuseSetOwnerAndGroup :: FilePath -> UserID -> GroupID -> IO Errno
fuseSetFileSize :: FilePath -> FileOffset -> IO Errno
fuseSetFileTimes :: FilePath -> EpochTime -> EpochTime -> IO Errno
fuseOpen :: FilePath -> OpenMode -> OpenFileFlags -> IO (Either Errno fh)
fuseRead :: FilePath -> fh -> ByteCount -> FileOffset -> IO (Either Errno ByteString)
fuseWrite :: FilePath -> fh -> ByteString -> FileOffset -> IO (Either Errno ByteCount)
fuseGetFileSystemStats :: String -> IO (Either Errno FileSystemStats)
fuseFlush :: FilePath -> fh -> IO Errno
fuseRelease :: FilePath -> fh -> IO ()
fuseSynchronizeFile :: FilePath -> SyncType -> IO Errno
fuseOpenDirectory :: FilePath -> IO Errno
fuseReadDirectory :: FilePath -> IO (Either Errno [(FilePath, FileStat)])
fuseReleaseDirectory :: FilePath -> IO Errno
fuseSynchronizeDirectory :: FilePath -> SyncType -> IO Errno
fuseAccess :: FilePath -> Int -> IO Errno
fuseInit :: IO ()
fuseDestroy :: IO ()
}
defaultFuseOps :: FuseOperations fh
fuseMain :: FuseOperations fh -> (Exception -> IO Errno) -> IO ()
defaultExceptionHandler :: Exception -> IO Errno
data FileStat = FileStat {
statEntryType :: EntryType
statFileMode :: FileMode
statLinkCount :: LinkCount
statFileOwner :: UserID
statFileGroup :: GroupID
statSpecialDeviceID :: DeviceID
statFileSize :: FileOffset
statBlocks :: Integer
statAccessTime :: EpochTime
statModificationTime :: EpochTime
statStatusChangeTime :: EpochTime
}
data EntryType
= Unknown
| NamedPipe
| CharacterSpecial
| Directory
| BlockSpecial
| RegularFile
| SymbolicLink
| Socket
data FileSystemStats = FileSystemStats {
fsStatBlockSize :: Integer
fsStatBlockCount :: Integer
fsStatBlocksFree :: Integer
fsStatBlocksAvailable :: Integer
fsStatFileCount :: Integer
fsStatFilesFree :: Integer
fsStatMaxNameLength :: Integer
}
data SyncType
= FullSync
| DataSync
getFuseContext :: IO FuseContext
data FuseContext
entryTypeToFileMode :: EntryType -> FileMode
data OpenMode
= ReadOnly
| WriteOnly
| ReadWrite
data OpenFileFlags = OpenFileFlags {
append :: Bool
exclusive :: Bool
noctty :: Bool
nonBlock :: Bool
trunc :: Bool
}
intersectFileModes :: FileMode -> FileMode -> FileMode
unionFileModes :: FileMode -> FileMode -> FileMode
Using FUSE

FuseOperations contains a field for each filesystem operations that can be called by FUSE. Think like if you were implementing a file system inside the Linux kernel.

Each actions must return a POSIX error code, also called Errno reflecting operation result. For actions not using Either, you should return eOK in case of success.

Read and writes are done with Haskell ByteString type.

module Foreign.C.Error
data FuseOperations fh Source

This record, given to fuseMain, binds each required file system operations.

Each field is named against System.Posix names. Matching Linux system calls are also given as a reference.

fh is the file handle type returned by fuseOpen and subsequently passed to all other file operations.

Constructors
FuseOperations
fuseGetFileStat :: FilePath -> IO (Either Errno FileStat)Implements System.Posix.Files.getSymbolicLinkStatus operation (POSIX lstat(2)).
fuseReadSymbolicLink :: FilePath -> IO (Either Errno FilePath)Implements System.Posix.Files.readSymbolicLink operation (POSIX readlink(2)). The returned FilePath might be truncated depending on caller buffer size.
fuseCreateDevice :: FilePath -> EntryType -> FileMode -> DeviceID -> IO ErrnoImplements System.Posix.Files.createDevice (POSIX mknod(2)). This function will also be called for regular file creation.
fuseCreateDirectory :: FilePath -> FileMode -> IO ErrnoImplements System.Posix.Directory.createDirectory (POSIX mkdir(2)).
fuseRemoveLink :: FilePath -> IO ErrnoImplements System.Posix.Files.removeLink (POSIX unlink(2)).
fuseRemoveDirectory :: FilePath -> IO ErrnoImplements System.Posix.Directory.removeDirectory (POSIX rmdir(2)).
fuseCreateSymbolicLink :: FilePath -> FilePath -> IO ErrnoImplements System.Posix.Files.createSymbolicLink (POSIX symlink(2)).
fuseRename :: FilePath -> FilePath -> IO ErrnoImplements System.Posix.Files.rename (POSIX rename(2)).
fuseCreateLink :: FilePath -> FilePath -> IO ErrnoImplements System.Posix.Files.createLink (POSIX link(2)).
fuseSetFileMode :: FilePath -> FileMode -> IO ErrnoImplements System.Posix.Files.setFileMode (POSIX chmod(2)).
fuseSetOwnerAndGroup :: FilePath -> UserID -> GroupID -> IO ErrnoImplements System.Posix.Files.setOwnerAndGroup (POSIX chown(2)).
fuseSetFileSize :: FilePath -> FileOffset -> IO ErrnoImplements System.Posix.Files.setFileSize (POSIX truncate(2)).
fuseSetFileTimes :: FilePath -> EpochTime -> EpochTime -> IO ErrnoImplements System.Posix.Files.setFileTimes (POSIX utime(2)).
fuseOpen :: FilePath -> OpenMode -> OpenFileFlags -> IO (Either Errno fh)

Implements System.Posix.Files.openFd (POSIX open(2)). On success, returns Right of a filehandle-like value that will be passed to future file operations; on failure, returns Left of the appropriate Errno.

No creation, exclusive access or truncating flags will be passed. This should check that the operation is permitted for the given flags.

fuseRead :: FilePath -> fh -> ByteCount -> FileOffset -> IO (Either Errno ByteString)Implements Unix98 pread(2). It differs from System.Posix.Files.fdRead by the explicit FileOffset argument. The fuse.h 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."
fuseWrite :: FilePath -> fh -> ByteString -> FileOffset -> IO (Either Errno ByteCount)Implements Unix98 pwrite(2). It differs from System.Posix.Files.fdWrite by the explicit FileOffset argument.
fuseGetFileSystemStats :: String -> IO (Either Errno FileSystemStats)Implements statfs(2).
fuseFlush :: FilePath -> fh -> IO ErrnoCalled when close(2) 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 open(2). The return value is passed on to the close(2) system call.
fuseRelease :: FilePath -> fh -> IO ()Called when an open file has all file descriptors closed and all memory mappings unmapped. For every open call there will be exactly one release 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.
fuseSynchronizeFile :: FilePath -> SyncType -> IO ErrnoImplements fsync(2).
fuseOpenDirectory :: FilePath -> IO ErrnoImplements opendir(3). This method should check if the open operation is permitted for this directory.
fuseReadDirectory :: FilePath -> IO (Either Errno [(FilePath, FileStat)])Implements readdir(3). The entire contents of the directory should be returned as a list of tuples (corresponding to the first mode of operation documented in fuse.h).
fuseReleaseDirectory :: FilePath -> IO ErrnoImplements closedir(3).
fuseSynchronizeDirectory :: FilePath -> SyncType -> IO ErrnoSynchronize the directory's contents; analogous to fuseSynchronizeFile.
fuseAccess :: FilePath -> Int -> IO ErrnoCheck file access permissions; this will be called for the access() system call. If the default_permissions mount option is given, this method is not called. This method is also not called under Linux kernel versions 2.4.x
fuseInit :: IO ()Initializes the filesystem. This is called before all other operations.
fuseDestroy :: IO ()Called on filesystem exit to allow cleanup.
defaultFuseOps :: FuseOperations fhSource
Empty / default versions of the FUSE operations.
fuseMain :: FuseOperations fh -> (Exception -> IO Errno) -> IO ()Source

Main function of FUSE. This is all that has to be called from the main function. On top of the FuseOperations record with filesystem implementation, you must give an exception handler converting Haskell exceptions to Errno.

This function does the following:

  • parses command line options (-d, -s and -h) ;
  • passes all options after -- to the fusermount program ;
  • mounts the filesystem by calling fusermount ;
  • installs signal handlers for System.Posix.Signals.keyboardSignal, System.Posix.Signals.lostConnection, System.Posix.Signals.softwareTermination and System.Posix.Signals.openEndedPipe ;
  • registers an exit handler to unmount the filesystem on program exit ;
  • registers the operations ;
  • calls FUSE event loop.
defaultExceptionHandler :: Exception -> IO ErrnoSource
Default exception handler. Print the exception on error output and returns eFAULT.
Operations datatypes
data FileStat Source

Used by fuseGetFileStat. Corresponds to struct stat from stat.h; st_dev, st_ino and st_blksize are omitted, since (from the libfuse documentation): "the st_dev and st_blksize fields are ignored. The st_ino field is ignored except if the use_ino mount option is given."

TODO: at some point the inode field will probably be needed.

Constructors
FileStat
statEntryType :: EntryType
statFileMode :: FileMode
statLinkCount :: LinkCount
statFileOwner :: UserID
statFileGroup :: GroupID
statSpecialDeviceID :: DeviceID
statFileSize :: FileOffset
statBlocks :: Integer
statAccessTime :: EpochTime
statModificationTime :: EpochTime
statStatusChangeTime :: EpochTime
show/hide Instances
data EntryType Source
The Unix type of a node in the filesystem.
Constructors
UnknownUnknown entry type
NamedPipe
CharacterSpecial
Directory
BlockSpecial
RegularFile
SymbolicLink
Socket
show/hide Instances
data FileSystemStats Source
Type used by the fuseGetFileSystemStats.
Constructors
FileSystemStats
fsStatBlockSize :: IntegerOptimal transfer block size. FUSE default is 512.
fsStatBlockCount :: IntegerTotal data blocks in file system.
fsStatBlocksFree :: IntegerFree blocks in file system.
fsStatBlocksAvailable :: IntegerFree blocks available to non-superusers.
fsStatFileCount :: IntegerTotal file nodes in file system.
fsStatFilesFree :: IntegerFree file nodes in file system.
fsStatMaxNameLength :: IntegerMaximum length of filenames. FUSE default is 255.
data SyncType Source
Used by fuseSynchronizeFile and fuseSynchronizeDirectory.
Constructors
FullSyncSynchronize all in-core parts of a file to disk: file content and metadata.
DataSyncSynchronize only the file content.
show/hide Instances
FUSE Context
getFuseContext :: IO FuseContextSource
Returns the context of the program doing the current FUSE call.
data FuseContext Source
Returned by getFuseContext.
File modes
entryTypeToFileMode :: EntryType -> FileModeSource
Converts an EntryType into the corresponding POSIX FileMode.
data OpenMode Source
Constructors
ReadOnly
WriteOnly
ReadWrite
data OpenFileFlags Source
Correspond to some of the int flags from C's fcntl.h.
Constructors
OpenFileFlags
append :: BoolO_APPEND
exclusive :: BoolO_EXCL
noctty :: BoolO_NOCTTY
nonBlock :: BoolO_NONBLOCK
trunc :: BoolO_TRUNC
intersectFileModes :: FileMode -> FileMode -> FileModeSource
Combines two file modes into one that only contains modes that appear in both.
unionFileModes :: FileMode -> FileMode -> FileModeSource
Combines the two file modes into one that contains modes that appear in either.
Produced by Haddock version 2.6.0