.\" $NetBSD: extattrctl.2,v 1.7 2025/03/11 14:13:45 wiz Exp $
.\" Copyright (c) 2025 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Christos Zoulas.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd March 9, 2025
.Dt EXTATTRCTL 2
.Os
.Sh NAME
.Nm extattrctl
.Nd control extended attributes on a UFS1 file system
.Sh SYNOPSIS
.In sys/extattr.h
.In ufs/ufs/extattr.h
.Ft int
.Fn extattrctl "const char *path" "int cmd" "const char *filename" "int attrnamespace" "const char *attrname"
.Sh DESCRIPTION
The
.Fn extattrctl
system call provides low-level control over extended attributes on a UFS1
file system.
It allows enabling, disabling, and managing extended attributes.
.Pp
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
.Pa "/.attribute"
directory.
By convention, there are usually two directories directly under it,
separating two namespaces:
.Dq user
and
.Dq system .
Under these, there are named attributes that can be created and
managed using
.Xr extattrctl 8 .
.Pp
This programming interface is currently only used by
.Xr extattrctl 8 ,
and is not intended for general use.
.Sh PARAMETERS
.Bl -tag -width indent
.It Fa path
The path to the mount point of the file system.
.It Fa cmd
The command to execute.
Valid commands are:
.Bl -tag -width indent
.It Dv UFS_EXTATTR_CMD_ENABLE
Enable a specific extended attribute.
.It Dv UFS_EXTATTR_CMD_DISABLE
Disable a specific extended attribute.
.It Dv UFS_EXTATTR_CMD_START
Start extended attribute support on the file system.
.It Dv UFS_EXTATTR_CMD_STOP
Stop extended attribute support on the file system.
.El
.It Fa attrname
The name of the extended attribute (for relevant commands).
.It Fa attrnamespace
The attribute namespace, such as
.Dv EXTATTR_NAMESPACE_USER
or
.Dv EXTATTR_NAMESPACE_SYSTEM .
.It Fa filename
The path to a backing file for extended attribute storage
(if required by the command).
.El
.Sh RETURN VALUES
.Rv -std extattrctl
.Sh EXAMPLES
Enable an attribute on a file system:
.Bd -literal -offset indent
#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");
.Ed
.Sh ERRORS
The
.Fn extattrctl
system call may fail with the following errors:
.Bl -tag -width Bq -offset indent
.It Bq Er EACCES
The calling user does not have permission to access the file
specified.
.It Bq Er EINVAL
Invalid arguments were provided.
.It Bq Er ENOENT
The specified path, attribute, or file does not exist.
.It Bq Er EOPNOTSUPP
The file system does not support extended attributes.
.It Bq Er EPERM
The calling user is not permitted to change extended attributes.
.El
.Sh SEE ALSO
.Xr extattr_delete_file 2 ,
.Xr extattr_get_file 2 ,
.Xr extattr_list_file 2 ,
.Xr extattr_set_file 2 ,
.Xr extattrctl 8
.Sh HISTORY
The
.Fn extattrctl
system call was imported from
.Fx 5.0
in
.Nx 3.0 .