System.LibFuse3

A Haskell binding to libfuse-3.x.

Documentation

data FuseOperations fh dh

The file system operations.

All operations are optional. Each field is named against struct fuse_operations in fuse.h.

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

dh is the directory handle type returned by fuseOpendir, and subsequently passed to fuseReaddir and fuseReleasedir.

Constructors

FuseOperations

Fields

• fuseGetattr :: Maybe (FilePath -> Maybe fh -> IO (Either Errno FileStat))

  Implements getSymbolicLinkStatus operation (POSIX lstat(2)).

  fh will always be Nothing if the file is not currently open, but may also be Nothing even if it is open.

• fuseReadlink :: Maybe (FilePath -> IO (Either Errno FilePath))

  Implements readSymbolicLink operation (POSIX readlink(2)).

  This function should not append a terminating NUL byte. The returned FilePath might be truncated depending on caller buffer size.

• fuseMknod :: Maybe (FilePath -> FileMode -> DeviceID -> IO Errno)

  Implements createDevice (POSIX mknod(2)).

  This function will also be called for regular file creation if fuseCreate is not defined.

  fileModeToEntryType is handy to pattern match on the request type of the node.

• fuseMkdir :: Maybe (FilePath -> FileMode -> IO Errno)

  Implements createDirectory (POSIX mkdir(2)).

• fuseUnlink :: Maybe (FilePath -> IO Errno)

  Implements removeLink (POSIX unlink(2)).

• fuseRmdir :: Maybe (FilePath -> IO Errno)

  Implements removeDirectory (POSIX rmdir(2)).

• fuseSymlink :: Maybe (FilePath -> FilePath -> IO Errno)

  Implements createSymbolicLink (POSIX symlink(2)).

• fuseRename :: Maybe (FilePath -> FilePath -> IO Errno)

  Implements rename (POSIX rename(2)).

• fuseLink :: Maybe (FilePath -> FilePath -> IO Errno)

  Implements createLink (POSIX link(2)).

• fuseChmod :: Maybe (FilePath -> Maybe fh -> FileMode -> IO Errno)

  Implements setFileMode (POSIX chmod(2)).

  fh will always be Nothing if the file is not currently open, but may also be Nothing even if it is open.

• fuseChown :: Maybe (FilePath -> Maybe fh -> UserID -> GroupID -> IO Errno)

  Implements setOwnerAndGroup (POSIX chown(2)).

  fh will always be Nothing if the file is not currently open, but may also be Nothing even if it is open.

  Unless FUSE_CAP_HANDLE_KILLPRIV is disabled, this method is expected to reset the setuid and setgid bits.

• fuseTruncate :: Maybe (FilePath -> Maybe fh -> FileOffset -> IO Errno)

  Implements setFileSize (POSIX truncate(2)).

  fh will always be Nothing if the file is not currently open, but may also be Nothing even if it is open.

  Unless FUSE_CAP_HANDLE_KILLPRIV is disabled, this method is expected to reset the setuid and setgid bits.

• fuseOpen :: Maybe (FilePath -> OpenMode -> OpenFileFlags -> IO (Either Errno fh))

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

  • Creation flags will be filtered out / handled by the kernel.
  • Access modes should be used by this to check if the operation is permitted.
  • The filesystem is expected to properly handle the O_APPEND flag and ensure that each write is appending to the end of the file.
  • If this method returns Left eNOSYS and FUSE_CAP_NO_OPEN_SUPPORT is set in fuse_conn_info.capable, this is treated as success and future calls to open will also succeed without being sent to the filesystem process.

  TODO allow this method to set fuse_file_info.direct_io and fuse_file_info.keep_cache

• fuseRead :: Maybe (FilePath -> fh -> ByteCount -> FileOffset -> IO (Either Errno ByteString))

  Implements Unix98 pread(2).

  It differs from fdRead by the explicit FileOffset argument.

• fuseWrite :: Maybe (FilePath -> fh -> ByteString -> FileOffset -> IO (Either Errno CInt))

  Implements Unix98 pwrite(2).

  It differs from fdWrite by the explicit FileOffset argument.

  Unless FUSE_CAP_HANDLE_KILLPRIV is disabled, this method is expected to reset the setuid and setgid bits.

• fuseStatfs :: Maybe (String -> IO (Either Errno FileSystemStats))

  Implements statfs(2).

• fuseFlush :: Maybe (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 :: Maybe (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.

• fuseFsync :: Maybe (FilePath -> fh -> SyncType -> IO Errno)

  Implements fsync(2).

• fuseSetxattr :: Maybe (FilePath -> String -> ByteString -> SetxattrFlag -> IO Errno)

  Implements setxattr(2).

  The parameters are: path, name, value and flags.

• fuseGetxattr :: Maybe (FilePath -> String -> IO (Either Errno ByteString))

  Implements getxattr(2).

  The parameters are path and name.

• fuseListxattr :: Maybe (FilePath -> IO (Either Errno [String]))

  Implements listxattr(2).

• fuseRemovexattr :: Maybe (FilePath -> String -> IO Errno)

  Implements removexattr(2).

• fuseOpendir :: Maybe (FilePath -> IO (Either Errno dh))

  Implements opendir(3).

  This method should check if the open operation is permitted for this directory.

• fuseReaddir :: Maybe (FilePath -> dh -> IO (Either Errno [(String, Maybe 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).

  The returned list should contain entries of "." and "..".

  Each element of the list is a pair of the name and the stat. The name should not include the path to it. The implementation may return Nothing as the stat; in this case fuseGetattr is called instead.

• fuseReleasedir :: Maybe (FilePath -> dh -> IO Errno)

  Implements closedir(3).

• fuseFsyncdir :: Maybe (FilePath -> dh -> SyncType -> IO Errno)

  Synchronize the directory's contents; analogous to fuseFsync.

• fuseInit :: Maybe (FuseConfig -> IO FuseConfig)

  Initializes the filesystem. This is called before all other operations.

  The filesystem may modify FuseConfig to configure the API.

• fuseDestroy :: Maybe (IO ())

  Called on filesystem exit to allow cleanup.

• fuseAccess :: Maybe (FilePath -> AccessMode -> IO Errno)

  Implements fileAccess and 'System.Posix.Files.fileExist (POSIX access(2)).

  Checks file access permissions as requested by an AccessMode.

  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

  TODO add notes about default_permissions to other relevant handlers

• fuseCreate :: Maybe (FilePath -> OpenMode -> FileMode -> OpenFileFlags -> IO (Either Errno fh))

  Implements openFd (POSIX open(2)). Creates and opens a regular file.

  If this is not implemented, fuseMknod and fuseOpen methods will be called instead.

  See fuseOpen for notes on the flags.

• fuseUtimens :: Maybe (FilePath -> Maybe fh -> TimeSpec -> TimeSpec -> IO Errno)

  Implements utimensat(2).

  Changes the access and modification times of a file with nanosecond resolution.

  fh will always be Nothing if the file is not currently open, but may also be Nothing even if it is open.

• fuseFallocate :: Maybe (FilePath -> fh -> CInt -> FileOffset -> FileOffset -> IO Errno)

  Implements fileAllocate (posix_fallocate(3)). Allocates space for an open file.

• fuseCopyFileRange :: Maybe (FilePath -> fh -> FileOffset -> FilePath -> fh -> FileOffset -> ByteCount -> CInt -> IO (Either Errno CSsize))

  Implements copy_file_range(2).

• fuseLseek :: Maybe (FilePath -> fh -> FileOffset -> SeekMode -> IO (Either Errno FileOffset))

  Implements fdSeek lseek(3).

  Note: This is silently ignored if libfuse doesn't support lseek operation (requires libfuse-3.8.0).

defaultFuseOperations :: FuseOperations fh dh

An empty set of operations whose fields are Nothing.

data FuseConfig

Configures the filesystem. Passed to fuseInit.

See the module System.LibFuse3.FuseConfig for its fields.

Instances

Eq FuseConfig

Defined in System.LibFuse3.FuseConfig

Methods

(==) :: FuseConfig -> FuseConfig -> Bool

(/=) :: FuseConfig -> FuseConfig -> Bool

Show FuseConfig

Defined in System.LibFuse3.FuseConfig

Methods

showsPrec :: Int -> FuseConfig -> ShowS

show :: FuseConfig -> String

showList :: [FuseConfig] -> ShowS

data AccessMode

The query type of access. Passed to fuseAccess.

Constructors

FileOK

File existence (F_OK)

PermOK Bool Bool Bool

Reading, writing and executing permissions (R_OK, W_OK and X_OK, resp.)

Instances

Eq AccessMode

Defined in System.LibFuse3.Internal

Methods

(==) :: AccessMode -> AccessMode -> Bool

(/=) :: AccessMode -> AccessMode -> Bool

Show AccessMode

Defined in System.LibFuse3.Internal

Methods

showsPrec :: Int -> AccessMode -> ShowS

show :: AccessMode -> String

showList :: [AccessMode] -> ShowS

access :: FilePath -> AccessMode -> IO ()

Tests if access permissions to the file is granted or the file exists.

Calls access. Compared to fileAccess and fileExist, this function doesn't translate the errno and just returns () to indicate success, or throws an error to indicate failure.

accessErrno :: FilePath -> AccessMode -> IO Errno

Same as access but returns the Errno instead of throwing an exception.

Returns eOK on success.

data EntryType

The Unix type of a node in the filesystem.

Constructors

Unknown

Unknown entry type

NamedPipe

CharacterSpecial

Directory

BlockSpecial

RegularFile

SymbolicLink

Socket

Instances

Eq EntryType

Defined in System.LibFuse3.Internal

Methods

(==) :: EntryType -> EntryType -> Bool

(/=) :: EntryType -> EntryType -> Bool

Show EntryType

Defined in System.LibFuse3.Internal

Methods

showsPrec :: Int -> EntryType -> ShowS

show :: EntryType -> String

showList :: [EntryType] -> ShowS

entryTypeToFileMode :: EntryType -> FileMode

Converts an EntryType into the corresponding POSIX FileMode.

fileModeToEntryType :: FileMode -> EntryType

Decodes EntryType from a FileMode.

data SyncType

Passed to fuseFsync and fuseFsyncdir.

Constructors

FullSync

Synchronize both file content and metadata.

DataSync

Synchronize only the file content.

Instances

Eq SyncType

Defined in System.LibFuse3.Internal

Methods

(==) :: SyncType -> SyncType -> Bool

(/=) :: SyncType -> SyncType -> Bool

Show SyncType

Defined in System.LibFuse3.Internal

Methods

showsPrec :: Int -> SyncType -> ShowS

show :: SyncType -> String

showList :: [SyncType] -> ShowS

data FileStat

A file status a.k.a. metadata.

The differences from FileStatus are:

• Is a record type with a Storable instance.
• Has an extra field blockCount.

• Provides an exact representation (TimeSpec) of the time fields without converting to POSIXTime.

  • This assumes that the struct stat has st_atim, st_mtim and st_ctim fields. On Linux this requires Linux >= 2.6.

Ptr FileStat can be cast to Ptr CStat and vice versa.

Use defaultFileStat and modify its fields you are interested in.

The st_ino field is ignored unless the use_ino mount option is given.

The st_dev and st_blksize fields are ignored by libfuse, so not provided.

Constructors

FileStat

Fields

• fileID :: FileID

  Inode number. st_ino

• fileMode :: FileMode

  File type and mode. st_mode

• linkCount :: LinkCount

  Number of hard links. st_nlink

• fileOwner :: UserID

  User ID of owner. st_uid

• fileGroup :: GroupID

  Group ID of owner. st_gid

• specialDeviceID :: DeviceID

  Device ID (if special file). st_rdev

• fileSize :: FileOffset

  Total size, in bytes. st_size

• blockCount :: CBlkSize

  Number of 512B blocks allocated. st_blocks

• accessTimeHiRes :: TimeSpec

  Time of last access. st_atim

• modificationTimeHiRes :: TimeSpec

  Time of last modification. st_mtim

• statusChangeTimeHiRes :: TimeSpec

  Time of last status change. st_ctim

Instances

Eq FileStat

Defined in System.LibFuse3.FileStat

Methods

(==) :: FileStat -> FileStat -> Bool

(/=) :: FileStat -> FileStat -> Bool

Show FileStat

Defined in System.LibFuse3.FileStat

Methods

showsPrec :: Int -> FileStat -> ShowS

show :: FileStat -> String

showList :: [FileStat] -> ShowS

Storable FileStat

Targets struct stat.

Defined in System.LibFuse3.FileStat

Methods

sizeOf :: FileStat -> Int

alignment :: FileStat -> Int

peekElemOff :: Ptr FileStat -> Int -> IO FileStat

pokeElemOff :: Ptr FileStat -> Int -> FileStat -> IO ()

peekByteOff :: Ptr b -> Int -> IO FileStat

pokeByteOff :: Ptr b -> Int -> FileStat -> IO ()

peek :: Ptr FileStat -> IO FileStat

poke :: Ptr FileStat -> FileStat -> IO ()

defaultFileStat :: FileStat

The default value of FileStat.

The Haskell Equivalent of zero-setting C code { struct stat st; memset(&st, 0, sizeof(struct stat)); }.

getFileStat :: FilePath -> IO FileStat

Reads a file status of a given file.

Calls lstat.

getFileStatFd :: Fd -> IO FileStat

Reads a file status of a given file.

Calls fstat.

data FileSystemStats

Passed to fuseStatfs.

The Storable instance targets C struct statvfs.

f_favail, f_fsid and f_flag fields are ignored by libfuse, and their corresponding fields are not defined.

Instances

Eq FileSystemStats

Defined in System.LibFuse3.FileSystemStats

Methods

(==) :: FileSystemStats -> FileSystemStats -> Bool

(/=) :: FileSystemStats -> FileSystemStats -> Bool

Show FileSystemStats

Defined in System.LibFuse3.FileSystemStats

Methods

showsPrec :: Int -> FileSystemStats -> ShowS

show :: FileSystemStats -> String

showList :: [FileSystemStats] -> ShowS

Storable FileSystemStats

Defined in System.LibFuse3.FileSystemStats

Methods

sizeOf :: FileSystemStats -> Int

alignment :: FileSystemStats -> Int

peekElemOff :: Ptr FileSystemStats -> Int -> IO FileSystemStats

pokeElemOff :: Ptr FileSystemStats -> Int -> FileSystemStats -> IO ()

peekByteOff :: Ptr b -> Int -> IO FileSystemStats

pokeByteOff :: Ptr b -> Int -> FileSystemStats -> IO ()

peek :: Ptr FileSystemStats -> IO FileSystemStats

poke :: Ptr FileSystemStats -> FileSystemStats -> IO ()

getFileSystemStats

Arguments

:: FilePath

A path of any file within the filesystem

-> IO FileSystemStats

Gets filesystem statistics.

Calls statvfs.

getFileSystemStatsFd :: Fd -> IO FileSystemStats

Gets filesystem statistics.

Calls fstatvfs.

data SetxattrFlag

Passed to fuseSetxattr.

Constructors

SetxattrDefault

Create a new attribute if it does not exist, or replace the value if it already exists (0)

SetxattrCreate

Perform a pure create, which fails if the named attribute exists already (XATTR_CREATE)

SetxattrReplace

Perform a pure replace operation, which fails if the named attribute does not already exist (XATTR_REPLACE)

Instances

Eq SetxattrFlag

Defined in System.LibFuse3.Internal

Methods

(==) :: SetxattrFlag -> SetxattrFlag -> Bool

(/=) :: SetxattrFlag -> SetxattrFlag -> Bool

Show SetxattrFlag

Defined in System.LibFuse3.Internal

Methods

showsPrec :: Int -> SetxattrFlag -> ShowS

show :: SetxattrFlag -> String

showList :: [SetxattrFlag] -> ShowS

module System.LibFuse3.Utils

fuseMain :: Exception e => FuseOperations fh dh -> (e -> IO Errno) -> IO ()

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
• passes all options after -- to the fusermount program
• mounts the filesystem by calling fusermount
• installs signal handlers
• registers an exit handler to unmount the filesystem on program exit
• registers the operations
• calls FUSE event loop