lib/libc/posix1e/acl_get_qualifier.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 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
  40 The
  41 .Fn acl_get_qualifier
  42 function
  43 is a POSIX.1e call that retrieves the qualifier of the tag for
  44 the ACL entry indicated by the argument
  45 .Fa entry_d
  46 into working storage and returns a pointer to that storage.
  47 .Pp
  48 If the value of the tag type in the ACL entry referred to by
  49 .Fa entry_d
  50 is
  51 .Dv ACL_USER ,
  52 then the value returned by
  53 .Fn acl_get_qualifier
  54 will be a pointer to type
  55 .Vt uid_t .
  56 .Pp
  57 If the value of the tag type in
  58 the ACL entry referred to by
  59 .Fa entry_d
  60 is
  61 .Dv ACL_GROUP ,
  62 then the value returned by
  63 .Fn acl_get_qualifier
  64 will be a pointer to type
  65 .Vt gid_t .
  66 .Pp
  67 If the value of the tag type in the ACL entry referred to by
  68 .Fa entry_d
  69 is
  70 .Dv ACL_UNDEFINED_TAG , ACL_USER_OBJ , ACL_GROUP_OBJ ,
  71 .Dv ACL_OTHER , ACL_MASK ,
  72 or an implementation-defined value for which a qualifier
  73 is not supported, then
  74 .Fn acl_get_qualifier
  75 will return a value of
  76 .Vt ( void * ) Ns Dv NULL
  77 and the function will fail.
  78 .Pp
  79 This function may cause memory to be allocated.
  80 The caller should
  81 free any releasable memory, when the new qualifier is no longer
  82 required, by calling
  83 .Fn acl_free
  84 with
  85 .Vt void *
  86 as the argument.
  87 .Sh RETURN VALUES
  88 The
  89 .Fn acl_get_qualifier
  90 function returns a pointer to the allocated storage if successful;
  91 otherwise a
  92 .Dv NULL
  93 pointer is returned and the global variable
  94 .Va errno
  95 is set to indicate the error.
  96 .Sh ERRORS
  97 The
  98 .Fn acl_get_qualifier
  99 fails if:
 100 .Bl -tag -width Er
 101 .It Bq Er EINVAL
 102 Argument
 103 .Fa entry_d
 104 does not point to a valid descriptor for an ACL entry.
 105 The
 106 value of the tag type in the ACL entry referenced by argument
 107 .Fa entry_d
 108 is not
 109 .Dv ACL_USER
 110 or
 111 .Dv ACL_GROUP .
 112 .It Bq Er ENOMEM
 113 The value to be returned requires more memory than is allowed
 114 by 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
 126 POSIX.1e is described in IEEE POSIX.1e draft 17.
 127 .Sh HISTORY
 128 POSIX.1e support was introduced in
 129 .Fx 4.0 .
 130 The
 131 .Fn acl_get_qualifier
 132 function was added in
 133 .Fx 5.0 .
 134 .Sh AUTHORS
 135 The
 136 .Fn acl_get_qualifier
 137 function was written by
 138 .An Chris D. Faulhaber Aq Mt jedgar@fxp.org .