ACL_TO_ANY_TEXT(3)

✨ ACL_TO_ANY_TEXT(3) ✨

okay bestie, so this is a page from the Library Functions Manual, and it's about acl_to_any_text — the little function that turns an ACL into text. yes, the whole thing. 💖 let's get into it.

🌸 NAME 🌸

acl_to_any_text — convert an ACL to text

📚 LIBRARY 📚

Linux Access Control Lists library (libacl, -lacl). that's the vibe, that's the whole library. 🫶

🎀 SYNOPSIS 🎀

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

char *
acl_to_any_text(acl_t acl, const char *prefix, char separator,
    int options);

💅 DESCRIPTION 💅

so the acl_to_any_text() function takes the ACL that acl points at and translates it into a NULL terminated character string. iconic behavior fr fr. this string is built out of the ACL entries sitting inside acl, in the entry text format that acl(5) describes. entries get separated from each other by the separator character. and if prefix is not (const char *)NULL, then every single entry gets that character string stuck on the front of it. slay. ✨

if options is 0, the ACL entries get converted using the entry tag type keywords user, group, mask, and other. user IDs and group IDs of ACL entries that carry those qualifiers get converted to their matching names — and if an identifier has no corresponding name, you just get a decimal number string instead. no cap. the ACL text representation contains no additional comments. periodt.

but you can also bitwise-combine these options to change up the result:

• TEXT_ABBREVIATE — instead of spelling out the full tag type keywords, you get single letter abbreviations. the abbreviation for user is u, the abbreviation for group is g, the abbreviation for mask is m, and the abbreviation for other is o. short queen energy. 💅
• TEXT_NUMERIC_IDS — user IDs and group IDs get included as decimal numbers instead of names.
• TEXT_SOME_EFFECTIVE — a comment containing the effective permissions of the ACL entry gets included after ACL entries that have permissions which are ineffective because they're masked by an ACL_MASK entry. the ACL entry and the comment are separated by a tab character.
• TEXT_ALL_EFFECTIVE — a comment containing the effective permissions of the ACL entry gets included after all ACL entries that are affected by an ACL_MASK entry. and it's included even if the permissions in the ACL entry equal the effective permissions. again, the ACL entry and the comment are separated by a tab character.
• TEXT_SMART_INDENT — this one only makes sense used in combination with the TEXT_SOME_EFFECTIVE or TEXT_ALL_EFFECTIVE option. it increases the number of tab characters inserted between the ACL entry and the comment so that the comment lines up with the fourth tab stop position. a tab width of 8 characters is assumed. aesthetic alignment, we love to see it. 🌈

the ACL that acl refers to is not changed. promise. 🫶

this function allocates whatever memory it needs to hold the string and returns a pointer to the string. when you're done with that new string, you the caller should free any releasable memory by calling acl_free() with the (void*)char returned by acl_to_any_text() as the argument. don't be a memory leaker bestie. 😭

⭐ RETURN VALUE ⭐

on success, this function returns a pointer to the text representation of the ACL. on error, you get a value of (char *)NULL, and errno gets set appropriately. rude but fair.

💀 ERRORS 💀

if any of these conditions happen, the acl_to_any_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.

and also: the ACL referenced by acl contains one or more improperly formed ACL entries, or for some other reason cannot be translated into the text form of an ACL. 💀

• [ENOMEM] — the character string to be returned requires more memory than is allowed by the hardware or system-imposed memory management constraints. no room, no vibes.

📜 STANDARDS 📜

this is a non-portable, Linux specific extension to the ACL manipulation functions defined in IEEE Std 1003.1e draft 17 ("POSIX.1e", abandoned). yes, abandoned — iconic, honestly. 🫶

👀 SEE ALSO 👀

acl_from_text(3), acl_to_text(3), acl_free(3), acl(5)

👑 AUTHOR 👑

written by Andreas Gruenbacher <andreas.gruenbacher@gmail.com>. thank you for your service king. 🫡

and that's the whole page bestie — Linux ACL, page ACL_TO_ANY_TEXT(3), dated March 25, 2002. old but gold, fr fr. go forth and convert those ACLs. 💖✨🎀