HFuse-0.2.4: HFuse is a binding for the Linux FUSE library.

PortabilityGHC 6.4-6.12
Maintainertaruti@taruti.net, jeremy.bobbio@etu.upmc.fr




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).


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.

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.




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 Errno

Implements System.Posix.Files.createDevice (POSIX mknod(2)). This function will also be called for regular file creation.

fuseCreateDirectory :: FilePath -> FileMode -> IO Errno

Implements System.Posix.Directory.createDirectory (POSIX mkdir(2)).

fuseRemoveLink :: FilePath -> IO Errno

Implements System.Posix.Files.removeLink (POSIX unlink(2)).

fuseRemoveDirectory :: FilePath -> IO Errno

Implements System.Posix.Directory.removeDirectory (POSIX rmdir(2)).

fuseCreateSymbolicLink :: FilePath -> FilePath -> IO Errno

Implements System.Posix.Files.createSymbolicLink (POSIX symlink(2)).

fuseRename :: FilePath -> FilePath -> IO Errno

Implements System.Posix.Files.rename (POSIX rename(2)).

fuseCreateLink :: FilePath -> FilePath -> IO Errno

Implements System.Posix.Files.createLink (POSIX link(2)).

fuseSetFileMode :: FilePath -> FileMode -> IO Errno

Implements System.Posix.Files.setFileMode (POSIX chmod(2)).

fuseSetOwnerAndGroup :: FilePath -> UserID -> GroupID -> IO Errno

Implements System.Posix.Files.setOwnerAndGroup (POSIX chown(2)).

fuseSetFileSize :: FilePath -> FileOffset -> IO Errno

Implements System.Posix.Files.setFileSize (POSIX truncate(2)).

fuseSetFileTimes :: FilePath -> EpochTime -> EpochTime -> IO Errno

Implements 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 Errno

Called 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 Errno

Implements fsync(2).

fuseOpenDirectory :: FilePath -> IO Errno

Implements 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 Errno

Implements closedir(3).

fuseSynchronizeDirectory :: FilePath -> SyncType -> IO Errno

Synchronize the directory's contents; analogous to fuseSynchronizeFile.

fuseAccess :: FilePath -> Int -> IO Errno

Check 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 :: Exception e => FuseOperations fh -> (e -> 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.

fuseRun :: String -> [String] -> Exception e => FuseOperations fh -> (e -> IO Errno) -> IO ()Source

defaultExceptionHandler :: SomeException -> 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.


data EntryType Source

The Unix type of a node in the filesystem.


data FileSystemStats Source

Type used by the fuseGetFileSystemStats.




fsStatBlockSize :: Integer

Optimal transfer block size. FUSE default is 512.

fsStatBlockCount :: Integer

Total data blocks in file system.

fsStatBlocksFree :: Integer

Free blocks in file system.

fsStatBlocksAvailable :: Integer

Free blocks available to non-superusers.

fsStatFileCount :: Integer

Total file nodes in file system.

fsStatFilesFree :: Integer

Free file nodes in file system.

fsStatMaxNameLength :: Integer

Maximum length of filenames. FUSE default is 255.

data SyncType Source



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


Synchronize only the file content.


FUSE Context

getFuseContext :: IO FuseContextSource

Returns the context of the program doing the current FUSE call.

File modes

entryTypeToFileMode :: EntryType -> FileModeSource

Converts an EntryType into the corresponding POSIX FileMode.

data OpenMode



data OpenFileFlags

Correspond to some of the int flags from C's fcntl.h.




append :: Bool


exclusive :: Bool


noctty :: Bool


nonBlock :: Bool


trunc :: Bool


intersectFileModes :: FileMode -> FileMode -> FileMode

Combines two file modes into one that only contains modes that appear in both.

unionFileModes :: FileMode -> FileMode -> FileMode

Combines the two file modes into one that contains modes that appear in either.