EXTATTRCTL(2)

EXTATTRCTL(2) | System Calls Manual | EXTATTRCTL(2)

# NAME

`extattrctl` — control extended attributes on a UFS1 file system

# SYNOPSIS

`#include <sys/extattr.h>`
`#include <ufs/ufs/extattr.h>`

int
`extattrctl`(const char *path, int cmd, const char *filename, int attrnamespace, const char *attrname);

# DESCRIPTION

The `extattrctl`() system call provides low-level control over extended attributes on a UFS1 file system. It allows enabling, disabling, and managing extended attributes.

Since there was no provision in the UFS1 file system for attributes, they are stored as regular files and directories in the file system under the /.attribute directory. By convention, there are usually two directories directly under it, separating two namespaces: “user” and “system”. Under these, there are named attributes that can be created and managed using extattrctl(8).

This programming interface is currently only used by extattrctl(8), and is not intended for general use.

# PARAMETERS

path
  The path to the mount point of the file system.
cmd
  The command to execute. Valid commands are:
  `UFS_EXTATTR_CMD_ENABLE`
    Enable a specific extended attribute.
  `UFS_EXTATTR_CMD_DISABLE`
    Disable a specific extended attribute.
  `UFS_EXTATTR_CMD_START`
    Start extended attribute support on the file system.
  `UFS_EXTATTR_CMD_STOP`
    Stop extended attribute support on the file system.
attrname
  The name of the extended attribute (for relevant commands).
attrnamespace
  The attribute namespace, such as `EXTATTR_NAMESPACE_USER` or `EXTATTR_NAMESPACE_SYSTEM`.
filename
  The path to a backing file for extended attribute storage (if required by the command).

# RETURN VALUES

The `extattrctl`() function returns the value 0 if successful; otherwise the value -1 is returned and the global variable errno is set to indicate the error.

# EXAMPLES

Enable an attribute on a file system:

    #include <sys/extattr.h>
    #include <ufs/ufs/extattr.h>

    if (extattrctl("/home", UFS_EXTATTR_CMD_ENABLE,
        "/.attribute/user/comment",
        EXTATTR_NAMESPACE_USER, "comment") == -1)
    	err(EXIT_FAILURE, "extattrctl");

# ERRORS

The `extattrctl`() system call may fail with the following errors:

[`EACCES`]
  The calling user does not have permission to access the file specified.
[`EINVAL`]
  Invalid arguments were provided.
[`ENOENT`]
  The specified path, attribute, or file does not exist.
[`EOPNOTSUPP`]
  The file system does not support extended attributes.
[`EPERM`]
  The calling user is not permitted to change extended attributes.

# SEE ALSO

extattr_delete_file(2), extattr_get_file(2), extattr_list_file(2), extattr_set_file(2), extattrctl(8)

# HISTORY

The `extattrctl`() system call was imported from FreeBSD 5.0 in NetBSD 3.0.

March 9, 2025 | NetBSD 11.0