posix1e/acl_copy_ext.3

   1 .Dd February 3, 2011
   2 .Dt ACL_COPY_EXT 3
   3 .Sh NAME
   4 .Nm acl_copy_ext ,
   5 .Nm acl_copy_ext_native ,
   6 .Nm acl_copy_int ,
   7 .Nm acl_copy_int_native,
   8 .Nm acl_size
   9 .Nd convert an ACL to and from an external representation
  10 .Sh SYNOPSIS
  11 .In sys/types.h
  12 .In sys/acl.h
  13 .Ft ssize_t
  14 .Fo acl_copy_ext
  15 .Fa "void *buf"
  16 .Fa "acl_t acl"
  17 .Fa "ssize_t size"
  18 .Fc
  19 .Ft ssize_t
  20 .Fo acl_copy_ext_native
  21 .Fa "void *buf"
  22 .Fa "acl_t acl"
  23 .Fa "ssize_t size"
  24 .Fc
  25 .Ft acl_t
  26 .Fo acl_copy_int
  27 .Fa "const void *buf"
  28 .Fc
  29 .Ft acl_t
  30 .Fo acl_copy_int_native
  31 .Fa "const void *buf"
  32 .Fc
  33 .Ft ssize_t
  34 .Fo acl_size
  35 .Fa "acl_t acl"
  36 .Fc
  37 .Sh DESCRIPTION
  38 The
  39 .Fn acl_copy_ext
  40 and
  41 .Fn acl_copy_ext_native
  42 functions convert the ACL given by the argument
  43 .Fa acl
  44 into a binary external representation that can be saved to a file,
  45 passed to another program, etc.
  46 This external representation is written to the buffer pointed to by the argument
  47 .Fa buf ,
  48 which is assumed to have at least the number of contiguous bytes passed in the
  49 .Fa size
  50 argument.
  51 The number of bytes actually written is returned.
  52 .Pp
  53 The
  54 .Fn acl_copy_ext
  55 function writes data in big-endian byte-order, and so is portable across
  56 machines with different byte-order.
  57 To the contrary, the
  58 .Fn acl_copy_ext_native
  59 function uses the machine's native byte-order, and so is only portable to
  60 machines of like byte-order.
  61 .Pp
  62 The
  63 .Fn acl_copy_int
  64 and
  65 .Fn acl_copy_int_native
  66 functions do the reverse conversion; the ACL represented by the external
  67 representation passed in the argument
  68 .Fa buf ,
  69 is returned.
  70 The
  71 .Fn acl_copy_int
  72 function expects an external representation in big-endian byte-order (as
  73 returned by
  74 .Fn acl_copy_ext ) ,
  75 while
  76 .Fn acl_copy_int_native
  77 expects an external representation in native byte-order (as returned by
  78 .Fn acl_copy_ext_native ) .
  79 .Pp
  80 The
  81 .Fn acl_size
  82 function returns the corresponding external representation size, in bytes, for
  83 the given ACL passed in the argument
  84 .Fa acl .
  85 This size can be used to allocate sufficient memory for the buffer in
  86 subsequent calls to
  87 .Fn acl_copy_ext
  88 and
  89 .Fn acl_copy_ext_native .
  90 .Sh RETURN VALUES
  91 Upon successful completion, the
  92 .Fn acl_copy_ext
  93 and
  94 .Fn acl_copy_ext_native
  95 functions shall return the number of bytes actually written to the buffer.
  96 Otherwise, a value of
  97 .Va -1
  98 shall be returned and
  99 .Va errno
 100 shall be set to indicate the error.
 101 .Pp
 102 Upon successful completion, the
 103 .Fn acl_copy_int
 104 and
 105 .Fn acl_copy_int_native
 106 functions shall return the ACL represented by the external representation
 107 passed in the buffer.
 108 Otherwise, a value of
 109 .Va (acl_t)NULL
 110 shall be returned and
 111 .Va errno
 112 shall be set to indicate the error.
 113 .Pp
 114 Upon successful completion, the
 115 .Fn acl_size
 116 function shall return the size of the external representation.
 117 Otherwise, a value of
 118 .Va -1
 119 shall be returned and
 120 .Va errno
 121 shall be set to indicate the error.
 122 .Sh ERRORS
 123 The
 124 .Fn acl_copy_ext
 125 and
 126 .Fn acl_copy_ext_native
 127 functions fail if:
 128 .Bl -tag -width Er
 129 .It Bq Er EINVAL
 130 Argument
 131 .Fa acl
 132 does not point to a valid ACL.
 133 .It Bq Er ERANGE
 134 The given buffer is too small to contain the converted external representation.
 135 .El
 136 .Pp
 137 The
 138 .Fn acl_copy_int
 139 and
 140 .Fn acl_copy_int_native
 141 functions fail if:
 142 .Bl -tag -width Er
 143 .It Bq Er EINVAL
 144 The buffer does not contain a valid external representation.
 145 .El
 146 .Pp
 147 The
 148 .Fn acl_size
 149 function fails if:
 150 .Bl -tag -width Er
 151 .It Bq Er EINVAL
 152 Argument
 153 .Fa acl
 154 does not point to a valid ACL.
 155 .El
 156 .Sh NOTE
 157 While the external representation may use pre-existing data structures,
 158 no assumptions on the internal structure should be made.
 159 .Pp
 160 The
 161 .Xr acl_to_text 3
 162 and
 163 .Xr acl_from_text 3
 164 functions also convert to and from a different external representation,
 165 a human-readable string.
 166 Neither of these representations are cross-platform, lacking a cross-platform
 167 standard.
 168 .Sh SEE ALSO
 169 .Xr acl 3 ,
 170 .Xr acl_from_text 3 ,
 171 .Xr acl_to_text 3
 172 .Sh AUTHORS
 173 .An Michael Smith
 174 .An Robert N M Watson