manual/acl/original/man3/acl_get_entry.3

   1 .\" Access Control Lists manual pages
   2 .\"
   3 .\" (C) 2002 Andreas Gruenbacher, <a.gruenbacher@bestbits.at>
   4 .\"
   5 .\" This is free documentation; you can redistribute it and/or
   6 .\" modify it under the terms of the GNU General Public License as
   7 .\" published by the Free Software Foundation; either version 2 of
   8 .\" the License, or (at your option) any later version.
   9 .\"
  10 .\" The GNU General Public License's references to "object code"
  11 .\" and "executables" are to be interpreted as the output of any
  12 .\" document formatting or typesetting system, including
  13 .\" intermediate and printed output.
  14 .\"
  15 .\" This manual is distributed in the hope that it will be useful,
  16 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  17 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18 .\" GNU General Public License for more details.
  19 .\"
  20 .\" You should have received a copy of the GNU General Public
  21 .\" License along with this manual.  If not, see
  22 .\" <http://www.gnu.org/licenses/>.
  23 .\"
  24 .Dd March 23, 2002
  25 .Dt ACL_GET_ENTRY 3
  26 .Os "Linux ACL"
  27 .Sh NAME
  28 .Nm acl_get_entry
  29 .Nd get an ACL entry
  30 .Sh LIBRARY
  31 Linux Access Control Lists library (libacl, \-lacl).
  32 .Sh SYNOPSIS
  33 .In sys/types.h
  34 .In sys/acl.h
  35 .Ft int
  36 .Fn acl_get_entry "acl_t acl" "int entry_id" "acl_entry_t *entry_p"
  37 .Sh DESCRIPTION
  38 The
  39 .Fn acl_get_entry
  40 function obtains a descriptor for an ACL entry as specified by
  41 .Va entry_id
  42 within the ACL indicated by the argument
  43 .Va acl .
  44 If the value of
  45 .Va entry_id
  46 is ACL_FIRST_ENTRY, then the function returns in
  47 .Va entry_p
  48 a descriptor for the first ACL entry within
  49 .Va acl .
  50 If the value of
  51 .Va entry_id
  52 is ACL_NEXT_ENTRY, then the function returns in
  53 .Va entry_p
  54 a descriptor for the next ACL entry within
  55 .Va acl .
  56 .Pp
  57 If a call is made to
  58 .Fn acl_get_entry
  59 with
  60 .Va entry_id
  61 set to ACL_NEXT_ENTRY when there has not been either an initial
  62 successful call to
  63 .Fn acl_get_entry ,
  64 or a previous successful call to
  65 .Fn acl_get_entry
  66 following a call to
  67 .Fn acl_calc_mask ,
  68 .Fn acl_copy_int ,
  69 .Fn acl_create_entry ,
  70 .Fn acl_delete_entry ,
  71 .Fn acl_dup ,
  72 .Fn acl_from_text ,
  73 .Fn acl_get_fd ,
  74 .Fn acl_get_file ,
  75 .Fn acl_set_fd ,
  76 .Fn acl_set_file ,
  77 or
  78 .Fn acl_valid ,
  79 then the effect is unspecified.
  80 .Pp
  81 Calls to
  82 .Fn acl_get_entry
  83 do not modify any ACL entries. Subsequent operations using the returned
  84 ACL entry descriptor operate on the ACL entry within the ACL in working
  85 storage. The order of all existing entries in the ACL remains unchanged.
  86 Any existing ACL entry descriptors that refer to entries within the ACL
  87 continue to refer to those entries. Any existing ACL pointers that refer
  88 to the ACL referred to by
  89 .Va acl
  90 continue to refer to the ACL.
  91 .Sh RETURN VALUE
  92 If the function successfully obtains an ACL entry, the function returns a
  93 value of
  94 .Li 1 .
  95 If the ACL has no ACL entries, the function returns the value
  96 .Li 0 .
  97 If the value of
  98 .Va entry_id
  99 is ACL_NEXT_ENTRY and the last ACL entry in the ACL has already been
 100 returned by a previous call to
 101 .Fn acl_get_entry ,
 102 the function returns the value
 103 .Li 0
 104 until a successful call with an
 105 .Va entry_id
 106 of ACL_FIRST_ENTRY is made. Otherwise, the value
 107 .Li -1
 108 is returned and
 109 .Va errno
 110 is set to indicate the error.
 111 .Sh ERRORS
 112 If any of the following conditions occur, the
 113 .Fn acl_get_entry
 114 function returns
 115 .Li -1
 116 and sets
 117 .Va errno
 118 to the corresponding value:
 119 .Bl -tag -width Er
 120 .It Bq Er EINVAL
 121 The argument
 122 .Va acl_p
 123 is not a valid pointer to an ACL.
 124 .Pp
 125 The argument
 126 .Va entry_id
 127 is neither ACL_NEXT_ENTRY nor ACL_FIRST_ENTRY.
 128 .El
 129 .Sh STANDARDS
 130 IEEE Std 1003.1e draft 17 (\(lqPOSIX.1e\(rq, abandoned)
 131 .Sh SEE ALSO
 132 .Xr acl_calc_mask 3 ,
 133 .Xr acl_create_entry 3 ,
 134 .Xr acl_copy_entry 3 ,
 135 .Xr acl_delete_entry 3 ,
 136 .Xr acl_get_file 3 ,
 137 .Xr acl 5
 138 .Sh AUTHOR
 139 Derived from the FreeBSD manual pages written by
 140 .An "Robert N M Watson" Aq rwatson@FreeBSD.org ,
 141 and adapted for Linux by
 142 .An "Andreas Gruenbacher" Aq a.gruenbacher@bestbits.at .