xref: /freebsd/lib/libc/posix1e/extattr.3 (revision 2b47b55f69365b54f6d5d700dc2997b5a367734c)
1444a2d61SDima Dorfman.\"
2444a2d61SDima Dorfman.\" Copyright (c) 2001 Dima Dorfman <dd@FreeBSD.org>
3444a2d61SDima Dorfman.\" All rights reserved.
4444a2d61SDima Dorfman.\"
5444a2d61SDima Dorfman.\" Redistribution and use in source and binary forms, with or without
6444a2d61SDima Dorfman.\" modification, are permitted provided that the following conditions
7444a2d61SDima Dorfman.\" are met:
8444a2d61SDima Dorfman.\" 1. Redistributions of source code must retain the above copyright
9444a2d61SDima Dorfman.\"    notice, this list of conditions and the following disclaimer.
10444a2d61SDima Dorfman.\" 2. Redistributions in binary form must reproduce the above copyright
11444a2d61SDima Dorfman.\"    notice, this list of conditions and the following disclaimer in the
12444a2d61SDima Dorfman.\"    documentation and/or other materials provided with the distribution.
13444a2d61SDima Dorfman.\"
14444a2d61SDima Dorfman.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15444a2d61SDima Dorfman.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16444a2d61SDima Dorfman.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17444a2d61SDima Dorfman.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18444a2d61SDima Dorfman.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19444a2d61SDima Dorfman.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20444a2d61SDima Dorfman.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21444a2d61SDima Dorfman.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22444a2d61SDima Dorfman.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23444a2d61SDima Dorfman.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24444a2d61SDima Dorfman.\" SUCH DAMAGE.
25444a2d61SDima Dorfman.\"
26444a2d61SDima Dorfman.\" $FreeBSD$
27444a2d61SDima Dorfman.\"
28444a2d61SDima Dorfman.Dd June 24, 2001
29444a2d61SDima Dorfman.Dt EXTATTR 3
30444a2d61SDima Dorfman.Os
31444a2d61SDima Dorfman.Sh NAME
32444a2d61SDima Dorfman.Nm extattr_namespace_to_string ,
33444a2d61SDima Dorfman.Nm extattr_string_to_namespace
34444a2d61SDima Dorfman.Nd convert an extended attribute namespace identifier to a string and
35444a2d61SDima Dorfmanvice versa
36444a2d61SDima Dorfman.Sh LIBRARY
37444a2d61SDima Dorfman.Lb libutil
38444a2d61SDima Dorfman.Sh SYNOPSIS
39444a2d61SDima Dorfman.Fd #include <sys/extattr.h>
40444a2d61SDima Dorfman.Fd #include <libutil.h>
41444a2d61SDima Dorfman.Ft int
42444a2d61SDima Dorfman.Fn extattr_namespace_to_string "int attrnamespace" "char **string"
43444a2d61SDima Dorfman.Ft int
44444a2d61SDima Dorfman.Fn extattr_string_to_namespace "const char *string" "int *attrnamespace"
45444a2d61SDima Dorfman.Sh DESCRIPTION
46444a2d61SDima DorfmanThe
47444a2d61SDima Dorfman.Fn extattr_namespace_to_string
48444a2d61SDima Dorfmanfunction converts a VFS extended attribute identifier to a human-readable
49444a2d61SDima Dorfmanstring;
50444a2d61SDima Dorfmanthe
51444a2d61SDima Dorfman.Fn extattr_string_to_namespace
52444a2d61SDima Dorfmanfunction undoes the aforementioned operation,
53444a2d61SDima Dorfmanand converts a human-readable string representing a namespace to a
54444a2d61SDima Dorfmannamespace identifier.
55444a2d61SDima DorfmanAlthough a filesystem may implement arbitrary namespaces,
56444a2d61SDima Dorfmanthese functions only support the
57444a2d61SDima Dorfman.Dv EXTATTR_NAMESPACE_USER
58444a2d61SDima Dorfman.Pq Dq user
59444a2d61SDima Dorfmanand
60444a2d61SDima Dorfman.Dv EXTATTR_NAMESPACE_SYSTEM
61444a2d61SDima Dorfman.Pq Dq system
62444a2d61SDima Dorfmannamespaces,
63444a2d61SDima Dorfmanwhich are defined in
64444a2d61SDima Dorfman.Xr extattr 9 .
65444a2d61SDima Dorfman.Pp
66444a2d61SDima DorfmanThese functions are meant to be used in error reporting and other
67444a2d61SDima Dorfmaninteractive tasks.
68444a2d61SDima DorfmanFor example,
69444a2d61SDima Dorfmaninstead of printing the integer identifying an extended attribute in
70444a2d61SDima Dorfmanan error message,
71444a2d61SDima Dorfmana program might use
72444a2d61SDima Dorfman.Fn extattr_namespace_to_string
73444a2d61SDima Dorfmanto obtain a human-readable representation.
74444a2d61SDima DorfmanLikewise,
75444a2d61SDima Dorfmaninstead of requiring a user to enter the integer representing a namespace,
76444a2d61SDima Dorfmanan interactive program might ask for a name and use
77444a2d61SDima Dorfman.Fn extattr_string_to_namespace
78444a2d61SDima Dorfmanto get the desired identifier.
792b47b55fSDima Dorfman.Sh RETURN VALUES
802b47b55fSDima DorfmanIf any of the calls are unsuccessful, the value \-1 is returned
812b47b55fSDima Dorfmanand the global variable
822b47b55fSDima Dorfman.Va errno
832b47b55fSDima Dorfmanis set to indicate the error.
842b47b55fSDima Dorfman.Sh ERRORS
852b47b55fSDima Dorfman.Bl -tag -width Er
862b47b55fSDima Dorfman.It Bq Er EINVAL
872b47b55fSDima DorfmanThe requested namespace could not be identified.
882b47b55fSDima Dorfman.El
89444a2d61SDima Dorfman.Sh SEE ALSO
902b47b55fSDima Dorfman.Xr extattr 2 ,
91444a2d61SDima Dorfman.Xr getextattr 8 ,
92444a2d61SDima Dorfman.Xr setextattr 8 ,
93444a2d61SDima Dorfman.Xr extattr 9
94444a2d61SDima Dorfman.Sh HISTORY
95444a2d61SDima DorfmanExtended attribute support was developed as part of the
96444a2d61SDima Dorfman.Tn TrustedBSD
97444a2d61SDima DorfmanProject, and introduced in
98444a2d61SDima Dorfman.Fx 5.0 .
99444a2d61SDima DorfmanIt was developed to support security extensions requiring additional labels
100444a2d61SDima Dorfmanto be associated with each file or directory.
101