NAMED_ATTRIBUTE(7)

📦 version 15.1, in freebsd 15.1, nixpkgs unstable

🦋 NAMED_ATTRIBUTE(7) 🦋

okay bestie, so this is the named_attribute page — it's giving "Solaris-like extended attribute system interface" energy, and honestly it's kind of iconic once you get past the syscall lore. sit down, grab a lil snack 🍓, and let's get into it.

✨ NAME ✨

named_attribute — the Solaris-like extended attribute system interface. yup. that's the whole vibe. 💅

💖 DESCRIPTION 💖

So this page is all about the system interface for named attributes (that's the NFS Version 4 terminology, iykyk).

🌸 Introduction 🌸

This doc describes an alternate system interface for extended attributes compared to extattr(2). It's based on the interface that Solaris and NFS Version 4 provide. basically the cooler, more file-y cousin.

This interface associates a directory — known as a named attribute directory — to a file system object. You read this directory the same manner as a normal directory via the getdents(2) or getdirentries(2) system calls. The . and .. entries refer to the directory itself and to the associated file object, respectively. The other entries in this directory are the names of the extended attributes for the associated file object, and they're referred to as named attributes. These named attributes are regular files used to store the attribute's value.

A named attribute directory does not live in the file system's name space. You access it via an open(2) or openat(2) system call done on a file to query the named attributes for the file, with the O_NAMEDATTR flag specified and a path argument of ... This file descriptor can be used as the fd argument for a variety of system calls, such as: fchdir(2), unlinkat(2) and renameat(2). Heads up: renameat(2) is only permitted to rename a named attribute within the same named attribute directory. no sneaky cross-directory moves, bestie 🚫

When a file descriptor for a file object in the file system's namespace is used as the fd argument of an openat(2) along with the flag O_NAMEDATTR and a path argument that is the name of a named attribute (not . or ..), a file descriptor for the named attribute is returned. If the flag O_CREAT is specified, the named attribute will be created if it does not exist. The path argument must be a single component name, with no embedded “/” in it. I/O on these named attribute file descriptors may be performed by standard I/O system calls such as: read(2), write(2), lseek(2) and ftruncate(2).

The _PC_NAMEDATTR_ENABLED name argument to pathconf(2) will return 1 if the file system supports named attributes. The _PC_HAS_NAMEDATTR name argument to pathconf(2) will return 1 if there are one or more named attributes for the file. If an application does a openat(2) of “.” to open a named attribute directory when no named attribute directory exists, an empty named attribute directory will be created. Testing _PC_HAS_NAMEDATTR can be done to avoid creating these named attribute directories unnecessarily. literally a little "look before you create" moment 👀

The named attribute interface is a different mechanism/system call interface for manipulating extended attributes compared with extattr(2). Although the named attribute mechanism might require different internal implementation of extended attributes within a file system, both ZFS and NFSv4 provide both mechanisms, which can be used interchangeably to manipulate extended attributes — but with a few limitations. list time:

  • The extattr(2) interface requires that an extended attribute's value be set or acquired via a single system call using a single buffer. This limits the size of the attribute's value. 😭
  • The named attribute interface does not support system namespace extended attributes and, as such, system namespace extended attributes must be manipulated via extattr(2).
  • For ZFS, if an extended attribute with a value that is a small length in bytes is created when the ZFS xattr property is set to “sa”, that extended attribute is only visible via extattr(2) and not as a named attribute. Archiving/de-archiving the file via tar(1) after setting the xattr property to “dir” will make the attribute(s) visible as both named attributes and via extattr(2).
  • For ZFS, it is also possible to create two attributes with the same name by creating one when the ZFS xattr property is set to “sa” and then creating another one with the same name after the ZFS property xattr has been changed to “dir”. The one created when the ZFS xattr property is set to “sa” may be removed via rmextattr(8).
  • To avoid these issues for ZFS, it is strongly recommended that the ZFS property xattr be set to “dir” as soon as the file system is created, if named attributes are to be used on the file system. fr fr, do this early. 🔥

The named attribute mechanism/system call interface provides certain advantages over extattr(2). Since the attribute's value is updated via read(2) and write(2) system calls, the attribute's data may be as large as any regular file and may be partially updated. (Note that this interface does not provide the atomicity guarantee that extattr(2) does.) The permission to access a named attribute directory is determined from the access control information for the associated file object. However, access control information can be set on each individual attribute in a manner similar to a regular file. This provides “per attribute” granular control over attribute permissions via fchown(2). slay, per-attribute permission era 👑

At this time, the only local file system which supports this interface is ZFS and only if the xattr property is set to “dir”. (Note that, even when zfs get xattr <file-system> shows “on” the command zfs set xattr=dir <file-system> must be done, followed by a remount to make the setting take effect.) A NFSv4 mount will also support this interface, but only if the NFSv4 server file system supports named attributes (the openattr operation). The FreeBSD NFSv4 server supports named attributes only for ZFS exported file systems where the “xattr” property is set to “dir” for the file system.

⚠️ real talk: if you're on ZFS and you want named attributes, set that xattr property to “dir” from the jump. do not play with “sa” unless you're ready for the lore.

🎀 EXAMPLES 🎀

okay this is the part where we actually do stuff. here's the whole code moment, verbatim bestie:

#include <stdio.h>
#include <dirent.h>
#include <fcntl.h>
#include <unistd.h>

...

/* For a file called "myfile". Failure checks removed for brevity. */
int file_fd, nameddir_fd, namedattr_fd;
ssize_t siz;
char buf[DIRBLKSIZ], *cp;
struct dirent *dp;
long named_enabled, has_named_attrs;

...
/* Check to see if named attributes are supported. */
named_enabled = pathconf("myfile", _PC_NAMEDATTR_ENABLED);
if (named_enabled <= 0)
        err(1, "Named attributes not enabled");
/* Test to see if named attribute(s) exist for the file. */
has_named_attrs = pathconf("myfile", _PC_HAS_NAMEDATTR);
if (has_named_attrs == 1)
        printf("myfile has named attribute(s)\n");
else
        printf("myfile does not have any named attributes\n");
/* Open a named attribute directory. */
file_fd = open("myfile", O_RDONLY, 0);
nameddir_fd = openat(file_fd, ".", O_NAMEDATTR, 0);
...
/* and read it, assuming it all fits in DIRBLKSIZ for simplicity. */
siz = getdents(fd, buf, sizeof(buf));
cp = buf;
while (cp < &buf[siz]) {
        dp = (struct dirent *)cp;
        printf("name=%s\n", dp->d_name);
        cp += dp->d_reclen;
}
...
/* Open/create a named attribute called "foo". */
namedattr_fd = openat(file_fd, "foo", O_CREAT | O_RDWR |
    O_TRUNC | O_NAMEDATTR, 0600);
...
/* Write foo's attribute value. */
write(namedattr_fd, "xxxyyy", 6);
...
/* Read foo's attribute value. */
lseek(namedattr_fd, 0, SEEK_SET);
siz = read(namedattr_fd, buf, sizeof(buf));
...
/* And close "foo". */
close(namedattr_fd);
...
/* Rename "foo" to "oldfoo". */
renameat(nameddir_fd, "foo", nameddir_fd, "oldfoo");
/* and delete "oldfoo". */
unlinkat(nameddir_fd, "oldfoo", AT_RESOLVE_BENEATH);

The runat(1) command may be used to perform shell commands on named attributes. for example:

$ runat myfile cp /etc/hosts attrhosts  # creates attrhosts
$ runat myfile cat attrhosts            # displays contents of attrhosts
$ runat myfile ls -l                    # lists the attributes for myfile

If using the bash(1) shell, the command “cd -@ foo” enters the named attribute directory for the file object “foo”. cute little shortcut, no cap 💅

🌈 SEE ALSO 🌈

okay the whole friend group is here:

⭐ HISTORY ⭐

This interface first appeared in FreeBSD 15.0. a whole era was born. 👑

and that's the page, bestie! written with love on the Debian side, dated August 5, 2025 — go forth and name those attributes responsibly. NAMED_ATTRIBUTE(7) out. 🫶💜

📦 where this page comes from