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

資料結構

    acl_t --- acl_entry_t --+-- acl_tag_t (tag type)
                            |-- void* (qualifier)
                            \-- acl_permest_t (permission) --- acl_perm_t

==============================================================================

註：標記 $ 表示 may cause memory to be allocated

通用函式

    int acl_free(void *obj_p);

建立或複製資料結構

$   acl_t acl_init(int 至少有幾個項目);
$   acl_t acl_dup(acl_t 來源);

編輯項目

    建立或刪除項目

$       int acl_create_entry(acl_t *acl_p, acl_entry_t *entry_p);
        int acl_delete_entry(acl_t acl, acl_entry_t entry_d);
        int acl_copy_entry(acl_entry_t 目的地, acl_entry_t 來源);

    讀取與檢驗

        int acl_get_entry(acl_t acl, int entry_id, acl_entry_t *entry_p);
            entry_id 欄位：
                ACL_FIRST_ENTRY 讀取第一個項目
                ACL_NEXT_ENTRY  讀取下一個項目
            回傳值：
                1   成功
                0   沒有項目可以回傳或已經讀完了
                -1  發生錯誤
        int acl_valid(acl_t acl);

    編輯項目：tag type

        acl_tag_t 的可能值：
            ACL_USER_OBJ    denotes access rights for the file owner
            ACL_USER        denote access rights for users
            ACL_GROUP_OBJ   denotes access rights for the file group
            ACL_GROUP       denote access rights for groups
            ACL_MASK
            ACL_OTHER

        int acl_get_tag_type(acl_entry_t entry_d, acl_tag_t *tag_type_p);
        int acl_set_tag_type(acl_entry_t entry_d, acl_tag_t tag_type);

    編輯項目：qualifier

        只在 tag type 為 ACL_USER 或 ACL_GROUP 時有效
        (此時為 uid_t* 或 gid_t*)

        void * acl_get_qualifier(acl_entry_t entry_d);
        int acl_set_qualifier(acl_entry_t entry_d, const void *qualifier_p);

    編輯項目：permission set

        int acl_get_permset(acl_entry_t entry_d, acl_permset_t *permset_p);
        int acl_set_permset(acl_entry_t entry_d, acl_permset_t permset_d);

        編輯項目：permission

            acl_perm_t 的可能值：
                ACL_READ
                ACL_WRITE
                ACL_EXECUTE

            int acl_clear_perms(acl_permset_t permset_d);
            int acl_add_perm(acl_permset_t permset_d, acl_perm_t perm);
            int acl_delete_perm(acl_permset_t permset_d, acl_perm_t perm);

            從 permset 中取得 perm ...... 似乎沒有簡單、通用的方法

            /* 我曾經利用 (int*) 強迫轉換再 de-reference，但這不是標準寫法，
               也不保證一定可以這樣用。

               但我真的不知道還有什麼簡單的方法可以得到相同的目的。
               真的覺得這是一個奇怪的設計......
               acl_get_perm() 居然是 Linux extension，所以沒寫進來......

               看了 libacl 的原始碼後，覺得可靠的方法似乎只有......
               解析 acl_to_text() 的輸出，但這實在是麻煩，而且感覺上就在做
               多餘的事！
               (請 acl_to_text() 轉換過去，然後我再轉回來......)
             */

自動修改 mask 值

    int acl_calc_mask(acl_t *acl_p);

ACL 與 文字表示法 的轉換

$   char * acl_to_text(acl_t acl, ssize_t *len_p);
$   acl_t acl_from_text(const char *buf_p);

將 ACL 資料結構輸入或輸出到連續的記憶體空間內

$   acl_t acl_copy_int(const void *buf_p);
    ssize_t acl_copy_ext(void *buf_p, acl_t acl, ssize_t size);
    ssize_t acl_size(acl_t acl);

檔案處理

$   acl_t acl_get_file(const char *path_p, acl_type_t type);
$   acl_t acl_get_fd(int fd);
    int acl_set_file(const char *path_p, acl_type_t type, acl_t acl);
    int acl_set_fd(int fd, acl_t acl);
        acl_type_t 欄位：
            ACL_TYPE_ACCESS     一般存取權限
            ACL_TYPE_DEFAULT    (只在目錄有效) 新建檔案所採用的權限
    int acl_delete_def_file(const char *path_p);

    註：刪除一般的存取權限只要將所有用不到的欄位刪掉即可