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 December 29, 2002
  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 .Sh IMPLEMENTATION NOTES
  95 .Fx Ns 's
  96 support for POSIX.1e interfaces and features is still under
  97 development at this time.
  98 .Sh RETURN VALUES
  99 Upon successful completion, the function shall return a pointer to the ACL
 100 that was retrieved.
 101 Otherwise, a value of
 102 .Va (acl_t)NULL
 103 shall be returned, and
 104 .Va errno
 105 shall be set to indicate the error.
 106 .Sh ERRORS
 107 If any of the following conditions occur, the
 108 .Fn acl_get_fd
 109 function shall return a value of
 110 .Va (acl_t)NULL
 111 and set
 112 .Va errno
 113 to the corresponding value:
 114 .Bl -tag -width Er
 115 .It Bq Er EACCES
 116 Search permission is denied for a component of the path prefix, or the
 117 object exists and the process does not have appropriate access rights.
 118 .It Bq Er EBADF
 119 The
 120 .Va fd
 121 argument is not a valid file descriptor.
 122 .It Bq Er EINVAL
 123 The ACL type passed is invalid for this file object.
 124 .It Bq Er ENAMETOOLONG
 125 A component of a pathname exceeded 255 characters, or an
 126 entire path name exceeded 1023 characters.
 127 .It Bq Er ENOENT
 128 The named object does not exist, or the
 129 .Va path_p
 130 argument points to an empty string.
 131 .It Bq Er ENOMEM
 132 Insufficient memory available to fulfill request.
 133 .It Bq Er EOPNOTSUPP
 134 The file system does not support ACL retrieval.
 135 .El
 136 .Sh SEE ALSO
 137 .Xr acl 3 ,
 138 .Xr acl_free 3 ,
 139 .Xr acl_get 3 ,
 140 .Xr acl_set 3 ,
 141 .Xr posix1e 3
 142 .Sh STANDARDS
 143 POSIX.1e is described in IEEE POSIX.1e draft 17.
 144 Discussion
 145 of the draft continues on the cross-platform POSIX.1e implementation
 146 mailing list.
 147 To join this list, see the
 148 .Fx
 149 POSIX.1e implementation
 150 page for more information.
 151 .Sh HISTORY
 152 POSIX.1e support was introduced in
 153 .Fx 4.0 ,
 154 and development continues.
 155 .Sh AUTHORS
 156 .An Robert N M Watson