1.\"-
2.\" Copyright (c) 2001 Chris D. Faulhaber
3.\" All rights reserved.
4.\"
5.\" Redistribution and use in source and binary forms, with or without
6.\" modification, are permitted provided that the following conditions
7.\" are met:
8.\" 1. Redistributions of source code must retain the above copyright
9.\"    notice, this list of conditions and the following disclaimer.
10.\" 2. Redistributions in binary form must reproduce the above copyright
11.\"    notice, this list of conditions and the following disclaimer in the
12.\"    documentation and/or other materials provided with the distribution.
13.\"
14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17.\" ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24.\" SUCH DAMAGE.
25.\"
26.Dd March 13, 2001
27.Dt ACL_GET_QUALIFIER 3
28.Os
29.Sh NAME
30.Nm acl_get_qualifier
31.Nd retrieve the qualifier from an ACL entry
32.Sh LIBRARY
33.Lb libc
34.Sh SYNOPSIS
35.In sys/types.h
36.In sys/acl.h
37.Ft void *
38.Fn acl_get_qualifier "acl_entry_t entry_d"
39.Sh DESCRIPTION
40The
41.Fn acl_get_qualifier
42function
43is a POSIX.1e call that retrieves the qualifier of the tag for
44the ACL entry indicated by the argument
45.Fa entry_d
46into working storage and returns a pointer to that storage.
47.Pp
48If the value of the tag type in the ACL entry referred to by
49.Fa entry_d
50is
51.Dv ACL_USER ,
52then the value returned by
53.Fn acl_get_qualifier
54will be a pointer to type
55.Vt uid_t .
56.Pp
57If the value of the tag type in
58the ACL entry referred to by
59.Fa entry_d
60is
61.Dv ACL_GROUP ,
62then the value returned by
63.Fn acl_get_qualifier
64will be a pointer to type
65.Vt gid_t .
66.Pp
67If the value of the tag type in the ACL entry referred to by
68.Fa entry_d
69is
70.Dv ACL_UNDEFINED_TAG , ACL_USER_OBJ , ACL_GROUP_OBJ ,
71.Dv ACL_OTHER , ACL_MASK ,
72or an implementation-defined value for which a qualifier
73is not supported, then
74.Fn acl_get_qualifier
75will return a value of
76.Vt ( void * ) Ns Dv NULL
77and the function will fail.
78.Pp
79This function may cause memory to be allocated.
80The caller should
81free any releasable memory, when the new qualifier is no longer
82required, by calling
83.Fn acl_free
84with
85.Vt void *
86as the argument.
87.Sh RETURN VALUES
88The
89.Fn acl_get_qualifier
90function returns a pointer to the allocated storage if successful;
91otherwise a
92.Dv NULL
93pointer is returned and the global variable
94.Va errno
95is set to indicate the error.
96.Sh ERRORS
97The
98.Fn acl_get_qualifier
99fails if:
100.Bl -tag -width Er
101.It Bq Er EINVAL
102Argument
103.Fa entry_d
104does not point to a valid descriptor for an ACL entry.
105The
106value of the tag type in the ACL entry referenced by argument
107.Fa entry_d
108is not
109.Dv ACL_USER
110or
111.Dv ACL_GROUP .
112.It Bq Er ENOMEM
113The value to be returned requires more memory than is allowed
114by the hardware or system-imposed memory management constraints.
115.El
116.Sh SEE ALSO
117.Xr acl 3 ,
118.Xr acl_create_entry 3 ,
119.Xr acl_free 3 ,
120.Xr acl_get_entry 3 ,
121.Xr acl_get_tag_type 3 ,
122.Xr acl_set_qualifier 3 ,
123.Xr acl_set_tag_type 3 ,
124.Xr posix1e 3
125.Sh STANDARDS
126POSIX.1e is described in IEEE POSIX.1e draft 17.
127.Sh HISTORY
128POSIX.1e support was introduced in
129.Fx 4.0 .
130The
131.Fn acl_get_qualifier
132function was added in
133.Fx 5.0 .
134.Sh AUTHORS
135The
136.Fn acl_get_qualifier
137function was written by
138.An Chris D. Faulhaber Aq Mt jedgar@fxp.org .
139