System.Linux.XAttr

linux-xattr provides bindings to the Linux syscalls for reading and manipulating extended attributes (setxattr, getxattr, listxattr and removexattr).

Each function in this module has two variants: one with the name prefixed by l and one prefixed by fd. Both of these are identical to the original version except that the l-variant does not follow symbolic link but acts on the link itself, and the fd-variant take a file descriptor as argument rather than a FilePath.

Moreover, every function has an xxxUserXAttr variant for working transparently in the user namespace of extended attributes, without worrying about the "user." prefix: these functions automatically prepends the string "user." to the Name of the attribute when Name is an input value, or strip the prefix "user." from it when Name is a returned value. See the documentation of each individual function for details.

Set extended attributes

Functions in this section call the setxattr syscall.

setXAttr :: FilePath -> Name -> Value -> IO ()

Set the Value of the extended attribute identified by Name and associated with the given FilePath in the filesystem.

lSetXAttr :: FilePath -> Name -> Value -> IO ()

Set the Value of the extended attribute identified by Name and associated with the given FilePath in the filesystem (do not follow symbolic links).

fdSetXAttr :: Fd -> Name -> Value -> IO ()

Set the Value of the extended attribute identified by Name and associated with the given file descriptor in the filesystem.

Set extended user attributes

setUserXAttr :: FilePath -> Name -> Value -> IO ()

setUserXAttr "/some/path" "foo" "bar" = setXAttr "/some/path" "user.foo" "bar"

lSetUserXAttr :: FilePath -> Name -> Value -> IO ()

lSetUserXAttr "/some/link" "foo" "bar" = lSetXAttr "/some/link" "user.foo" "bar"

fdSetUserXAttr :: Fd -> Name -> Value -> IO ()

fdSetUserXAttr (Fd n) "foo" "bar" = fdSetXAttr (Fd n) "user.foo" "bar"

Create extended attributes

Functions in this section call the setxattr syscall with the flag XATTR_CREATE.

createXAttr :: FilePath -> Name -> Value -> IO ()

Identical to setXAttr, but if the attribute already exists fail with isAlreadyExistsError.

lCreateXAttr :: FilePath -> Name -> Value -> IO ()

Identical to lSetXAttr, but if the attribute already exists fail with isAlreadyExistsError.

fdCreateXAttr :: Fd -> Name -> Value -> IO ()

Identical to fdSetXAttr, but if the attribute already exists fail with isAlreadyExistsError.

Create extended user attributes

createUserXAttr :: FilePath -> Name -> Value -> IO ()

createUserXAttr "/some/path" "foo" "bar" = createXAttr "/some/path" "user.foo" "bar"

lCreateUserXAttr :: FilePath -> Name -> Value -> IO ()

lCreateUserXAttr "/some/link" "foo" "bar" = lCreateXAttr "/some/link" "user.foo" "bar"

fdCreateUserXAttr :: Fd -> Name -> Value -> IO ()

fdCreateUserXAttr (Fd n) "foo" "bar" = fdCreateXAttr (Fd n) "user.foo" "bar"

Replace extended attributes

Functions in this section call the setxattr syscall with the flag XATTR_REPLACE.

replaceXAttr :: FilePath -> Name -> Value -> IO ()

Identical to setXAttr, but if the attribute does not exist fail with isDoesNotExistError.

lReplaceXAttr :: FilePath -> Name -> Value -> IO ()

Identical to lSetXAttr, but if the attribute does not exist fail with isDoesNotExistError.

fdReplaceXAttr :: Fd -> Name -> Value -> IO ()

Identical to fdSetXAttr, but if the attribute does not exist fail with isDoesNotExistError.

Replace extended user attributes

replaceUserXAttr :: FilePath -> Name -> Value -> IO ()

replaceUserXAttr "/some/path" "foo" "bar" = replaceXAttr "/some/path" "user.foo" "bar"

lReplaceUserXAttr :: FilePath -> Name -> Value -> IO ()

lReplaceUserXAttr "/some/link" "foo" "bar" = lReplaceXAttr "/some/link" "user.foo" "bar"

fdReplaceUserXAttr :: Fd -> Name -> Value -> IO ()

fdReplaceUserXAttr (Fd n) "foo" "bar" = fdReplaceXAttr (Fd n) "user.foo" "bar"

Retrieve extended attributes

Functions in this section call the getxattr syscall.

getXAttr :: FilePath -> Name -> IO Value

Retrieve the Value of the extended attribute identified by Name and associated with the given FilePath in the filesystem, or fail with isDoesNotExistError if the attribute does not exist.

lGetXAttr :: FilePath -> Name -> IO Value

Retrieve the Value of the extended attribute identified by Name and associated with the given FilePath in the filesystem, or fail with isDoesNotExistError if the attribute does not exist (do not follow symbolic links).

fdGetXAttr :: Fd -> Name -> IO Value

Retrieve the Value of the extended attribute identified by Name and associated with the given file descriptor in the filesystem, or fail with isDoesNotExistError if the attribute does not exist.

Retrieve extended user attributes

getUserXAttr :: FilePath -> Name -> IO Value

getUserXAttr "/some/path" "foo" = getXAttr "/some/path" "user.foo"

lGetUserXAttr :: FilePath -> Name -> IO Value

lGetUserXAttr "/some/link" "foo" = lGetXAttr "/some/link" "user.foo"

fdGetUserXAttr :: Fd -> Name -> IO Value

fdGetUserXAttr (Fd n) "foo" = fdGetXAttr (Fd n) "user.foo"

List extended attributes

Functions in this section call the listxattr syscall.

listXAttr :: FilePath -> IO [Name]

Get the list of extended attribute Names associated with the given FilePath in the filesystem.

lListXAttr :: FilePath -> IO [Name]

Get the list of extended attribute Names associated with the given FilePath in the filesystem (do not follow symbolic links).

fdListXAttr :: Fd -> IO [Name]

Get the list of extended attribute Names associated with the given file descriptor in the filesystem.

List extended user attributes

These functions only list those extended attributes with Name beginning with "user.". The "user." prefix is removed from each Name in the output list.

listUserXAttr :: FilePath -> IO [Name]

>>> listXAttr "/some/path"
["user.foo","user.bar"]
>>> listUserXAttr "/some/path"
["foo","bar"]

lListUserXAttr :: FilePath -> IO [Name]

>>> lListXAttr "/some/link"
["user.foo","user.bar"]
>>> lListUserXAttr "/some/link"
["foo","bar"]

fdListUserXAttr :: Fd -> IO [Name]

>>> fdListXAttr (Fd n)
["user.foo","user.bar"]
>>> fdListUserXAttr (Fd n)
["foo","bar"]

Remove extended attributes

Functions in this section call the removexattr syscall.

removeXAttr :: FilePath -> Name -> IO ()

Remove the extended attribute identified by Name and associated with the given FilePath in the filesystem, or fail with isDoesNotExistError if the attribute does not exist.

lRemoveXAttr :: FilePath -> Name -> IO ()

Remove the extended attribute identified by Name and associated with the given FilePath in the filesystem, or fail with isDoesNotExistError if the attribute does not exist (do not follow symbolic links).

fdRemoveXAttr :: Fd -> Name -> IO ()

Remove the extended attribute identified by Name and associated with the given file descriptor in the filesystem, or fail with isDoesNotExistError if the attribute does not exist.

Remove extended user attributes

removeUserXAttr :: FilePath -> Name -> IO ()

removeUserXAttr "/some/path" "foo" = removeXAttr "/some/path" "user.foo"

lRemoveUserXAttr :: FilePath -> Name -> IO ()

lRemoveUserXAttr "/some/link" "foo" = lRemoveXAttr "/some/link" "user.foo"

fdRemoveUserXAttr :: Fd -> Name -> IO ()

fdRemoveUserXAttr (Fd n) "foo" = fdRemoveXAttr (Fd n) "user.foo"

Types for extended attributes

type Name = String

Name of extended attribute.

type Value = ByteString

Value of extended attribute.