Home | History | Annotate | Line # | Download | only in sys 
 $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
n sys/extattr.h n 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.

p
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

a "/.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 .

p
This programming interface is currently only used by
.Xr extattrctl 8 ,
and is not intended for general use.
.Sh PARAMETERS
l -tag -width indent t Fa path The path to the mount point of the file system.
t Fa cmd The command to execute.
Valid commands are:
l -tag -width indent t Dv UFS_EXTATTR_CMD_ENABLE Enable a specific extended attribute.
t Dv UFS_EXTATTR_CMD_DISABLE Disable a specific extended attribute.
t Dv UFS_EXTATTR_CMD_START Start extended attribute support on the file system.
t Dv UFS_EXTATTR_CMD_STOP Stop extended attribute support on the file system.
.El
t Fa attrname The name of the extended attribute (for relevant commands).
t Fa attrnamespace The attribute namespace, such as
.Dv EXTATTR_NAMESPACE_USER
or
.Dv EXTATTR_NAMESPACE_SYSTEM .
t 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:
d -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:
l -tag -width Bq -offset indent t Bq Er EACCES The calling user does not have permission to access the file
specified.
t Bq Er EINVAL Invalid arguments were provided.
t Bq Er ENOENT The specified path, attribute, or file does not exist.
t Bq Er EOPNOTSUPP The file system does not support extended attributes.
t 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 .