ACL_CHECK(3)

💖 ACL_CHECK(3) — the check-your-ACL-for-validity girlie 💖

okay so bestie, we're in the Library Functions Manual section, and today's main character is acl_check — she checks an ACL for validity. yes she's that girl. 🎀

✨ NAME ✨

acl_check — check an ACL for validity. literally her whole job. she ate. 💅

📚 LIBRARY 📚

Linux Access Control Lists library (libacl, -lacl). that's the one, bestie, don't link the wrong one or it's giving undefined reference energy 😭

🌸 SYNOPSIS 🌸

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

int
acl_check(acl_t acl, int *last);

💜 DESCRIPTION 💜

The acl_check() function checks the ACL referred to by the argument acl for validity. vibe check time, no cap. 🔥

So here's the tea, and it's a strict tea:

The three required entries ACL_USER_OBJ, ACL_GROUP_OBJ, and ACL_OTHER must exist exactly once in the ACL. exactly. once. not zero, not two. periodt.

If the ACL contains any ACL_USER or ACL_GROUP entries, then an ACL_MASK entry is also required. like, you brought friends so now you need a chaperone. 🫶

The ACL may contain at most one ACL_MASK entry. one. that's the limit. don't push it.

The user identifiers must be unique among all entries of type ACL_USER. The group identifiers must be unique among all entries of type ACL_GROUP. no duplicates allowed, bestie, we don't do clones here 🦋

If the ACL referred to by acl is invalid, acl_check() returns a positive error code that indicates which type of error was detected. so she's not just saying "no" — she's saying why, and that's growth. The following symbolic error codes are defined:

• ACL_MULTI_ERROR — The ACL contains multiple entries that have a tag type that may occur at most once. like girl, we said once. 💀
• ACL_DUPLICATE_ERROR — The ACL contains multiple ACL_USER entries with the same user ID, or multiple ACL_GROUP entries with the same group ID. twin behavior, but make it illegal 🙈
• ACL_MISS_ERROR — A required entry is missing. she's not here and we're all pretending it's fine 😭
• ACL_ENTRY_ERROR — The ACL contains an invalid entry tag type. that tag is not on the guest list, babe.

The acl_error() function can be used to translate error codes to text messages. so if you want the error to actually talk to you, that's your girl. 🧚

In addition, if the pointer last is not NULL, acl_check() assigns the number of the ACL entry at which the error was detected to the value pointed to by last. so she'll literally point at the culprit. icon behavior. 👑

Entries are numbered starting with zero, in the order in which they would be returned by the acl_get_entry() function. zero-indexed, as all correct things are ✨

⭐ RETURN VALUE ⭐

If successful, the acl_check() function returns 0 if the ACL referred to by acl is valid, and a positive error code if the ACL is invalid. yes bestie, "successful" here still includes "the ACL was bad and I'm telling you about it" — that's a return value, not a failure. 💖

Otherwise, a value of -1 is returned and the global variable errno is set to indicate the error. that's the real bad path. 😭

🚨 ERRORS 🚨

If any of the following conditions occur, the acl_check() function returns -1 and sets errno to the corresponding value:

• [EINVAL] — The argument acl is not a valid pointer to an ACL. you handed her garbage, she's not gonna pretend it's a salad. 🥗💀

fr fr: this one is the "you passed me a nonsense pointer" error. no ACL, no service.

📏 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). so like... it's Linux-exclusive and the ancestor spec got abandoned. iconic of the 90s honestly 🫠

👀 SEE ALSO 👀

• acl_valid(3)
• acl(5)

go read those too, bestie, knowledge is free and she's giving it away 💜

✍️ AUTHOR ✍️

Written by Andreas Gruenbacher <andreas.gruenbacher@gmail.com>. thank you king, we appreciate you 🫶

and that's the whole page, babes — this was Linux ACL, March 23, 2002, so yes she's a vintage queen and she's still valid (unlike some ACLs 😌). stay valid, stay unique, stay exactly-once. mwah 💋✨🌸