ACL_COPY_EXT(3)

✨ ACL_COPY_EXT(3) ✨

okay bestie, we're doing a deep dive on acl_copy_ext from the Linux Access Control Lists library (that's libacl, link it with -lacl 💅). this is a Library Functions Manual situation and honestly? it's giving ✨pointer energy✨. let's go 🦋

🌸 NAME 🌸

acl_copy_ext — copy an ACL from internal to external representation

💜 LIBRARY 💜

Linux Access Control Lists library (libacl, -lacl).

🎀 SYNOPSIS 🎀

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

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

✨ DESCRIPTION ✨

so here's the tea 🍓: acl_copy_ext() takes the ACL that acl points to and copies it from system-managed space into the user-managed space that buf_p points at. it's literally a glow-up transformation from internal to external form.

the size parameter is the size in bytes of the buffer that buf_p points to, bestie. don't be sloppy with it.

now the format of the ACL that lands in buf_p? it's a contiguous, persistent data item — and the format itself is unspecified. iykyk. it's not for you to poke at, it's for you to hand back to the library later. 👑

⚠️ it is your responsibility (yes, the invoker's, that's you) to allocate an area big enough to hold the copied ACL. don't come crying to me if your buffer is too small, the library will simply not have a good time.

want to know how big that exportable, contiguous, persistent form actually is? call acl_size() first, babe. that's the vibe check before the main character moment. 💅

one more thing that's lowkey important: any ACL entry descriptors that refer to an entry in the ACL referenced by acl continue to refer to those entries. and any existing ACL pointers that refer to the ACL referenced by acl continue to refer to the ACL. nothing gets detached, nothing gets moved, we're just copying. no cap. 🫶

💖 RETURN VALUE 💖

• on success, it returns the number of bytes placed in the buffer pointed to by buf_p ✨
• on error, a value of (ssize_t)-1 is returned and errno is set appropriately 😭

💀 ERRORS 💀

if any of these conditions occur, acl_copy_ext() returns a value of (ssize_t)-1 and sets errno to the corresponding value:

• [EINVAL] — a whole bundle of yikes, actually:
  • the size parameter is zero or negative 🙈
  • the argument acl is not a valid pointer to an ACL 💀
  • the ACL referenced by acl contains one or more improperly formed ACL entries, or for some other reason cannot be translated into the external form of an ACL
• [ERANGE] — the size parameter is greater than zero but smaller than the length of the contiguous, persistent form of the ACL. so close yet so far, bestie 😭

⭐ STANDARDS ⭐

IEEE Std 1003.1e draft 17 (“POSIX.1e”, abandoned)

yes it says abandoned. we don't talk about that. 💀

🌈 SEE ALSO 🌈

• acl_copy_int(3)
• acl_size(3)
• acl(5)

👑 AUTHOR 👑

Derived from the FreeBSD manual pages written by Robert N M Watson <rwatson@FreeBSD.org>, and adapted for Linux by Andreas Gruenbacher <andreas.gruenbacher@gmail.com>.

and that's the whole page, bestie 🎀 this one came from the Linux ACL manual, dated March 23, 2002. iconic, historic, periodt. go forth and copy your ACLs responsibly 💖✨🦋