man/man3/acl_copy_ext.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_COPY_EXT 3
  26 .Os "Linux ACL"
  27 .Sh NAME
  28 .Nm acl_copy_ext
  29 .Nd copy an ACL from internal to external representation
  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 ssize_t
  36 .Fn acl_copy_ext "void *buf_p" "acl_t acl" "ssize_t size"
  37 .Sh DESCRIPTION
  38 The
  39 .Fn acl_copy_ext
  40 function copies the ACL pointed to by
  41 .Va acl
  42 from system-managed space to the user managed space pointed to by
  43 .Va buf_p .
  44 The
  45 .Va size
  46 parameter represents the size in bytes of the buffer pointed to by
  47 .Va buf_p .
  48 The format of the ACL placed in the buffer pointed to by
  49 .Va buf_p
  50 is a contiguous, persistent data item, the format of which is unspecified.
  51 It is the responsibility of the invoker to allocate an area large enough
  52 to hold the copied ACL. The size of the exportable, contiguous, persistent
  53 form of the ACL may be obtained by invoking the
  54 .Fn acl_size
  55 function.
  56 .Pp
  57 Any ACL entry descriptors that refer to an entry in the ACL referenced by
  58 .Va acl
  59 continue to refer to those entries. Any existing ACL pointers that refer
  60 to the ACL referenced by
  61 .Va acl
  62 continue to refer to the ACL.
  63 .Sh RETURN VALUE
  64 Upon success, this function returns the number of bytes placed in the buffer pointed to by
  65 .Va buf_p .
  66 On error, a value of
  67 .Li (ssize_t)-1
  68 is returned and
  69 .Va errno
  70 is set appropriately.
  71 .Sh ERRORS
  72 If any of the following conditions occur, the
  73 .Fn acl_copy_ext
  74 function returns a value of
  75 .Li (ssize_t)-1
  76 and sets
  77 .Va errno
  78 to the corresponding value:
  79 .Bl -tag -width Er
  80 .It Bq Er EINVAL
  81 The
  82 .Va size
  83 parameter is zero or negative.
  84 .Pp
  85 The argument
  86 .Va acl
  87 is not a valid pointer to an ACL.
  88 .Pp
  89 The ACL referenced by
  90 .Va acl
  91 contains one or more improperly formed ACL entries, or for some other
  92 reason cannot be translated into the external form of an ACL.
  93 .It Bq Er ERANGE
  94 The
  95 .Va size
  96 parameter is greater than zero but smaller than the length of the contiguous, persistent form of the ACL.
  97 .El
  98 .Sh STANDARDS
  99 IEEE Std 1003.1e draft 17 (\(lqPOSIX.1e\(rq, abandoned)
 100 .Sh SEE ALSO
 101 .Xr acl_copy_int 3 ,
 102 .Xr acl_size 3 ,
 103 .Xr acl 5
 104 .Sh AUTHOR
 105 Derived from the FreeBSD manual pages written by
 106 .An "Robert N M Watson" Aq rwatson@FreeBSD.org ,
 107 and adapted for Linux by
 108 .An "Andreas Gruenbacher" Aq a.gruenbacher@bestbits.at .