The ACL API uses three opaque handle types. You never directly access or allocate their internals — you only hold pointers to them returned by API functions.

The ACL API is large. Here is every commonly used function grouped by purpose.

#include <stdio.h>
#include <stdlib.h>
#include <sys/acl.h>
#include <pwd.h>
#include <grp.h>

/* Helper: print permissions as rwx string */
static void print_perms(acl_permset_t ps) {
    printf("%c", acl_get_perm(ps, ACL_READ)    ? 'r' : '-');
    printf("%c", acl_get_perm(ps, ACL_WRITE)   ? 'w' : '-');
    printf("%c", acl_get_perm(ps, ACL_EXECUTE) ? 'x' : '-');
}

int main(int argc, char *argv[]) {
    if (argc != 2) { fprintf(stderr, "Usage: %s <file>\n", argv[0]); return 1; }

    acl_t acl = acl_get_file(argv[1], ACL_TYPE_ACCESS);
    if (!acl) { perror("acl_get_file"); return 1; }

    acl_entry_t entry;
    int eid;
    printf("%-15s %-10s %s\n", "Tag", "Qualifier", "Perms");
    printf("%-15s %-10s %s\n", "---", "---------", "-----");

    for (eid = ACL_FIRST_ENTRY; acl_get_entry(acl, eid, &entry) == 1;
         eid = ACL_NEXT_ENTRY) {

        acl_tag_t tag;
        acl_get_tag_type(entry, &tag);

        const char *tag_name = (tag == ACL_USER_OBJ)  ? "user_obj"  :
                               (tag == ACL_USER)       ? "user"      :
                               (tag == ACL_GROUP_OBJ)  ? "group_obj" :
                               (tag == ACL_GROUP)      ? "group"     :
                               (tag == ACL_MASK)       ? "mask"      :
                               (tag == ACL_OTHER)      ? "other"     : "???";
        printf("%-15s ", tag_name);

        if (tag == ACL_USER) {
            uid_t *uidp = acl_get_qualifier(entry);
            struct passwd *pw = getpwuid(*uidp);
            printf("%-10s ", pw ? pw->pw_name : "unknown");
            acl_free(uidp);
        } else if (tag == ACL_GROUP) {
            gid_t *gidp = acl_get_qualifier(entry);
            struct group *gr = getgrgid(*gidp);
            printf("%-10s ", gr ? gr->gr_name : "unknown");
            acl_free(gidp);
        } else {
            printf("%-10s ", "-");
        }

        acl_permset_t ps;
        acl_get_permset(entry, &ps);
        print_perms(ps);
        printf("\n");
    }

    acl_free(acl);
    return 0;
}
/* Compile: gcc print_acl.c -lacl -o print_acl */

#include <stdio.h>
#include <stdlib.h>
#include <sys/acl.h>
#include <pwd.h>

/* Sets ACL on a file: owner=rw, alice=r, group=r, mask=rw, other=--- */
int main(int argc, char *argv[]) {
    if (argc != 2) { fprintf(stderr, "Usage: %s <file>\n", argv[0]); return 1; }

    /* Build from text — easiest approach for known ACLs */
    const char *acl_text = "u::rw-,u:alice:r--,g::r--,m::rw-,o::---";
    acl_t acl = acl_from_text(acl_text);
    if (!acl) { perror("acl_from_text"); return 1; }

    /* Validate */
    if (acl_valid(acl) != 0) {
        fprintf(stderr, "ACL is invalid\n");
        acl_free(acl); return 1;
    }

    /* Apply to file */
    if (acl_set_file(argv[1], ACL_TYPE_ACCESS, acl) == -1) {
        perror("acl_set_file"); acl_free(acl); return 1;
    }

    printf("ACL applied: %s\n", acl_text);
    acl_free(acl);
    return 0;
}
/* Compile: gcc set_acl.c -lacl -o set_acl
   Run:     ./set_acl myfile.txt */

#include <stdio.h>
#include <stdlib.h>
#include <sys/acl.h>
#include <pwd.h>

/* Adds read permission for a named user to a file's ACL.
   Usage: ./add_user_acl <file> <username> */
int main(int argc, char *argv[]) {
    if (argc != 3) { fprintf(stderr, "Usage: %s <file> <user>\n", argv[0]); return 1; }

    const char *path = argv[1];
    const char *username = argv[2];

    /* Look up UID */
    struct passwd *pw = getpwnam(username);
    if (!pw) { fprintf(stderr, "User %s not found\n", username); return 1; }
    uid_t uid = pw->pw_uid;

    /* Fetch current ACL */
    acl_t acl = acl_get_file(path, ACL_TYPE_ACCESS);
    if (!acl) { perror("acl_get_file"); return 1; }

    /* Create a new entry */
    acl_entry_t entry;
    if (acl_create_entry(&acl, &entry) == -1) {
        perror("acl_create_entry"); acl_free(acl); return 1;
    }

    /* Set tag type to ACL_USER */
    if (acl_set_tag_type(entry, ACL_USER) == -1) {
        perror("acl_set_tag_type"); acl_free(acl); return 1;
    }

    /* Set qualifier (UID) */
    if (acl_set_qualifier(entry, &uid) == -1) {
        perror("acl_set_qualifier"); acl_free(acl); return 1;
    }

    /* Set permissions: read only */
    acl_permset_t permset;
    acl_get_permset(entry, &permset);
    acl_clear_perms(permset);
    acl_add_perm(permset, ACL_READ);
    acl_set_permset(entry, permset);

    /* Recalculate mask */
    if (acl_calc_mask(&acl) == -1) {
        perror("acl_calc_mask"); acl_free(acl); return 1;
    }

    /* Write back */
    if (acl_set_file(path, ACL_TYPE_ACCESS, acl) == -1) {
        perror("acl_set_file"); acl_free(acl); return 1;
    }

    printf("Added read access for %s (uid=%d) on %s\n", username, uid, path);
    acl_free(acl);
    return 0;
}
/* Compile: gcc add_user_acl.c -lacl -o add_user_acl */

#include <stdio.h>
#include <stdlib.h>
#include <sys/acl.h>
#include <pwd.h>

/* Check whether a given user has write permission via ACL.
   Usage: ./check_write_acl <file> <username> */
int main(int argc, char *argv[]) {
    if (argc != 3) { fprintf(stderr, "Usage: %s <file> <user>\n", argv[0]); return 1; }

    struct passwd *pw = getpwnam(argv[2]);
    if (!pw) { fprintf(stderr, "User not found\n"); return 1; }
    uid_t target_uid = pw->pw_uid;

    acl_t acl = acl_get_file(argv[1], ACL_TYPE_ACCESS);
    if (!acl) { perror("acl_get_file"); return 1; }

    acl_entry_t entry;
    int eid, found = 0;

    for (eid = ACL_FIRST_ENTRY; acl_get_entry(acl, eid, &entry) == 1;
         eid = ACL_NEXT_ENTRY) {

        acl_tag_t tag;
        acl_get_tag_type(entry, &tag);

        if (tag == ACL_USER) {
            uid_t *uidp = acl_get_qualifier(entry);
            if (uidp && *uidp == target_uid) {
                acl_permset_t ps;
                acl_get_permset(entry, &ps);
                int has_write = acl_get_perm(ps, ACL_WRITE);
                printf("User %s has %s permission on %s\n",
                       argv[2],
                       has_write ? "WRITE" : "NO WRITE",
                       argv[1]);
                found = 1;
                acl_free(uidp);
                break;
            }
            if (uidp) acl_free(uidp);
        }
    }

    if (!found)
        printf("No ACL_USER entry found for %s\n", argv[2]);

    acl_free(acl);
    return 0;
}
/* Compile: gcc check_write_acl.c -lacl -o check_write_acl */

The book includes a program called acl_view.c that reads and displays a file’s ACL — essentially a subset of getfacl. Below is a clean, annotated version showing every API call used and why.

/* acl_view.c — Display ACL of a file.
   Usage:   ./acl_view [-d] <file>
   -d flag: show default ACL instead of access ACL

   Compile: gcc acl_view.c -lacl -o acl_view
*/
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <unistd.h>
#include <sys/acl.h>
#include <acl/libacl.h>   /* Linux extensions: acl_get_perm() */
#include <pwd.h>
#include <grp.h>

static void print_perms(acl_permset_t permset) {
    /* acl_get_perm() is a Linux extension; returns 1/0/-1 */
    int r = acl_get_perm(permset, ACL_READ);
    int w = acl_get_perm(permset, ACL_WRITE);
    int x = acl_get_perm(permset, ACL_EXECUTE);
    printf("%c%c%c", r ? 'r' : '-', w ? 'w' : '-', x ? 'x' : '-');
}

int main(int argc, char *argv[]) {
    int opt;
    acl_type_t type = ACL_TYPE_ACCESS;   /* default: access ACL */

    /* Parse options */
    while ((opt = getopt(argc, argv, "d")) != -1) {
        if (opt == 'd') type = ACL_TYPE_DEFAULT;
        else { fprintf(stderr, "Usage: %s [-d] <file>\n", argv[0]); return 1; }
    }
    if (optind + 1 != argc) {
        fprintf(stderr, "Usage: %s [-d] <file>\n", argv[0]); return 1;
    }

    /* STEP 1: Read the ACL into memory */
    acl_t acl = acl_get_file(argv[optind], type);
    if (acl == NULL) { perror("acl_get_file"); return 1; }

    acl_entry_t entry;
    int entryId;

    /* STEP 2: Walk through all entries */
    for (entryId = ACL_FIRST_ENTRY; ; entryId = ACL_NEXT_ENTRY) {

        /* acl_get_entry returns 1=got entry, 0=no more, -1=error */
        if (acl_get_entry(acl, entryId, &entry) != 1) break;

        /* STEP 3: Get the tag type of this entry */
        acl_tag_t tag;
        if (acl_get_tag_type(entry, &tag) == -1) {
            perror("acl_get_tag_type"); break;
        }

        /* Print tag name */
        const char *tname = (tag == ACL_USER_OBJ)  ? "user_obj"  :
                            (tag == ACL_USER)       ? "user"      :
                            (tag == ACL_GROUP_OBJ)  ? "group_obj" :
                            (tag == ACL_GROUP)      ? "group"     :
                            (tag == ACL_MASK)       ? "mask"      :
                            (tag == ACL_OTHER)      ? "other"     : "???";
        printf("%-12s", tname);

        /* STEP 4: Print qualifier (only for ACL_USER and ACL_GROUP) */
        if (tag == ACL_USER) {
            uid_t *uidp = acl_get_qualifier(entry);   /* returns uid_t* */
            if (!uidp) { perror("acl_get_qualifier"); break; }
            struct passwd *pw = getpwuid(*uidp);
            if (pw) printf("%-10s ", pw->pw_name);
            else    printf("%-10u ", (unsigned)*uidp);
            acl_free(uidp);   /* MUST free the qualifier */
        } else if (tag == ACL_GROUP) {
            gid_t *gidp = acl_get_qualifier(entry);   /* returns gid_t* */
            if (!gidp) { perror("acl_get_qualifier"); break; }
            struct group *gr = getgrgid(*gidp);
            if (gr) printf("%-10s ", gr->gr_name);
            else    printf("%-10u ", (unsigned)*gidp);
            acl_free(gidp);
        } else {
            printf("%-11s", " ");
        }

        /* STEP 5: Get and print the permission set */
        acl_permset_t permset;
        if (acl_get_permset(entry, &permset) == -1) {
            perror("acl_get_permset"); break;
        }
        print_perms(permset);
        printf("\n");
    }

    /* STEP 6: Free the in-memory ACL */
    if (acl_free(acl) == -1) perror("acl_free");

    return 0;
}

Sample run:

$ touch tfile
$ setfacl -m 'u:alice:r,u:bob:rw,g:devteam:r' tfile
$ ./acl_view tfile
user_obj            rw-
user       alice     r--
user       bob       rw-
group_obj           r--
group      devteam   r--
mask                rw-
other               r--

acl_calc_mask(&acl) computes and sets the ACL_MASK entry as the union of all ACL_USER, ACL_GROUP, and ACL_GROUP_OBJ permissions. It also creates the ACL_MASK entry if it doesn’t exist yet. Always call this after modifying any ACL that has or will have ACL_USER/ACL_GROUP entries.

acl_valid(acl) checks that the ACL is structurally correct — required entries present, no duplicate user/group entries, mask present when needed. Returns 0 if valid, -1 if invalid.

#include <stdio.h>
#include <stdlib.h>
#include <sys/acl.h>

/* Builds the ACL: owner=rwx, alice=r--, group=r-x, other=--- */
int main(int argc, char *argv[]) {
    if (argc != 2) { fprintf(stderr, "Usage: %s <file>\n", argv[0]); return 1; }

    /* Helper macro: add an entry with given tag & perms */
    acl_t acl = acl_init(5);   /* hint: we plan ~5 entries */
    if (!acl) { perror("acl_init"); return 1; }

    acl_entry_t ent;
    acl_permset_t ps;

    /* --- ACL_USER_OBJ (owner) = rwx --- */
    acl_create_entry(&acl, &ent);
    acl_set_tag_type(ent, ACL_USER_OBJ);
    acl_get_permset(ent, &ps); acl_clear_perms(ps);
    acl_add_perm(ps, ACL_READ); acl_add_perm(ps, ACL_WRITE); acl_add_perm(ps, ACL_EXECUTE);
    acl_set_permset(ent, ps);

    /* --- ACL_USER (alice) = r-- --- */
    uid_t alice_uid = 1001;    /* replace with real UID or getpwnam lookup */
    acl_create_entry(&acl, &ent);
    acl_set_tag_type(ent, ACL_USER);
    acl_set_qualifier(ent, &alice_uid);
    acl_get_permset(ent, &ps); acl_clear_perms(ps);
    acl_add_perm(ps, ACL_READ);
    acl_set_permset(ent, ps);

    /* --- ACL_GROUP_OBJ (file group) = r-x --- */
    acl_create_entry(&acl, &ent);
    acl_set_tag_type(ent, ACL_GROUP_OBJ);
    acl_get_permset(ent, &ps); acl_clear_perms(ps);
    acl_add_perm(ps, ACL_READ); acl_add_perm(ps, ACL_EXECUTE);
    acl_set_permset(ent, ps);

    /* --- ACL_OTHER = --- --- */
    acl_create_entry(&acl, &ent);
    acl_set_tag_type(ent, ACL_OTHER);
    acl_get_permset(ent, &ps); acl_clear_perms(ps);
    acl_set_permset(ent, ps);

    /* Compute and create ACL_MASK automatically */
    if (acl_calc_mask(&acl) == -1) { perror("acl_calc_mask"); acl_free(acl); return 1; }

    /* Validate before writing */
    if (acl_valid(acl) != 0) {
        fprintf(stderr, "ACL is not valid!\n"); acl_free(acl); return 1;
    }

    /* Apply */
    if (acl_set_file(argv[1], ACL_TYPE_ACCESS, acl) == -1) {
        perror("acl_set_file"); acl_free(acl); return 1;
    }

    /* Display what we set */
    ssize_t len;
    char *txt = acl_to_text(acl, &len);
    printf("Applied ACL:\n%s\n", txt);
    acl_free(txt);
    acl_free(acl);
    return 0;
}
/* Compile: gcc build_acl.c -lacl -o build_acl */

Everything returned by heap-allocating ACL functions must be freed with acl_free(). Missing these calls causes memory leaks, especially in long-running daemons. The following objects must be freed: