man/man3/acl_get_file.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_FILE 3
  26 .Os "Linux ACL"
  27 .Sh NAME
  28 .Nm acl_get_file
  29 .Nd get an ACL by filename
  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 acl_t
  36 .Fn acl_get_file "const char *path_p" "acl_type_t type"
  37 .Sh DESCRIPTION
  38 The
  39 .Fn acl_get_file
  40 function retrieves the access ACL associated with a file or directory, or the default ACL associated with a directory. The pathname for the file or directory is pointed to by the argument
  41 .Va path_p .
  42 The ACL is placed into working storage and
  43 .Fn acl_get_file
  44 returns a pointer to that storage.
  45 .Pp
  46 In order to read an ACL from an object, a process must have read access to
  47 the object's attributes.
  48 .Pp
  49 The value of the argument
  50 .Va type
  51 is used to indicate whether the access ACL or the default ACL associated with
  52 .Va path_p
  53 is returned. If
  54 .Va type
  55 is ACL_TYPE_ACCESS, the access ACL of
  56 .Va path_p
  57 is returned. If
  58 .Va type
  59 is ACL_TYPE_DEFAULT, the default ACL of
  60 .Va path_p
  61 is returned. If
  62 .Va type
  63 is ACL_TYPE_DEFAULT and no default ACL is associated with the directory
  64 .Va path_p ,
  65 then an ACL containing zero ACL entries is returned. If
  66 .Va type
  67 specifies a type of ACL that cannot be associated with
  68 .Va path_p ,
  69 then the function fails.
  70 .Pp
  71 This function may cause memory to be allocated.  The caller should free any
  72 releasable memory, when the new ACL is no longer required, by calling
  73 .Xr acl_free 3
  74 with the
  75 .Va (void*)acl_t
  76 returned by
  77 .Fn acl_get_file
  78 as an argument.
  79 .Sh RETURN VALUE
  80 On success, this function returns a pointer to the
  81 working storage.  On error, a value of
  82 .Li (acl_t)NULL
  83 is returned, and
  84 .Va errno
  85 is set appropriately.
  86 .Sh ERRORS
  87 If any of the following conditions occur, the
  88 .Fn acl_get_file
  89 function returns a value of
  90 .Li (acl_t)NULL
  91 and sets
  92 .Va errno
  93 to the corresponding value:
  94 .Bl -tag -width Er
  95 .It Bq Er EACCES
  96 Search permission is denied for a component of the path prefix or the
  97 object exists and the process does not have appropriate access rights.
  98 .Pp
  99 Argument
 100 .Va type
 101 specifies a type of ACL that cannot be associated with
 102 .Va path_p .
 103 .It Bq Er EINVAL
 104 The argument
 105 .Va type
 106 is not ACL_TYPE_ACCESS or ACL_TYPE_DEFAULT.
 107 .It Bq Er ENAMETOOLONG
 108 The length of the argument
 109 .Va path_p
 110 is too long.
 111 .It Bq Er ENOENT
 112 The named object does not exist or the argument
 113 .Va path_p
 114 points to an empty string.
 115 .It Bq Er ENOMEM
 116 The ACL working storage requires more memory than is allowed by the hardware or system-imposed memory management constraints.
 117 .It Bq Er ENOTDIR
 118 A component of the path prefix is not a directory.
 119 .It Bq Er ENOTSUP
 120 The file system on which the file identified by
 121 .Va path_p
 122 is located does not support ACLs, or ACLs are disabled.
 123 .El
 124 .Sh STANDARDS
 125 IEEE Std 1003.1e draft 17 (\(lqPOSIX.1e\(rq, abandoned)
 126 .Sh SEE ALSO
 127 .Xr acl_free 3 ,
 128 .Xr acl_get_entry 3 ,
 129 .Xr acl_get_fd 3 ,
 130 .Xr acl_set_file 3 ,
 131 .Xr acl 5
 132 .Sh AUTHOR
 133 Derived from the FreeBSD manual pages written by
 134 .An "Robert N M Watson" Aq rwatson@FreeBSD.org ,
 135 and adapted for Linux by
 136 .An "Andreas Gruenbacher" Aq a.gruenbacher@bestbits.at .