lib/libc/posix1e/acl_get.3

   1 .\"-
   2 .\" Copyright (c) 2000, 2002 Robert N. M. Watson
   3 .\" All rights reserved.
   4 .\"
   5 .\" This software was developed by Robert Watson for the TrustedBSD Project.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\" $FreeBSD$
  29 .\"
  30 .Dd June 25, 2009
  31 .Dt ACL_GET 3
  32 .Os
  33 .Sh NAME
  34 .Nm acl_get_fd ,
  35 .Nm acl_get_fd_np ,
  36 .Nm acl_get_file ,
  37 .Nm acl_get_link_np
  38 .Nd get an ACL for a file
  39 .Sh LIBRARY
  40 .Lb libc
  41 .Sh SYNOPSIS
  42 .In sys/types.h
  43 .In sys/acl.h
  44 .Ft acl_t
  45 .Fn acl_get_fd "int fd"
  46 .Ft acl_t
  47 .Fn acl_get_fd_np "int fd" "acl_type_t type"
  48 .Ft acl_t
  49 .Fn acl_get_file "const char *path_p" "acl_type_t type"
  50 .Ft acl_t
  51 .Fn acl_get_link_np "const char *path_p" "acl_type_t type"
  52 .Sh DESCRIPTION
  53 The
  54 .Fn acl_get_fd ,
  55 .Fn acl_get_file ,
  56 .Fn acl_get_link_np ,
  57 and
  58 .Fn acl_get_fd_np
  59 each allow the retrieval of an ACL from a file.
  60 The
  61 .Fn acl_get_fd
  62 is a POSIX.1e call that allows the retrieval of an ACL of type
  63 ACL_TYPE_ACCESS
  64 from a file descriptor.
  65 The
  66 .Fn acl_get_fd_np
  67 function
  68 is a non-portable form of
  69 .Fn acl_get_fd
  70 that allows the retrieval of any type of ACL from a file descriptor.
  71 The
  72 .Fn acl_get_file
  73 function is a POSIX.1e call that allows the retrieval of a
  74 specified type of ACL from a file by name;
  75 .Fn acl_get_link_np
  76 is a non-portable variation on
  77 .Fn acl_get_file
  78 which does not follow a symlink if the target of the call is a
  79 symlink.
  80 .Pp
  81 These functions may cause memory to be allocated.
  82 The caller should free
  83 any releasable memory, when the new ACL is no longer required, by calling
  84 .Xr acl_free 3
  85 with the
  86 .Va (void *)acl_t
  87 as an argument.
  88 .Pp
  89 The ACL in the working storage is an independent copy of the ACL associated
  90 with the object referred to by
  91 .Va fd .
  92 The ACL in the working storage shall not participate in any access control
  93 decisions.
  94 .Pp
  95 Valid values for the
  96 .Va type
  97 argument are:
  98 .Bl -column -offset 3n "ACL_TYPE_DEFAULT"
  99 .It ACL_TYPE_ACCESS     POSIX.1e access ACL
 100 .It ACL_TYPE_DEFAULT    POSIX.1e default ACL
 101 .It ACL_TYPE_NFS4       NFSv4 ACL
 102 .El
 103 .Pp
 104 The ACL returned will be branded accordingly.
 105 .Sh IMPLEMENTATION NOTES
 106 .Fx Ns 's
 107 support for POSIX.1e interfaces and features is still under
 108 development at this time.
 109 .Sh RETURN VALUES
 110 Upon successful completion, the function shall return a pointer to the ACL
 111 that was retrieved.
 112 Otherwise, a value of
 113 .Va (acl_t)NULL
 114 shall be returned, and
 115 .Va errno
 116 shall be set to indicate the error.
 117 .Sh ERRORS
 118 If any of the following conditions occur, the
 119 .Fn acl_get_fd
 120 function shall return a value of
 121 .Va (acl_t)NULL
 122 and set
 123 .Va errno
 124 to the corresponding value:
 125 .Bl -tag -width Er
 126 .It Bq Er EACCES
 127 Search permission is denied for a component of the path prefix, or the
 128 object exists and the process does not have appropriate access rights.
 129 .It Bq Er EBADF
 130 The
 131 .Va fd
 132 argument is not a valid file descriptor.
 133 .It Bq Er EINVAL
 134 The ACL type passed is invalid for this file object.
 135 .It Bq Er ENAMETOOLONG
 136 A component of a pathname exceeded 255 characters, or an
 137 entire path name exceeded 1023 characters.
 138 .It Bq Er ENOENT
 139 The named object does not exist, or the
 140 .Va path_p
 141 argument points to an empty string.
 142 .It Bq Er ENOMEM
 143 Insufficient memory available to fulfill request.
 144 .It Bq Er EOPNOTSUPP
 145 The file system does not support ACL retrieval.
 146 .El
 147 .Sh SEE ALSO
 148 .Xr acl 3 ,
 149 .Xr acl_free 3 ,
 150 .Xr acl_get 3 ,
 151 .Xr acl_get_brand_np 3 ,
 152 .Xr acl_set 3 ,
 153 .Xr posix1e 3
 154 .Sh STANDARDS
 155 POSIX.1e is described in IEEE POSIX.1e draft 17.
 156 Discussion
 157 of the draft continues on the cross-platform POSIX.1e implementation
 158 mailing list.
 159 To join this list, see the
 160 .Fx
 161 POSIX.1e implementation
 162 page for more information.
 163 .Sh HISTORY
 164 POSIX.1e support was introduced in
 165 .Fx 4.0 ,
 166 and development continues.
 167 .Sh AUTHORS
 168 .An Robert N M Watson