1Implementation details 2====================== 3 4Functionality level 5------------------- 6 7The IEEE 1003.1e draft 17 ("POSIX.1e") describes a set of 28 functions. 8These are grouped into three groups, based on their portability: 9 10- first group, the most portable one. All systems which claim to support 11 POSIX.1e should implement these: 12 13 acl_delete_def_file(3), acl_dup(3), acl_free(3), acl_from_text(3), 14 acl_get_fd(3), acl_get_file(3), acl_init(3), acl_set_fd(3), 15 acl_set_file(3), acl_to_text(3), acl_valid(3) 16 17- second group, containing the rest of the POSIX ACL functions. Systems 18 which claim to fully implement POSIX.1e should implement these: 19 20 acl_add_perm(3), acl_calc_mask(3), acl_clear_perms(3), 21 acl_copy_entry(3), acl_copy_ext(3), acl_copy_int(3), 22 acl_create_entry(3), acl_delete_entry(3), acl_delete_perm(3), 23 acl_get_entry(3), acl_get_permset(3), acl_get_qualifier(3), 24 acl_get_tag_type(3), acl_set_permset(3), acl_set_qualifier(3), 25 acl_set_tag_type(3), acl_size(3) 26 27- third group, containing extra functions implemented by each OS. These 28 are non-portable version. Both Linux and FreeBSD implement some extra 29 functions. 30 31Thus we have the level of compliance. Depending on whether the system 32library support the second group, you get some extra methods for the ACL 33object. 34 35The implementation of the second group of function can be tested by 36checking the module-level constant HAS_ACL_ENTRY. The extra 37functionality available on Linux can be tested by additional HAS_* 38constants. 39 40Internal structure 41------------------ 42 43The POSIX draft has the following stuff (correct me if I'm wrong): 44 45- an ACL is denoted by acl_t 46- an ACL contains many acl_entry_t, these are the individual entries in 47 the list; they always(!) belong to an acl_t 48- each entry_t has a qualifier (think uid_t or gid_t), whose type is 49 denoted by the acl_tag_t type, and an acl_permset_t 50- the acl_permset_t can contain acl_perm_t value (ACL_READ, ACL_WRITE, 51 ACL_EXECUTE, ACL_ADD, ACL_DELETE, ...) 52- functions to manipulate all these, and functions to manipulate files 53 54Currently supported platforms 55----------------------------- 56 57For any other platforms, volunteers are welcome. 58 59Linux 60~~~~~ 61 62It needs kernel 2.4 or higher and the libacl library installed (with 63development headers, if installing from rpm). This library is available 64on all modern distributions. 65 66The level of compliance is level 2 (see IMPLEMENTATION), plus some extra 67functions; and as my development is done on Linux, I try to implement 68these extensions when it makes sense. 69 70 71FreeBSD 72~~~~~~~ 73 74The current tested version is 7.0. FreeBSD supports all the standards 75functions, but 7.0-RELEASE seems to have some issues regarding the 76acl_valid() function when the qualifier of an ACL_USER or ACL_GROUP 77entry is the same as the current uid. By my interpretation, this should 78be a valid ACL, but FreeBSD declares the ACL invalid. As such, some 79unittests fail on FreeBSD. 80 81Porting to other platforms 82-------------------------- 83 84First, determine if your OS supports the full 28 functions of the 85POSIX.1e draft (if so, define HAVE_LEVEL2) or only the first 11 86functions (most common case, meaning only HAVE_LEVEL1). 87 88If your OS supports only LEVEL1, modify ``setup.py`` as appropriately; 89unfortunately, the functionality of the module is quite low. 90 91If your OS supports LEVEL2, there is a function which you must define: 92testing if an acl_permset_t contains a given permission. For example, 93under Linux, the acl library defines:: 94 95 int acl_get_perm(acl_permset_t permset_d, acl_perm_t perm); 96 97under FreeBSD, the library defines ``acl_get_perm_np`` with a similar 98syntax. So just see how this is implemented in your platform and either 99define a simple macro or a full function with the syntax:: 100 101 static int get_perm(acl_permset_t permset_d, acl_perm_t perm); 102 103which must return 1 if the permset contains perm and 0 otherwise. 104 105 106.. Local Variables: 107.. mode: rst 108.. fill-column: 72 109.. End: 110