man/man3/acl_set_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_SET_FILE 3
  26 .Os "Linux ACL"
  27 .Sh NAME
  28 .Nm acl_set_file
  29 .Nd set 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 int
  36 .Fn acl_set_file "const char *path_p" "acl_type_t type" "acl_t acl"
  37 .Sh DESCRIPTION
  38 The
  39 .Fn acl_set_file
  40 function associates an access ACL with a file or directory, or
  41 associates a default ACL with a directory. The pathname for the file or
  42 directory is pointed to by the argument
  43 .Va path_p .
  44 .Pp
  45 The effective user ID of the process must match the owner of the file or
  46 directory or the process must have the CAP_FOWNER capability for the
  47 request to succeed.
  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
  52 with
  53 .Va path_p
  54 is being set. If the
  55 .Va type
  56 parameter is ACL_TYPE_ACCESS, the access ACL of
  57 .Va path_p
  58 shall be set. If the
  59 .Va type
  60 parameter is ACL_TYPE_DEFAULT, the default ACL of
  61 .Va path_p
  62 shall be set. If the argument
  63 .Va type
  64 specifies a type of ACL that cannot be associated with
  65 .Va path_p ,
  66 then the function fails.
  67 .Pp
  68 The
  69 .Va acl
  70 parameter must reference a valid ACL according to the rules described on the
  71 .Xr acl_valid 3
  72 manual page if the
  73 .Va type
  74 parameter is ACL_TYPE_ACCESS, and must either reference a valid ACL or an ACL with zero ACL entries if the
  75 .Va type
  76 parameter is ACL_TYPE_DEFAULT. If the
  77 .Va acl
  78 parameter references an empty ACL, then the
  79 .Fn acl_set_file
  80 function removes any default ACL associated with the directory referred to
  81 by the
  82 .Va path_p
  83 parameter.
  84 .Sh RETURN VALUE
  85 .Rv -std acl_set_file
  86 .Sh ERRORS
  87 If any of the following conditions occur, the
  88 .Fn acl_set_file
  89 function returns
  90 .Li -1
  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 acl
 106 does not point to a valid ACL.
 107 .Pp
 108 The ACL has more entries than the file referred to by
 109 .Va path_p
 110 can obtain.
 111 .Pp
 112 The
 113 .Va type
 114 parameter is not ACL_TYPE_ACCESS or ACL_TYPE_DEFAULT.
 115 .Pp
 116 The
 117 .Va type
 118 parameter is ACL_TYPE_DEFAULT, but the file referred to by
 119 .Va path_p
 120 is not a directory.
 121 .It Bq Er ENAMETOOLONG
 122 The length of the argument
 123 .Va path_p
 124 is too long.
 125 .It Bq Er ENOENT
 126 The named object does not exist or the argument
 127 .Va path_p
 128 points to an empty string.
 129 .It Bq Er ENOSPC
 130 The directory or file system that would contain the new ACL cannot be extended or the file system is out of file allocation resources.
 131 .It Bq Er ENOTDIR
 132 A component of the path prefix is not a directory.
 133 .It Bq Er ENOTSUP
 134 The file identified by
 135 .Va path_p
 136 cannot be associated with the ACL because the file system on which the file
 137 is located does not support this.
 138 .It Bq Er EPERM
 139 The process does not have appropriate privilege to perform the operation to set the ACL.
 140 .It Bq Er EROFS
 141 This function requires modification of a file system which is currently read-only.
 142 .El
 143 .Sh STANDARDS
 144 IEEE Std 1003.1e draft 17 (\(lqPOSIX.1e\(rq, abandoned)
 145 .Pp
 146 The behavior of
 147 .Fn acl_set_file
 148 when the
 149 .Va acl
 150 parameter refers to an empty ACL and the
 151 .Va type
 152 parameter is ACL_TYPE_DEFAULT is an extension in the Linux implementation, in order that all values returned by
 153 .Fn acl_get_file
 154 can be passed to
 155 .Fn acl_set_file .
 156 The POSIX.1e function for removing a default ACL is
 157 .Fn acl_delete_def_file .
 158 .Sh SEE ALSO
 159 .Xr acl_delete_def_file 3 ,
 160 .Xr acl_get_file 3 ,
 161 .Xr acl_set_fd 3 ,
 162 .Xr acl_valid 3 ,
 163 .Xr acl 5
 164 .Sh AUTHOR
 165 Derived from the FreeBSD manual pages written by
 166 .An "Robert N M Watson" Aq rwatson@FreeBSD.org ,
 167 and adapted for Linux by
 168 .An "Andreas Gruenbacher" Aq a.gruenbacher@bestbits.at .