man/man3/acl_get_qualifier.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_QUALIFIER 3
  26 .Os "Linux ACL"
  27 .Sh NAME
  28 .Nm acl_get_qualifier
  29 .Nd retrieve the qualifier from 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 void *
  36 .Fn acl_get_qualifier "acl_entry_t entry_d"
  37 .Sh DESCRIPTION
  38 The
  39 .Fn acl_get_qualifier
  40 function retrieves the qualifier from the ACL entry indicated by the argument
  41 .Va entry_d
  42 into working storage and returns a pointer to that storage.
  43 .Pp
  44 If the value of the tag type in the ACL entry referred to by
  45 .Va entry_d
  46 is ACL_USER, then the value returned by
  47 .Fn acl_get_qualifier
  48 is a pointer to type
  49 .Va uid_t .
  50 If the value of the tag type in the ACL entry referred to by
  51 .Va entry_d
  52 is ACL_GROUP, then the value returned by
  53 .Fn acl_get_qualifier
  54 is a pointer to type
  55 .Va gid_t .
  56 If the tag type in the ACL entry referred to by
  57 .Va entry_d
  58 is a tag type for which a qualifier is not supported,
  59 .Fn acl_get_qualifier
  60 returns a value of
  61 .Li (void *)NULL
  62 and the function fails. Subsequent operations using the returned pointer
  63 operate on an independent copy of the qualifier in working storage, and will not change the qualifier of the ACL entry.
  64 .Pp
  65 This function may cause memory to be allocated. The caller should free any
  66 releasable memory, when the new qualifier is no longer required, by calling
  67 .Fn acl_free
  68 with the
  69 .Va void *
  70 value returned by
  71 .Fn acl_get_qualifier
  72 as an argument.
  73 .Pp
  74 The argument
  75 .Va entry_d
  76 and any other ACL entry descriptors that refer to entries within the ACL
  77 containing the entry referred to by
  78 .Va entry_d
  79 continue to refer to those entries. The order of all existing
  80 entries in the ACL containing the entry referred to by
  81 .Va entry_d
  82 remains unchanged.
  83 .Sh RETURN VALUE
  84 On success, the function returns a pointer to the tag qualifier that was retrieved into ACL working storage. On error, a value of
  85 .Li (void *)NULL
  86 is returned and
  87 .Va errno
  88 is set appropriately.
  89 .Sh ERRORS
  90 If any of the following conditions occur, the
  91 .Fn acl_get_qualifier
  92 function returns
  93 .Li (void *)NULL
  94 and sets
  95 .Va errno
  96 to the corresponding value:
  97 .Bl -tag -width Er
  98 .It Bq Er EINVAL
  99 The argument
 100 .Va entry_d
 101 is not a valid descriptor for an ACL entry.
 102 .Pp
 103 The value of the tag type in the ACL entry referenced by the argument
 104 .Va entry_d
 105 is neither ACL_USER nor ACL_GROUP.
 106 .It Bq Er ENOMEM
 107 The value to be returned requires more memory than is allowed by the hardware or system-imposed memory management constraints.
 108 .El
 109 .Sh STANDARDS
 110 IEEE Std 1003.1e draft 17 (\(lqPOSIX.1e\(rq, abandoned)
 111 .Sh SEE ALSO
 112 .Xr acl_create_entry 3 ,
 113 .Xr acl_free 3 ,
 114 .Xr acl_get_entry 3 ,
 115 .Xr acl_get_permset 3 ,
 116 .Xr acl_get_tag_type 3 ,
 117 .Xr acl_set_permset 3 ,
 118 .Xr acl_set_qualifier 3 ,
 119 .Xr acl_set_tag_type 3 ,
 120 .Xr acl 5
 121 .Sh AUTHOR
 122 Derived from the FreeBSD manual pages written by
 123 .An "Robert N M Watson" Aq rwatson@FreeBSD.org ,
 124 and adapted for Linux by
 125 .An "Andreas Gruenbacher" Aq a.gruenbacher@bestbits.at .