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: src/lib/libc/posix1e/acl_get.3,v 1.17 2003/02/23 01:43:45 ru Exp $
  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.  The caller should free
  82 any releasable memory, when the new ACL is no longer required, by calling
  83 .Xr acl_free 3
  84 with the
  85 .Va (void *)acl_t
  86 as an argument.
  87 .Pp
  88 The ACL in the working storage is an independent copy of the ACL associated
  89 with the object referred to by
  90 .Va fd .
  91 The ACL in the working storage shall not participate in any access control
  92 decisions.
  93 .Sh RETURN VALUES
  94 Upon successful completion, the function shall return a pointer to the ACL
  95 that was retrieved.  Otherwise, a value of
  96 .Va (acl_t)NULL
  97 shall be returned, and
  98 .Va errno
  99 shall be set to indicate the error.
 100 .Sh ERRORS
 101 If any of the following conditions occur, the
 102 .Fn acl_get_fd
 103 function shall return a value of
 104 .Va (acl_t)NULL
 105 and set
 106 .Va errno
 107 to the corresponding value:
 108 .Bl -tag -width Er
 109 .It Bq Er EACCES
 110 Search permission is denied for a component of the path prefix, or the
 111 object exists and the process does not have appropriate access rights.
 112 .It Bq Er EBADF
 113 The
 114 .Va fd
 115 argument is not a valid file descriptor.
 116 .It Bq Er EINVAL
 117 The ACL type passed is invalid for this file object.
 118 .It Bq Er ENAMETOOLONG
 119 A component of a pathname exceeded 255 characters, or an
 120 entire path name exceeded 1023 characters.
 121 .It Bq Er ENOENT
 122 The named object does not exist, or the
 123 .Va path_p
 124 argument points to an empty string.
 125 .It Bq Er ENOMEM
 126 Insufficient memory available to fulfill request.
 127 .It Bq Er EOPNOTSUPP
 128 The file system does not support ACL retrieval.
 129 .El
 130 .Sh SEE ALSO
 131 .Xr acl 3 ,
 132 .Xr acl_free 3 ,
 133 .Xr acl_get 3 ,
 134 .Xr acl_set 3 ,
 135 .Xr posix1e 3
 136 .Sh STANDARDS
 137 POSIX.1e is described in IEEE POSIX.1e draft 17.
 138 .Sh AUTHORS
 139 .An Michael Smith
 140 .An Robert N M Watson