System.Linux.Btrfs.ByteString

Deprecated: This module is deprecated and will be removed in a future version of this library. Please leave a comment on https://github.com/redneb/hs-btrfs/issues/5 if you think that is should not be removed.

Most functions in this module come in two flavors: one that operates on file descriptors and another one that operates on file paths. The former can be distinguished by the Fd suffix in their names.

Basic types

type FileSize = Word64

type ObjectType = Word8

type ObjectId = Word64

type InodeNum = ObjectId

type SubvolId = ObjectId

data CompressionType

Instances

Eq CompressionType

Defined in System.Linux.Btrfs.ByteString

Methods

(==) :: CompressionType -> CompressionType -> Bool

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

Show CompressionType

Defined in System.Linux.Btrfs.ByteString

Methods

showsPrec :: Int -> CompressionType -> ShowS

show :: CompressionType -> String

showList :: [CompressionType] -> ShowS

compressNone :: CompressionType

compressZlib :: CompressionType

compressLZO :: CompressionType

compressZstd :: CompressionType

File cloning/deduplication

cloneFd :: Fd -> Fd -> IO ()

clone

Arguments

:: RawFilePath

The source file.

-> RawFilePath

The destination file.

-> IO ()

Clone an entire file to an existing file.

Note: calls the BTRFS_IOC_CLONE/FICLONE ioctl.

cloneNew :: RawFilePath -> RawFilePath -> IO ()

Like clone except that it will create or truncate the destination file if necessary. This is similar to cp --reflink=always.

Note: calls the BTRFS_IOC_CLONE/FICLONE ioctl.

cloneRangeFd :: Fd -> FileSize -> FileSize -> Fd -> FileSize -> IO ()

cloneRange

Arguments

:: RawFilePath

The source file.

-> FileSize

The offset within the source file.

-> FileSize

The length of the range. A length of 0 selects the range from the source offset to the end.

-> RawFilePath

The destination file.

-> FileSize

The offset within the destination file.

-> IO ()

Clones a range of bytes from a file to another file. All ranges must be block-aligned (the block size can be obtained using getFSInfo and fsiCloneAlignment).

Note: calls the BTRFS_IOC_CLONE_RANGE/FICLONERANGE ioctl.

data CloneResult

The result of a cloneRangeIfSame operation.

Constructors

CRError IOError

Cloning failed because of an error.

CRDataDiffers

No cloning was performed because the contents of the source and the destination file differ.

CRSuccess FileSize

Cloning succeeded, the returned integer indicates the number of bytes that were deduped.

Instances

Eq CloneResult

Defined in System.Linux.Btrfs.ByteString

Methods

(==) :: CloneResult -> CloneResult -> Bool

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

Show CloneResult

Defined in System.Linux.Btrfs.ByteString

Methods

showsPrec :: Int -> CloneResult -> ShowS

show :: CloneResult -> String

showList :: [CloneResult] -> ShowS

cloneRangeIfSameFd :: Fd -> FileSize -> FileSize -> [(Fd, FileSize)] -> IO [CloneResult]

cloneRangeIfSame

Arguments

:: RawFilePath

The source file.

-> FileSize

The offset within the source file.

-> FileSize

The length of the range.

-> [(RawFilePath, FileSize)]

The destination files and corresponding offsets.

-> IO [CloneResult]

Similar to cloneRange except that it performs the cloning only if the data ranges contain identical data. Additionally, it accepts multiple destination files. The same thing can be accomplished with cloneRange in conjunction with file locking but this function uses in-kernel locking to guarantee that the deduplicated data is identical at the time of the operation. On the other hand, this function will not clone arbitrarily large ranges; the kernel has an upper limit for the length and if cloning bigger ranges is desired then it has to be called multiple times. Note that cloning may succeed for some of the destination files and fail for others. Because of that, this function returns a list of outcomes, one for each destination file, and no exceptions will be raised for the failed files.

Note: calls the BTRFS_IOC_FILE_EXTENT_SAME/FIDEDUPERANGE ioctl.

Requires Linux 3.12 or later.

Subvolumes and snapshots

createSubvol :: RawFilePath -> IO ()

Create an (initially) empty new subvolume.

Note: calls the BTRFS_IOC_SUBVOL_CREATE ioctl.

destroySubvol :: RawFilePath -> IO ()

Destroy (delete) a subvolume. The directory that corresponds to the subvolume is removed asynchronously. As a result, the subvolume may appear again after a crash. If this is not acceptable, call startSync followed by a waitSync, after the destroySubvol call.

Note: calls the BTRFS_IOC_SNAP_DESTROY ioctl.

snapshotFd :: Fd -> RawFilePath -> Bool -> IO ()

snapshot

Arguments

:: RawFilePath

The source subvolume.

-> RawFilePath

The destination subvolume (must not exist).

-> Bool

Create a read-only snapshot?

-> IO ()

Create a snapshot of an existing subvolume.

Note: calls the BTRFS_IOC_SNAP_CREATE_V2 ioctl.

getSubvolReadOnlyFd :: Fd -> IO Bool

getSubvolReadOnly :: RawFilePath -> IO Bool

Is the subvolume read-only?

Note: calls the BTRFS_IOC_SUBVOL_GETFLAGS ioctl.

setSubvolReadOnlyFd :: Fd -> Bool -> IO ()

setSubvolReadOnly :: RawFilePath -> Bool -> IO ()

Make a subvolume read-only (or read-write).

Note: calls the BTRFS_IOC_SUBVOL_GETFLAGS and BTRFS_IOC_SUBVOL_SETFLAGS ioctls.

getSubvolFd :: Fd -> IO SubvolId

getSubvol :: RawFilePath -> IO SubvolId

Find the id of the subvolume where the given file resides. This is merely a wrapper around lookupInode provided for convenience.

lookupSubvolFd :: Fd -> SubvolId -> IO (SubvolId, InodeNum, RawFilePath)

lookupSubvol

Arguments

:: RawFilePath

The mount point of the volume (or any file in that volume).

-> SubvolId

The id of the subvolume.

-> IO (SubvolId, InodeNum, RawFilePath)

Given the id of a subvolume, find the id of the parent subvolume, the inode number of the directory containing it, and its name. This is a wrapper around treeSearch.

resolveSubvolFd :: Fd -> SubvolId -> IO RawFilePath

resolveSubvol

Arguments

:: RawFilePath

The mount point of the volume (or any file in that volume).

-> SubvolId

The id of the subvolume.

-> IO RawFilePath

Given the id of a subvolume, find its path relative to the root of the volume. This function calls lookupSubvol recursively.

rootSubvol :: SubvolId

The id the root subvolume.

listSubvolsFd :: Fd -> IO [(SubvolId, SubvolId, InodeNum, RawFilePath)]

listSubvols :: RawFilePath -> IO [(SubvolId, SubvolId, InodeNum, RawFilePath)]

Find all subvolumes of the given volume. For each subvolume found, it returns: its id, the id of its parent subvolume, the inode number of the directory containing it, and its name. This is a wrapper around treeSearch.

listSubvolPathsFd :: Fd -> IO [(SubvolId, SubvolId, RawFilePath)]

listSubvolPaths :: RawFilePath -> IO [(SubvolId, SubvolId, RawFilePath)]

Find all subvolumes of the given volume. For each subvolume found, it returns: its id, the id of its parent subvolume, and its path relative to the root of the volume. This is a wrapper around treeSearch and resolveSubvol.

childSubvolsFd :: Fd -> SubvolId -> IO [(SubvolId, InodeNum, RawFilePath)]

childSubvols

Arguments

:: RawFilePath

The mount point of the volume (or any file in that volume).

-> SubvolId

The id of the subvolume.

-> IO [(SubvolId, InodeNum, RawFilePath)]

Find all child subvolumes of the given subvolume. For each child, returns its id, the inode number of the directory containing it, and its name. This is a wrapper around treeSearch.

childSubvolPathsFd :: Fd -> SubvolId -> IO [(SubvolId, RawFilePath)]

childSubvolPaths

Arguments

:: RawFilePath

The mount point of the volume (or any file in that volume).

-> SubvolId

The id of the subvolume.

-> IO [(SubvolId, RawFilePath)]

Find all child subvolumes of the given subvolume. For each child, returns its id and its path relative to the root of the parent. This is a wrapper around treeSearch and lookupInode.

data SubvolInfo

Information about a subvolume.

Constructors

SubvolInfo

Fields

• siGeneration :: Word64

  The generation when the subvolume was last modified.

• siLastSnapshot :: Maybe Word64

  The generation when the most recent snapshot of this subvolume was taken.

• siParSnapGen :: Maybe Word64

  The generation of the snapshot parent at the time when the snapshot was taken. Defined if only if this is a snapshot.

• siReadOnly :: Bool

  Is this a read-only subvolume?

• siUuid :: Maybe UUID

  The UUID of the subvolume.

• siPUuid :: Maybe UUID

  The UUID of the snapshot parent.

• siReceivedUuid :: Maybe UUID

  The UUID of the source subvolume that this subvolume was received from. This is always defined for received subvolumes.

• siCTransId :: Maybe Word64

  The generation when an inode was last modified.

• siOTransId :: Maybe Word64

  The generation when the subvolume was created.

• siSTransId :: Maybe Word64

  The generation of the source subvolume that this subvolume was received from. This is always defined for received subvolumes.

• siRTransId :: Maybe Word64

  The generation when the subvolume was received. This is always defined for received subvolumes.

• siCTime :: Maybe UTCTime

  The time when an inode was last modified.

• siOTime :: Maybe UTCTime

  The time when the subvolume was created.

• siSTime :: Maybe UTCTime

  The timestamp that corresponds to siSTransId.

• siRTime :: Maybe UTCTime

  The time when the subvolume was received. This is always defined for received subvolumes.

Instances

Eq SubvolInfo

Defined in System.Linux.Btrfs.ByteString

Methods

(==) :: SubvolInfo -> SubvolInfo -> Bool

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

Show SubvolInfo

Defined in System.Linux.Btrfs.ByteString

Methods

showsPrec :: Int -> SubvolInfo -> ShowS

show :: SubvolInfo -> String

showList :: [SubvolInfo] -> ShowS

getSubvolInfoFd :: Fd -> SubvolId -> IO SubvolInfo

getSubvolInfo

Arguments

:: RawFilePath

The mount point of the volume (or any file in that volume).

-> SubvolId

The id of the subvolume.

-> IO SubvolInfo

Retrieve information about a subvolume. This is a wrapper around treeSearch.

getSubvolByUuidFd :: Fd -> UUID -> IO SubvolId

getSubvolByUuid

Arguments

:: RawFilePath

The mount point of the volume (or any file in that volume).

-> UUID

The UUID of the subvolume.

-> IO SubvolId

Find the id of a subvolume, given its UUID. This is a wrapper around treeSearch.

Requires Linux 3.12 or later.

getSubvolByReceivedUuidFd :: Fd -> UUID -> IO SubvolId

getSubvolByReceivedUuid

Arguments

:: RawFilePath

The mount point of the volume (or any file in that volume).

-> UUID

The siReceivedUuid of the subvolume.

-> IO SubvolId

Find the id of a subvolume, given its siReceivedUuid. This is a wrapper around treeSearch.

Requires Linux 3.12 or later.

getDefaultSubvolFd :: Fd -> IO SubvolId

getDefaultSubvol

Arguments

:: RawFilePath

The mount point of the volume (or any file in that volume).

-> IO SubvolId

Find the id of the default subvolume. This is a wrapper around treeSearch.

setDefaultSubvolFd :: Fd -> ObjectId -> IO ()

setDefaultSubvol

Arguments

:: RawFilePath

The mount point of the volume (or any file in that volume).

-> SubvolId

The id of the new default subvolume.

-> IO ()

Set the default subvolume.

Note: calls the BTRFS_IOC_DEFAULT_SUBVOL ioctl.

Defrag

There is a limitation in the kernel whereby a defrag operation will be silently aborted when the calling process receives any signal. This does not play well with GHC's rts which in some cases uses signals as a way to preempt haskell threads. So in order to use defrag or defragRange, you must compile your program with GHC >=8.2 and the use the threaded runtime which does not use signals anymore. Alternatively, for older versions of GHC, you can use something like the withRTSSignalsBlocked function from here.

defragFd :: Fd -> IO ()

defrag :: RawFilePath -> IO ()

Defrag a single file.

Note: calls the BTRFS_IOC_DEFRAG ioctl.

data DefragRangeArgs

Argument to the defragRange operation.

Constructors

DefragRangeArgs

Fields

• draStart :: FileSize

  Beginning of the defrag range.

• draLength :: FileSize

  Number of bytes to defrag, use maxBound to say all.

• draExtentThreshold :: Word32

  Any extent of size bigger or equal to this number will be considered already defragged. Use 0 for the kernel default.

• draCompress :: CompressionType

  Compress the file while defragmenting.

• draFlush :: Bool

  Flush data to disk immediately after defragmenting.

Instances

Eq DefragRangeArgs

Defined in System.Linux.Btrfs.ByteString

Methods

(==) :: DefragRangeArgs -> DefragRangeArgs -> Bool

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

Show DefragRangeArgs

Defined in System.Linux.Btrfs.ByteString

Methods

showsPrec :: Int -> DefragRangeArgs -> ShowS

show :: DefragRangeArgs -> String

showList :: [DefragRangeArgs] -> ShowS

defaultDefragRangeArgs :: DefragRangeArgs

Defaults for defragRange. Selects the entire file, no compression, and no flushing.

defragRangeFd :: Fd -> DefragRangeArgs -> IO ()

defragRange :: RawFilePath -> DefragRangeArgs -> IO ()

Defrag a range within a single file.

Note: calls the BTRFS_IOC_DEFRAG_RANGE ioctl.

File system info

data FSInfo

Information about a btrfs file system.

Instances

Eq FSInfo

Defined in System.Linux.Btrfs.ByteString

Methods

(==) :: FSInfo -> FSInfo -> Bool

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

Show FSInfo

Defined in System.Linux.Btrfs.ByteString

Methods

showsPrec :: Int -> FSInfo -> ShowS

show :: FSInfo -> String

showList :: [FSInfo] -> ShowS

fsiDeviceCount :: FSInfo -> Word64

The number of devices in the file system.

fsiUuid :: FSInfo -> UUID

The UUID of the file system.

fsiNodeSize :: FSInfo -> FileSize

The tree block size in which metadata is stored.

fsiSectorSize :: FSInfo -> FileSize

The minimum data block allocation unit.

fsiCloneAlignment :: FSInfo -> FileSize

The size that is used for the alignment constraints of clone range operations.

getFSInfoFd :: Fd -> IO FSInfo

getFSInfo

Arguments

:: RawFilePath

The mount point of the volume (or any file in that volume).

-> IO FSInfo

Retrieve information about a btrfs file system.

Note: calls the BTRFS_IOC_FS_INFO ioctl.

File system label

getFSLabelFd :: Fd -> IO RawFilePath

getFSLabel

Arguments

:: RawFilePath

The mount point of the volume (or any file in that volume).

-> IO RawFilePath

Retrieve the label of a btrfs file system.

Note: calls the BTRFS_IOC_GET_FSLABEL ioctl.

setFSLabelFd :: Fd -> RawFilePath -> IO ()

setFSLabel

Arguments

:: RawFilePath

The mount point of the volume (or any file in that volume).

-> RawFilePath

The new label.

-> IO ()

Set the label of a btrfs file system. Note that a label can be up to 255 bytes long. If the provided label is longer, it will be silently truncated.

Note: calls the BTRFS_IOC_SET_FSLABEL ioctl.

Sync

syncFd :: Fd -> IO ()

sync :: RawFilePath -> IO ()

Sync the file system identified by the supplied path. The FilePath can refer to any file in the file system.

Note: calls the BTRFS_IOC_SYNC ioctl.

startSyncFd :: Fd -> IO ()

startSync :: RawFilePath -> IO ()

Initiate a sync for the file system identified by the supplied path.

Note: calls the BTRFS_IOC_START_SYNC ioctl.

waitSyncFd :: Fd -> IO ()

waitSync :: RawFilePath -> IO ()

Wait until the sync operation completes.

Note: calls the BTRFS_IOC_WAIT_SYNC ioctl.

Inspect internal

resolveLogicalFd :: Fd -> FileSize -> IO ([(InodeNum, FileSize, SubvolId)], Int)

resolveLogical

Arguments

:: RawFilePath

The mount point of the volume (or any file in that volume).

-> FileSize

The physical byte offset in the underlying block device.

-> IO ([(InodeNum, FileSize, SubvolId)], Int)

Given a physical offset, look for any inodes that this byte belongs to. For each inode, it returns the inode number, the logical offset (i.e. the offset within the inode), and the subvolume id. If a large number of inodes is found, then not all of them will be returned by this function. This is due to a current limitation in the kernel. The integer returned along with list of inodes indicates the number of inodes found but not included in the list.

Note: calls the BTRFS_IOC_LOGICAL_INO ioctl.

resolveInodeFd :: Fd -> InodeNum -> IO ([RawFilePath], Int)

resolveInode

Arguments

:: RawFilePath

The path to the subvolume (or any file in that subvolume).

-> InodeNum

The inode number.

-> IO ([RawFilePath], Int)

Find the file path(s) given an inode number. Returns a list of file paths and an integer indicating the number of paths found but not included in the resulting list. This is because of a limitation in the kernel (it will not return an arbitrarily large list). The paths returned are relative to the root of the subvolume.

Note: calls the BTRFS_IOC_INO_PATHS ioctl.

lookupInodeFd :: Fd -> SubvolId -> InodeNum -> IO (SubvolId, RawFilePath)

lookupInode

Arguments

:: RawFilePath

The path to any file in the volume. The subvolume where this file resides is ignored unless no SubvolId is provided (see below).

-> SubvolId

The id of the subvolume. Can be 0. In that case, the subvolume of the FilePath is used (see above).

-> InodeNum

The inode number.

-> IO (SubvolId, RawFilePath)

Find the path of a file given its inode number and the id of the subvolume. If multiple files share the same inode number, only one of them is returned. The id of the subvolume is also returned. This is useful when 0 is given for the SubvolId argument (also see getSubvol for this case).

Note: calls the BTRFS_IOC_INO_LOOKUP ioctl.

Miscellaneous

getFileNoCOWFd :: Fd -> IO Bool

getFileNoCOW :: RawFilePath -> IO Bool

Determine whether the NOCOW flag is enabled for the specified file.

Note: calls the FS_IOC_GETFLAGS ioctl.

setFileNoCOWFd :: Fd -> Bool -> IO ()

setFileNoCOW :: RawFilePath -> Bool -> IO ()

Set or clear the NOCOW flag for the specified file. If the file is not empty, this has no effect and no error will be reported.

Note: calls the FS_IOC_GETFLAGS and FS_IOC_GETFLAGS ioctls.

Tree search

Low-level API for tree search using the BTRFS_IOC_TREE_SEARCH ioctl.

data SearchKey

Constructors

SearchKey

Fields

• skTreeId :: ObjectId
• skMinObjectId :: ObjectId
• skMinType :: ObjectType
• skMinOffset :: Word64
• skMaxObjectId :: ObjectId
• skMaxType :: ObjectType
• skMaxOffset :: Word64
• skMinTransId :: Word64
• skMaxTransId :: Word64

Instances

Eq SearchKey

Defined in System.Linux.Btrfs.ByteString

Methods

(==) :: SearchKey -> SearchKey -> Bool

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

Show SearchKey

Defined in System.Linux.Btrfs.ByteString

Methods

showsPrec :: Int -> SearchKey -> ShowS

show :: SearchKey -> String

showList :: [SearchKey] -> ShowS

defaultSearchKey :: SearchKey

data SearchHeader

Constructors

SearchHeader

Fields

• shTransId :: Word64
• shObjectId :: ObjectId
• shOffset :: Word64
• shType :: ObjectType
• shLen :: Word32

Instances

Eq SearchHeader

Defined in System.Linux.Btrfs.ByteString

Methods

(==) :: SearchHeader -> SearchHeader -> Bool

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

Show SearchHeader

Defined in System.Linux.Btrfs.ByteString

Methods

showsPrec :: Int -> SearchHeader -> ShowS

show :: SearchHeader -> String

showList :: [SearchHeader] -> ShowS

treeSearchFd :: Fd -> SearchKey -> Int -> (SearchHeader -> Ptr i -> IO ()) -> IO ()

treeSearch :: RawFilePath -> SearchKey -> Int -> (SearchHeader -> Ptr i -> IO ()) -> IO ()

treeSearchListFd :: Fd -> SearchKey -> (SearchHeader -> Ptr i -> IO (Maybe a)) -> IO [a]

treeSearchList :: RawFilePath -> SearchKey -> (SearchHeader -> Ptr i -> IO (Maybe a)) -> IO [a]

findFirstItemFd :: Fd -> SearchKey -> (SearchHeader -> Ptr i -> IO a) -> IO a

findFirstItem :: RawFilePath -> SearchKey -> (SearchHeader -> Ptr i -> IO a) -> IO a