ACL_COPY_EXT(3) Library Functions Manual ACL_COPY_EXT(3)

acl_copy_ext, acl_copy_ext_native, acl_copy_int, acl_copy_int_native, acl_size — convert an ACL to and from an external representation

#include <sys/types.h>
#include <sys/acl.h>

ssize_t
acl_copy_ext(void *buf, acl_t acl, ssize_t size);

ssize_t
acl_copy_ext_native(void *buf, acl_t acl, ssize_t size);

acl_t
acl_copy_int(const void *buf);

acl_t
acl_copy_int_native(const void *buf);

ssize_t
acl_size(acl_t acl);

The () and () functions convert the ACL given by the argument acl into a binary external representation that can be saved to a file, passed to another program, etc. This external representation is written to the buffer pointed to by the argument buf, which is assumed to have at least the number of contiguous bytes passed in the size argument. The number of bytes actually written is returned.

The () function writes data in big-endian byte-order, and so is portable across machines with different byte-order. To the contrary, the () function uses the machine's native byte-order, and so is only portable to machines of like byte-order.

The () and () functions do the reverse conversion; the ACL represented by the external representation passed in the argument buf, is returned. The acl_copy_int() function expects an external representation in big-endian byte-order (as returned by acl_copy_ext()), while acl_copy_int_native() expects an external representation in native byte-order (as returned by acl_copy_ext_native()).

The () function returns the corresponding external representation size, in bytes, for the given ACL passed in the argument acl. This size can be used to allocate sufficient memory for the buffer in subsequent calls to acl_copy_ext() and acl_copy_ext_native().

Upon successful completion, the acl_copy_ext() and acl_copy_ext_native() functions shall return the number of bytes actually written to the buffer. Otherwise, a value of -1 shall be returned and errno shall be set to indicate the error.

Upon successful completion, the acl_copy_int() and acl_copy_int_native() functions shall return the ACL represented by the external representation passed in the buffer. Otherwise, a value of (acl_t)NULL shall be returned and errno shall be set to indicate the error.

Upon successful completion, the acl_size() function shall return the size of the external representation. Otherwise, a value of -1 shall be returned and errno shall be set to indicate the error.

The acl_copy_ext() and acl_copy_ext_native() functions fail if:

[]
Argument acl does not point to a valid ACL.
[]
The given buffer is too small to contain the converted external representation.

The acl_copy_int() and acl_copy_int_native() functions fail if:

[]
The buffer does not contain a valid external representation.

The acl_size() function fails if:

[]
Argument acl does not point to a valid ACL.

While the external representation may use pre-existing data structures, no assumptions on the internal structure should be made.

The acl_to_text(3) and acl_from_text(3) functions also convert to and from a different external representation, a human-readable string. Neither of these representations are cross-platform, lacking a cross-platform standard.

acl(3), acl_from_text(3), acl_to_text(3)

Michael Smith
Robert N M Watson

February 3, 2011