ACL_FROM_TEXT(3)

✨ ACL_FROM_TEXT(3) ✨

okay bestie, we're in the Library Functions Manual today and the page is called ACL_FROM_TEXT(3) but the function we're actually talking about is acl_to_text — yes it's giving "the filename doesn't match the vibe" but we move 💅

🌸 NAME 🌸

acl_to_text — convert an ACL to text

📚 LIBRARY 📚

Linux Access Control Lists library (libacl, -lacl). that's the whole lib, she's small but she's powerful 🫶

✨ SYNOPSIS ✨

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

char *
acl_to_text(acl_t acl, ssize_t *len_p);

💖 DESCRIPTION 💖

so acl_to_text() takes the ACL that the argument acl points at and translates it into a NULL terminated character string. that's the whole job. she's a translator, not a surgeon.

if the pointer len_p is not NULL, then the function drops the length of the string (and NOT including the NULL terminator, okay, read that again) into the location that len_p points to. like she's handing you the receipt too 🧾

the format of the text string that comes back from acl_to_text() is the long text form defined in acl(5). and lowkey the best part: the ACL referred to by acl is not changed. she does not touch your stuff. queen behavior, no cap 👑

this function allocates whatever memory it needs to hold the string, and returns a pointer to that string. so the caller — that's you bestie — should free any releasable memory when the new string isn't needed anymore, by calling acl_free(3) with the (void*)char returned by acl_to_text() as an argument.

not me handing you a string and then making you clean it up 😭 that's just how it is though. free your memory fr fr.

🔥 RETURN VALUE 🔥

on success, this function returns a pointer to the long text form of the ACL. slay.

on error, a value of (char *)NULL is returned, and errno is set appropriately. 💀

😭 ERRORS 😭

if any of the following conditions occur, the acl_to_text() function returns a value of (char *)NULL and sets errno to the corresponding value:

• [EINVAL] — the argument acl is not a valid pointer to an ACL.
  • also: the ACL referenced by acl contains one or more improperly formed ACL entries, or for some other reason cannot be translated into a text form of an ACL. like she tried, she really did, but the input was messy 🙈
• [ENOMEM] — the character string to be returned requires more memory than is allowed by the hardware or system-imposed memory management constraints. the string was simply too iconic for your RAM 🫠

🌈 STANDARDS 🌈

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

abandoned. the standard got ghosted 👻 rip bozo, but the function lives on

👑 SEE ALSO 👑

acl_free(3), acl_from_text(3), acl_to_any_text(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 page, bestie! this one came from the Linux ACL manual and it's dated March 23, 2002 — yeah she's an elder but she's still serving 💜 go free your strings, drink water, and stan acl_to_text. mwah 🦋✨