1.\" $NetBSD: extattrctl.2,v 1.7 2025/03/11 14:13:45 wiz Exp $
2.\" Copyright (c) 2025 The NetBSD Foundation, Inc.
3.\" All rights reserved.
4.\"
5.\" This code is derived from software contributed to The NetBSD Foundation
6.\" by Christos Zoulas.
7.\"
8.\" Redistribution and use in source and binary forms, with or without
9.\" modification, are permitted provided that the following conditions
10.\" are met:
11.\" 1. Redistributions of source code must retain the above copyright
12.\"    notice, this list of conditions and the following disclaimer.
13.\" 2. Redistributions in binary form must reproduce the above copyright
14.\"    notice, this list of conditions and the following disclaimer in the
15.\"    documentation and/or other materials provided with the distribution.
16.\"
17.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
18.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
19.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
20.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
21.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
22.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
23.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
24.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
25.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
26.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
27.\" POSSIBILITY OF SUCH DAMAGE.
28.\"
29.Dd March 9, 2025
30.Dt EXTATTRCTL 2
31.Os
32.Sh NAME
33.Nm extattrctl
34.Nd control extended attributes on a UFS1 file system
35.Sh SYNOPSIS
36.In sys/extattr.h
37.In ufs/ufs/extattr.h
38.Ft int
39.Fn extattrctl "const char *path" "int cmd" "const char *filename" "int attrnamespace" "const char *attrname"
40.Sh DESCRIPTION
41The
42.Fn extattrctl
43system call provides low-level control over extended attributes on a UFS1
44file system.
45It allows enabling, disabling, and managing extended attributes.
46.Pp
47Since there was no provision in the UFS1 file system for attributes,
48they are stored as regular files and directories in the file system under the
49.Pa "/.attribute"
50directory.
51By convention, there are usually two directories directly under it,
52separating two namespaces:
53.Dq user
54and
55.Dq system .
56Under these, there are named attributes that can be created and
57managed using
58.Xr extattrctl 8 .
59.Pp
60This programming interface is currently only used by
61.Xr extattrctl 8 ,
62and is not intended for general use.
63.Sh PARAMETERS
64.Bl -tag -width indent
65.It Fa path
66The path to the mount point of the file system.
67.It Fa cmd
68The command to execute.
69Valid commands are:
70.Bl -tag -width indent
71.It Dv UFS_EXTATTR_CMD_ENABLE
72Enable a specific extended attribute.
73.It Dv UFS_EXTATTR_CMD_DISABLE
74Disable a specific extended attribute.
75.It Dv UFS_EXTATTR_CMD_START
76Start extended attribute support on the file system.
77.It Dv UFS_EXTATTR_CMD_STOP
78Stop extended attribute support on the file system.
79.El
80.It Fa attrname
81The name of the extended attribute (for relevant commands).
82.It Fa attrnamespace
83The attribute namespace, such as
84.Dv EXTATTR_NAMESPACE_USER
85or
86.Dv EXTATTR_NAMESPACE_SYSTEM .
87.It Fa filename
88The path to a backing file for extended attribute storage
89(if required by the command).
90.El
91.Sh RETURN VALUES
92.Rv -std extattrctl
93.Sh EXAMPLES
94Enable an attribute on a file system:
95.Bd -literal -offset indent
96#include <sys/extattr.h>
97#include <ufs/ufs/extattr.h>
98
99if (extattrctl("/home", UFS_EXTATTR_CMD_ENABLE,
100    "/.attribute/user/comment",
101    EXTATTR_NAMESPACE_USER, "comment") == -1)
102	err(EXIT_FAILURE, "extattrctl");
103.Ed
104.Sh ERRORS
105The
106.Fn extattrctl
107system call may fail with the following errors:
108.Bl -tag -width Bq -offset indent
109.It Bq Er EACCES
110The calling user does not have permission to access the file
111specified.
112.It Bq Er EINVAL
113Invalid arguments were provided.
114.It Bq Er ENOENT
115The specified path, attribute, or file does not exist.
116.It Bq Er EOPNOTSUPP
117The file system does not support extended attributes.
118.It Bq Er EPERM
119The calling user is not permitted to change extended attributes.
120.El
121.Sh SEE ALSO
122.Xr extattr_delete_file 2 ,
123.Xr extattr_get_file 2 ,
124.Xr extattr_list_file 2 ,
125.Xr extattr_set_file 2 ,
126.Xr extattrctl 8
127.Sh HISTORY
128The
129.Fn extattrctl
130system call was imported from
131.Fx 5.0
132in
133.Nx 3.0 .
134