lib/libposix1e/acl_valid.3

   1 .\"-
   2 .\" Copyright (c) 2000 Robert N. M. Watson
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD: src/lib/libposix1e/acl_valid.3,v 1.2.2.5 2001/12/20 16:27:06 ru Exp $
  27 .\"
  28 .Dd January 28, 2000
  29 .Dt ACL_VALID 3
  30 .Os
  31 .Sh NAME
  32 .Nm acl_valid ,
  33 .Nm acl_valid_fd_np ,
  34 .Nm acl_valid_file_np
  35 .Nd validate an ACL
  36 .Sh LIBRARY
  37 .Lb libposix1e
  38 .Sh SYNOPSIS
  39 .In sys/types.h
  40 .In sys/acl.h
  41 .Ft int
  42 .Fn acl_valid "acl_t acl"
  43 .Ft int
  44 .Fn acl_valid_fd_np "int fd" "acl_type_t type" "acl_t acl"
  45 .Ft int
  46 .Fn acl_valid_file_np "const char *path_p" "acl_type_t type" "acl_t acl"
  47 .Sh DESCRIPTION
  48 These functions check that the ACL referred to by the argument
  49 .Va acl
  50 is valid.  The POSIX.1e routine,
  51 .Fn acl_valid ,
  52 checks this validity only with POSIX.1e ACL semantics, and irrespective
  53 of the context in which the ACL is to be used.  The non-portable forms,
  54 .Fn acl_valid_fd_np
  55 and
  56 .Fn acl_valid_file_np ,
  57 allow an ACL to be checked in the context of a specific acl type,
  58 .Va type ,
  59 and file system object.  In environments where additional ACL types are
  60 supported than just POSIX.1e, this makes more sense.
  61 .Pp
  62 For POSIX.1e semantics, the checks include:
  63 .Bd -literal -offset indent
  64 The three required entries (ACL_USER_OBJ, ACL_GROUP_OBJ,
  65 and ACL_OTHER) shall exist exactly once in the ACL.  If
  66 the ACL contains any ACL_USER, ACL_GROUP, or any other
  67 implementation-defined entries in the file group class
  68 then one ACL_MASK entry shall also be required.  The ACL
  69 shall contain at most on ACL_MASK entry.
  70 .Pp
  71 The qualifier field shall be unique among all entries of
  72 the same POSIX.1e ACL facility defined tag type.  The
  73 tag type field shall contain valid values including any
  74 implementation-defined values.  Validation of the values
  75 of the qualifier field is implementation-defined.
  76 .Ed
  77 .Pp
  78 The POSIX.1e
  79 .Fn acl_valid
  80 function may reorder the ACL for the purposes of verification; the
  81 non-portable validation functions will not.
  82 .Sh IMPLEMENTATION NOTES
  83 .Fx Ns 's
  84 support for POSIX.1e interfaces and features is still under
  85 development at this time.
  86 .Sh RETURN VALUES
  87 .Rv -std
  88 .Sh ERRORS
  89 If any of the following conditions occur, these functions shall return
  90 -1 and set
  91 .Va errno
  92 to the corresponding value:
  93 .Bl -tag -width Er
  94 .It Bq Er EACCES
  95 Search permission is denied for a component of the path prefix, or the
  96 object exists and the process does not have appropriate access rights.
  97 .It Bq Er EBADF
  98 The
  99 .Va fd
 100 argument is not a valid file descriptor.
 101 .It Bq Er EINVAL
 102 Argument
 103 .Va acl
 104 does not point to a valid ACL.
 105 .Pp
 106 One or more of the required ACL entries is not present in
 107 .Va acl .
 108 .Pp
 109 The ACL contains entries that are not unique.
 110 .Pp
 111 The file system rejects the ACL based on fs-specific semantics issues.
 112 .It Bq Er ENAMETOOLONG
 113 A component of a pathname exceeded 255 characters, or an
 114 entire path name exceeded 1023 characters.
 115 .It Bq Er ENOENT
 116 The named object does not exist, or the
 117 .Va path_p
 118 argument points to an empty string.
 119 .It Bq Er ENOMEM
 120 Insufficient memory available to fulfill request.
 121 .It Bq Er EOPNOTSUPP
 122 The file system does not support ACL retrieval.
 123 .El
 124 .Sh SEE ALSO
 125 .Xr acl 3 ,
 126 .Xr acl_get 3 ,
 127 .Xr acl_init 3 ,
 128 .Xr acl_set 3 ,
 129 .Xr posix1e 3
 130 .Sh STANDARDS
 131 POSIX.1e is described in IEEE POSIX.1e draft 17.  Discussion
 132 of the draft continues on the cross-platform POSIX.1e implementation
 133 mailing list.  To join this list, see the
 134 .Fx
 135 POSIX.1e implementation
 136 page for more information.
 137 .Sh HISTORY
 138 POSIX.1e support was introduced in
 139 .Fx 4.0 ,
 140 and development continues.
 141 .Sh AUTHORS
 142 .An Robert N M Watson
 143 .Sh BUGS
 144 These features are not yet fully implemented.  In particular, the shipped
 145 version of UFS/FFS does not support storage of additional security labels,
 146 and so is unable to (easily) provide support for most of these features.