manual/acl/original/man3/acl_create_entry.3

   1 .\" Access Control Lists manual pages
   2 .\"
   3 .\" (C) 2002 Andreas Gruenbacher, <a.gruenbacher@bestbits.at>
   4 .\"
   5 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
   6 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
   7 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
   8 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
   9 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  10 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  11 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  12 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  13 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  14 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  15 .\" SUCH DAMAGE.
  16 .\"
  17 .Dd March 23, 2002
  18 .Dt ACL_CREATE_ENTRY 3
  19 .Os "Linux ACL"
  20 .Sh NAME
  21 .Nm acl_create_entry
  22 .Nd create a new ACL entry
  23 .Sh LIBRARY
  24 Linux Access Control Lists library (libacl, \-lacl).
  25 .Sh SYNOPSIS
  26 .In sys/types.h
  27 .In sys/acl.h
  28 .Ft int
  29 .Fn acl_create_entry "acl_t *acl_p" "acl_entry_t *entry_p"
  30 .Sh DESCRIPTION
  31 The
  32 .Fn acl_create_entry
  33 function creates a new ACL entry in the ACL pointed to by the contents of the pointer argument
  34 .Va acl_p .
  35 On success, the function returns a descriptor for the new
  36 ACL entry via
  37 .Va entry_p .
  38 .Pp
  39 This function may cause memory to be allocated.  The caller should free any
  40 releasable memory, when the new ACL is no longer required, by calling
  41 .Xr acl_free 3
  42 with
  43 .\" <AG>
  44 .\" 1003.1e says:
  45 .\" .Va (void*)acl_t
  46 .\" this makes no sense, so:
  47 .Va (void*)*acl_p
  48 .\" </AG>
  49 as an argument.
  50 If the ACL working storage cannot be increased in the current location,
  51 then the working storage for the ACL pointed to by
  52 .Va acl_p
  53 may be relocated and the previous working storage is released. A pointer to
  54 the new working storage is returned via
  55 .Va acl_p .
  56 .Pp
  57 The components of the new ACL entry are initialized in the following ways: the
  58 ACL tag type component contains ACL_UNDEFINED_TAG, the qualifier component
  59 contains ACL_UNDEFINED_ID, and the set of permissions has no permissions
  60 enabled. Any existing ACL entry descriptors that refer to entries in the ACL
  61 continue to refer to those entries.
  62 .\" <AG>
  63 .\" Conflict between requirements:
  64 .\" (a) ACL may be relocated,
  65 .\" (b) all pointers remain valid.
  66 .\" </AG>
  67 .Sh RETURN VALUE
  68 .Rv -std acl_create_entry
  69 .Sh ERRORS
  70 If any of the following conditions occur, the
  71 .Fn acl_create_entry
  72 function returns
  73 .Li -1
  74 and sets
  75 .Va errno
  76 to the corresponding value:
  77 .Bl -tag -width Er
  78 .It Bq Er EINVAL
  79 The argument
  80 .Va acl_p
  81 is not a valid pointer to an ACL.
  82 .It Bq Er ENOMEM
  83 The ACL working storage requires more memory than is allowed by the hardware or system-imposed memory management constraints.
  84 .El
  85 .Sh STANDARDS
  86 IEEE Std 1003.1e draft 17 (\(lqPOSIX.1e\(rq, abandoned)
  87 .Sh SEE ALSO
  88 .Xr acl_init 3 ,
  89 .Xr acl_delete_entry 3 ,
  90 .Xr acl_free 3 ,
  91 .Xr acl_create_entry 3 ,
  92 .Xr acl 5
  93 .Sh AUTHOR
  94 Derived from the FreeBSD manual pages written by
  95 .An "Robert N M Watson" Aq rwatson@FreeBSD.org ,
  96 and adapted for Linux by
  97 .An "Andreas Gruenbacher" Aq a.gruenbacher@bestbits.at .