xattr

README

xattr

Documentation

Overview

Package xattr provides a typed Go API for working with POSIX-style extended file attributes.

Operations are dispatched through three target types: Path for filesystem paths, File for an open *os.File, and FD for a raw file descriptor. Each target supports the same set of operations (Get, Set, List, Remove, Supported) configured by functional options.

Read operations (Get, List) return empty results without error when the underlying filesystem does not support extended attributes; write operations (Set, Create, Replace, Mirror) return ErrUnsupported. Remove silently succeeds on unsupported filesystems because the attribute is, by construction, already absent.

Index

• Constants
• Variables
• func Create(t Target, key Key, data []byte, opts ...Option) error
• func Get(t Target, key Key, opts ...Option) ([]byte, error)
• func GetString(t Target, key Key, opts ...Option) (string, error)
• func Has(t Target, key Key, opts ...Option) (bool, error)
• func Mirror(src, dst Target, opts ...Option) error
• func NamesIter(t Target, opts ...Option) (iter.Seq[Key], func() error)
• func Remove(t Target, key Key, opts ...Option) error
• func Replace(t Target, key Key, data []byte, opts ...Option) error
• func Set(t Target, key Key, data []byte, opts ...Option) error
• func SetString(t Target, key Key, data string, opts ...Option) error
• func Supported(t Target, opts ...Option) (bool, error)
• type FD
  • func NewFDBorrowed(fd int) FD
• type File
  • func NewFileBorrowed(f *os.File) File
• type Key
  • func List(t Target, opts ...Option) ([]Key, error)
  • func ParseKey(s string) (Key, error)
  • func SecurityKey(name string) Key
  • func SystemKey(name string) Key
  • func TrustedKey(name string) Key
  • func UserKey(name string) Key
  • func (k Key) Name() string
  • func (k Key) Namespace() string
  • func (k Key) String() string
• type Option
  • func MaxBuffer(n int) Option
  • func WithContext(ctx context.Context) Option
• type Path
  • func NewPath(p string) Path
  • func (p Path) Follow(v bool) Path
  • func (p Path) NoFollow() Path
  • func (p Path) String() string
• type Target

Constants

const (
	NamespaceUser     = "user"
	NamespaceTrusted  = "trusted"
	NamespaceSecurity = "security"
	NamespaceSystem   = "system"
)

Standard xattr namespace prefixes used on Linux.

Variables

var ErrNamespaceUnsupported = errors.New("xattr: namespace not supported on this platform")

ErrNamespaceUnsupported is returned when an operation references a Key whose namespace is not available on the current platform. For example, the trusted and security namespaces exist on Linux but not on FreeBSD.

var ErrUnsupported = errors.New("xattr: not supported by filesystem")

ErrUnsupported is returned by Set and Mirror when the underlying filesystem does not support extended attributes.

Functions

func Create

func Create(t Target, key Key, data []byte, opts ...Option) error

Create writes the named extended attribute on t, failing if it already exists. On Linux and Darwin this maps to XATTR_CREATE semantics. On FreeBSD, whose extattr_set_* has no create-only mode, Create returns ErrUnsupported.

func Get

func Get(t Target, key Key, opts ...Option) ([]byte, error)

Get reads the value of the named extended attribute from t. It returns (nil, nil) when the underlying filesystem does not support extended attributes.

func GetString

func GetString(t Target, key Key, opts ...Option) (string, error)

GetString reads the named extended attribute as a string. It is equivalent to converting the result of Get with string(...) and shares its return semantics: an empty string with nil error when the underlying filesystem does not support extended attributes.

xattr values are not typed at the kernel level; GetString does not validate that the value is well-formed text. It is the caller's assertion that the named attribute is textual.

func Has

func Has(t Target, key Key, opts ...Option) (bool, error)

Has reports whether t has an extended attribute with the given key. It returns (false, nil) when the attribute is absent and when extended attributes are not supported.

func Mirror

func Mirror(src, dst Target, opts ...Option) error

Mirror copies extended attributes from src to dst, removing from dst any attribute that is not present on src. The result is that dst's xattr set is byte-for-byte equal to src's after a successful return.

If src does not support xattrs, dst is left empty (any pre-existing attributes are removed). If dst does not support xattrs and src has any attributes to copy, the operation fails with ErrUnsupported on the first Set; partial progress is possible.

func NamesIter

func NamesIter(t Target, opts ...Option) (iter.Seq[Key], func() error)

NamesIter returns a streaming iterator over the names of all extended attributes set on t. The returned sequence yields keys in an unspecified order — use List if you need them sorted. The second return value is an error-reporting closure that must be invoked after iteration completes (or after breaking out of it); it surfaces any error encountered during the syscall layer's enumeration.

When extended attributes are not supported, the sequence yields nothing and the error closure returns nil. Calling the error closure before consuming the sequence returns nil; the work is deferred until iteration begins.

func Remove

func Remove(t Target, key Key, opts ...Option) error

Remove deletes the named extended attribute from t. It returns nil when extended attributes are not supported, since the attribute is necessarily absent.

func Replace

func Replace(t Target, key Key, data []byte, opts ...Option) error

Replace writes the named extended attribute on t, failing if it does not already exist. On Linux and Darwin this maps to XATTR_REPLACE semantics. On FreeBSD, whose extattr_set_* has no replace-only mode, Replace returns ErrUnsupported.

func Set

func Set(t Target, key Key, data []byte, opts ...Option) error

Set writes the named extended attribute on t. The attribute is created if absent and overwritten if present. It returns ErrUnsupported when the underlying filesystem does not support extended attributes.

func SetString

func SetString(t Target, key Key, data string, opts ...Option) error

SetString writes the named extended attribute from a string. It is equivalent to calling Set with []byte(data) and shares its semantics, including returning ErrUnsupported on filesystems without xattr support.

func Supported

func Supported(t Target, opts ...Option) (bool, error)

Supported reports whether t's filesystem supports extended attributes. The returned error is non-nil only when the probe itself fails for an unrelated reason (e.g. the path does not exist).

Types

type FD

type FD int

FD is an xattr target backed by a raw file descriptor. It exists for interop with golang.org/x/sys/unix and similar callers that work with numeric descriptors directly. The caller is responsible for keeping the descriptor open across calls.

func NewFDBorrowed

func NewFDBorrowed(fd int) FD

NewFDBorrowed constructs an FD target from a numeric file descriptor. The fd is borrowed: the caller retains ownership and must keep it open and unmodified for the lifetime of the returned FD value. If you need the package to keep an owning reference alive across calls, wrap your fd in an *os.File via os.NewFile and use NewFileBorrowed instead.

type File

type File struct {
	// contains filtered or unexported fields
}

File is an xattr target backed by an open *os.File. The file is held by reference so the GC will not finalize it during a syscall.

func NewFileBorrowed

func NewFileBorrowed(f *os.File) File

NewFileBorrowed constructs a File target from an open *os.File. The *os.File is borrowed: the caller retains ownership and must keep it open for the lifetime of the returned File value. The package holds a reference to f so it cannot be finalized during a syscall, but it does not Close f and does not protect against the caller closing it.

type Key

type Key string

Key is the name of an extended attribute, such as "user.comment". It is a typed string so xattr keys are kept distinct from arbitrary strings at every call site. The underlying value is the full "namespace.name" form expected by the kernel.

func List

func List(t Target, opts ...Option) ([]Key, error)

List returns the names of all extended attributes set on t, sorted lexicographically. It returns (nil, nil) when extended attributes are not supported.

List is the materializing form built on top of NamesIter; callers who want to break out of the enumeration early, or who do not need a sorted result, should prefer NamesIter for the cycle savings (more pronounced on platforms whose listing is multi-step, such as the FreeBSD extattr namespaces).

func ParseKey

func ParseKey(s string) (Key, error)

ParseKey validates and returns a Key from a "namespace.name" string. It returns an error if s is not in that form (missing separator, empty namespace, or empty name).

func SecurityKey

func SecurityKey(name string) Key

SecurityKey returns a Key in the security namespace. Used by Linux security modules such as SELinux, Smack, and AppArmor.

func SystemKey

func SystemKey(name string) Key

SystemKey returns a Key in the system namespace. Used by the kernel for filesystem-managed attributes such as POSIX ACLs.

func TrustedKey

func TrustedKey(name string) Key

TrustedKey returns a Key in the trusted namespace. Reading and writing trusted xattrs requires CAP_SYS_ADMIN.

func UserKey

func UserKey(name string) Key

UserKey returns a Key in the user namespace ("user." + name). The user namespace is the standard place for application-defined attributes and is accessible without special privileges.

func (Key) Name

func (k Key) Name() string

Name returns the name portion of the key (the part after the first "."). Returns the empty string if k has no separator.

func (Key) Namespace

func (k Key) Namespace() string

Namespace returns the namespace portion of the key (the part before the first "."). Returns the empty string if k has no separator.

func (Key) String

func (k Key) String() string

String returns the full key string ("namespace.name").

type Option

type Option interface {
	// contains filtered or unexported methods
}

Option configures an xattr operation.

func MaxBuffer

func MaxBuffer(n int) Option

MaxBuffer overrides the default 64 MiB ceiling on Get and List buffer growth. The buffer doubles on each retry until it fits the value or reaches this limit.

func WithContext

func WithContext(ctx context.Context) Option

WithContext attaches a context to the operation. The context controls retry-on-EINTR cancellation in the underlying syscall layer.

type Path

type Path struct {
	// contains filtered or unexported fields
}

Path is an xattr target identified by a filesystem path. By default, symlinks are followed; call NoFollow to obtain a copy that operates on the symlink itself.

func NewPath

func NewPath(p string) Path

NewPath constructs a Path target. The returned Path follows symlinks.

func (Path) Follow

func (p Path) Follow(v bool) Path

Follow returns a copy of the Path that follows symlinks if v is true or operates on the symlink itself if v is false.

func (Path) NoFollow

func (p Path) NoFollow() Path

NoFollow returns a copy of p that operates on the symlink itself rather than the file it refers to.

func (Path) String

func (p Path) String() string

String returns the underlying filesystem path.

type Target

type Target interface {
	// contains filtered or unexported methods
}

Target is a sealed interface implemented by Path, File, and FD. The top-level operations (Get, Set, Has, List, NamesIter, Remove, Supported, Mirror) dispatch through it. It cannot be implemented by types outside this package.

xnames is the streaming primitive that backs both List (collect + sort) and NamesIter (pass through). Implementations return an iter.Seq[Key] plus an error-reporting closure; the closure captures any error produced during iteration so callers can check it after consuming the sequence.