posix1e/acl_get_entry.3

   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: src/lib/libc/posix1e/acl_get_entry.3,v 1.6 2002/12/18 12:45:09 ru Exp $
  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 .In sys/types.h
  38 .In sys/acl.h
  39 .Ft int
  40 .Fn acl_get_entry "acl_t acl" "int entry_id" "acl_entry_t *entry_p"
  41 .Sh DESCRIPTION
  42 The
  43 .Fn acl_get_entry
  44 function
  45 is a POSIX.1e call that retrieves a descriptor for an ACL entry
  46 specified by the argument
  47 .Fa entry_d
  48 within the ACL indicated by the argument
  49 .Fa acl .
  50 .Pp
  51 If the value of
  52 .Fa entry_id
  53 is
  54 .Dv ACL_FIRST_ENTRY ,
  55 then the function will return in
  56 .Fa entry_p
  57 a descriptor for the first ACL entry within
  58 .Fa acl .
  59 If a call is made to
  60 .Fn acl_get_entry
  61 with
  62 .Fa entry_id
  63 set to
  64 .Dv ACL_NEXT_ENTRY
  65 when there has not been either an initial successful call to
  66 .Fn acl_get_entry ,
  67 or a previous successfull call to
  68 .Fn acl_create_entry ,
  69 .Fn acl_delete_entry ,
  70 .Fn acl_dup ,
  71 .Fn acl_from_text ,
  72 .Fn acl_get_fd ,
  73 .Fn acl_get_file ,
  74 .Fn acl_set_fd ,
  75 .Fn acl_set_file ,
  76 or
  77 .Fn acl_valid ,
  78 then the result is unspecified.
  79 .Pp
  80 The caller may also set
  81 .Fa entry_id
  82 to the index of the desired entry within the ACL.  This is a non-portable
  83 extension.  A subsequent call with
  84 .Fa entry_id
  85 set to
  86 .Dv ACL_NEXT_ENTRY
  87 will return the entry following the previously nominated entry and so forth.
  88 .Sh RETURN VALUES
  89 If the
  90 .Fn acl_get_entry
  91 function successfully obtains an ACL entry, a value of 1 is returned.
  92 If the ACL has no ACL entries, the
  93 .Fn acl_get_entry
  94 returns a value of 0.  If the value of
  95 .Fa entry_id
  96 is
  97 .Dv ACL_NEXT_ENTRY
  98 and the last ACL entry in the ACL has already been returned by a
  99 previous call to
 100 .Fn acl_get_entry ,
 101 a value of 0 will be returned until a successful call with
 102 .Fa entry_id
 103 of
 104 .Dv ACL_FIRST_ENTRY
 105 is made.  Otherwise, a value of -1 will be returned and
 106 the global variable
 107 .Va errno
 108 will be set to indicate the error.
 109 .Sh ERRORS
 110 The
 111 .Fn acl_get_entry
 112 fails if:
 113 .Bl -tag -width Er
 114 .It Bq Er EINVAL
 115 Argument
 116 .Fa acl
 117 does not point to a valid ACL.  Argument
 118 .Fa entry_id
 119 is neither
 120 .Dv ACL_FIRST_ENTRY ,
 121 .Dv ACL_NEXT_ENTRY
 122 or a valid entry index.
 123 .El
 124 .Sh SEE ALSO
 125 .Xr acl 3 ,
 126 .Xr acl_calc_mask 3 ,
 127 .Xr acl_create_entry 3 ,
 128 .Xr acl_delete_entry 3 ,
 129 .Xr acl_dup 3 ,
 130 .Xr acl_from_text 3 ,
 131 .Xr acl_get_fd 3 ,
 132 .Xr acl_get_file 3 ,
 133 .Xr acl_init 3 ,
 134 .Xr acl_set_fd 3 ,
 135 .Xr acl_set_file 3 ,
 136 .Xr acl_valid 3 ,
 137 .Xr posix1e 3
 138 .Sh STANDARDS
 139 POSIX.1e is described in IEEE POSIX.1e draft 17.
 140 .Sh AUTHORS
 141 .An Michael Smith
 142 .An Chris D. Faulhaber