xref: /freebsd/lib/libc/posix1e/acl_get_entry.3 (revision 6990ffd8a95caaba6858ad44ff1b3157d1efba8f)
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 THE AUTHOR OR THE VOICES IN HIS HEAD BE
18.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
19.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
20.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
21.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
22.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
23.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
24.\" POSSIBILITY OF SUCH DAMAGE.
25.\"
26.\" $FreeBSD$
27.\"
28.Dd April 13, 2001
29.Dt ACL_GET_ENTRY 3
30.Os
31.Sh NAME
32.Nm acl_get_entry
33.Nd retrieve an ACL entry from an ACL
34.Sh LIBRARY
35.Lb libc
36.Sh SYNOPSIS
37.Fd #include <sys/types.h>
38.Fd #include <sys/acl.h>
39.Ft void *
40.Fn acl_get_entry "acl_t acl" "int entry_id" "acl_entry_t *entry_p"
41.Sh DESCRIPTION
42.Fn acl_get_entry
43is a POSIX.1e call that retrieves a descriptor for an ACL entry
44specified by the argument
45.Fa entry_d
46within the ACL indicated by the argument
47.Fa acl .
48.Pp
49If the value of
50.Fa entry_id
51is
52.Dv ACL_FIRST_ENTRY ,
53then the function will return in
54.Fa entry_p
55a descriptor for the first ACL entry within
56.Fa acl .
57If a call is made to
58.Fn acl_get_entry
59with
60.Fa entry_id
61set to
62.Dv ACL_NEXT_ENTRY
63when there has not been either an initial successful call to
64.Fn acl_get_entry ,
65or a previous successfull call to
66.Fn acl_create_entry ,
67.Fn acl_delete_entry ,
68.Fn acl_dup ,
69.Fn acl_from_text ,
70.Fn acl_get_fd ,
71.Fn acl_get_file ,
72.Fn acl_set_fd ,
73.Fn acl_set_file ,
74or
75.Fn acl_valid ,
76then the result is unspecified.
77.Sh RETURN VALUES
78If the
79.Fn acl_get_entry
80function successfully obtains an ACL entry, a value of 1 is returned.
81If the ACL has no ACL entries, the
82.Fn acl_get_entry
83returns a value of 0.  If the value of
84.Fa entry_id
85is
86.Dv ACL_NEXT_ENTRY
87and the last ACL entry in the ACL has already been returned by a
88previous call to
89.Fn acl_get_entry ,
90a value of 0 will be returned until a successful call with
91.Fa entry_id
92of
93.Dv ACL_FIRST_ENTRY
94is made.  Otherwise, a value of -1 will be returned and
95the global variable
96.Va errno
97will be set to indicate the error.
98.Sh ERRORS
99The
100.Fn acl_get_entry
101fails if:
102.Bl -tag -width Er
103.It Bq Er EINVAL
104Argument
105.Fa acl
106does not point to a valid ACL.  Argument
107.Fa entry_id
108is neither
109.Dv ACL_FIRST_ENTRY
110nor
111.Dv ACL_NEXT_ENTRY .
112.El
113.Sh SEE ALSO
114.Xr acl 3 ,
115.Xr acl_calc_mask 3 ,
116.Xr acl_create_entry 3 ,
117.Xr acl_delete_entry 3 ,
118.Xr acl_dup 3 ,
119.Xr acl_from_text 3 ,
120.Xr acl_get_fd 3 ,
121.Xr acl_get_file 3 ,
122.Xr acl_init 3 ,
123.Xr acl_set_fd 3 ,
124.Xr acl_set_file 3 ,
125.Xr acl_valid 3 ,
126.Xr posix1e 3
127.Sh STANDARDS
128POSIX.1e is described in IEEE POSIX.1e draft 17.
129.Sh HISTORY
130POSIX.1e support was introduced in
131.Fx 4.0 .
132The
133.Fn acl_get_entry
134function was added in
135.Fx 5.0 .
136.Sh AUTHORS
137The
138.Fn acl_get_entry
139function was written by
140.An Chris D. Faulhaber Aq jedgar@fxp.org .
141