Reference documentation about ACLs.

3 files changed, 586 insertions, 0 deletions

diff --git a/ChangeLog b/ChangeLog
index e515bb039e..dc0ade5bb7 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,11 @@
 2008-05-21  Bruno Haible  <bruno@clisp.org>
 
+	Add reference doc about ACLs.
+	* doc/acl-resources.txt: New file.
+	* doc/acl-cygwin.txt: New file.
+
+2008-05-21  Bruno Haible  <bruno@clisp.org>
+
 	Avoid one more warning from gcc.
 	* lib/vasnprintf.c (IF_LINT): Update comments.
 	(VASNPRINTF): Use it also for the 'prefix' array initializer.
diff --git a/doc/acl-cygwin.txt b/doc/acl-cygwin.txt
new file mode 100644
index 0000000000..e3007f5108
--- /dev/null
+++ b/doc/acl-cygwin.txt
@@ -0,0 +1,138 @@
+$ getfacl --help
+Usage: getfacl [-adn] FILE [FILE2...]
+Display file and directory access control lists (ACLs).
+
+  -a, --all      display the filename, the owner, the group, and
+                 the ACL of the file
+  -d, --dir      display the filename, the owner, the group, and
+                 the default ACL of the directory, if it exists
+  -h, --help     output usage information and exit
+  -n, --noname   display user and group IDs instead of names
+  -v, --version  output version information and exit
+
+When multiple files are specified on the command line, a blank
+line separates the ACLs for each file.
+For each argument that is a regular file, special file or
+directory, getfacl displays the owner, the group, and the ACL.
+For directories getfacl displays additionally the default ACL.
+
+With no options specified, getfacl displays the filename, the
+owner, the group, and both the ACL and the default ACL, if it
+exists.
+
+The format for ACL output is as follows:
+     # file: filename
+     # owner: name or uid
+     # group: name or uid
+     user::perm
+     user:name or uid:perm
+     group::perm
+     group:name or gid:perm
+     mask:perm
+     other:perm
+     default:user::perm
+     default:user:name or uid:perm
+     default:group::perm
+     default:group:name or gid:perm
+     default:mask:perm
+     default:other:perm
+
+
+
+$ setfacl --help
+Usage: setfacl [-r] (-f ACL_FILE | -s acl_entries) FILE...
+       setfacl [-r] ([-d acl_entries] [-m acl_entries]) FILE...
+Modify file and directory access control lists (ACLs)
+
+  -d, --delete     delete one or more specified ACL entries
+  -f, --file       set ACL entries for FILE to ACL entries read
+                   from a ACL_FILE
+  -m, --modify     modify one or more specified ACL entries
+  -r, --replace    replace mask entry with maximum permissions
+                   needed for the file group class
+  -s, --substitute substitute specified ACL entries for the
+                   ACL of FILE
+  -h, --help       output usage information and exit
+  -v, --version    output version information and exit
+
+At least one of (-d, -f, -m, -s) must be specified
+
+     Acl_entries are one or more comma-separated ACL entries 
+     from the following list:
+
+         u[ser]::perm
+         u[ser]:uid:perm
+         g[roup]::perm
+         g[roup]:gid:perm
+         m[ask]:perm
+         o[ther]:perm
+
+     Default entries are like the above with the additional
+     default identifier. For example: 
+
+         d[efault]:u[ser]:uid:perm
+
+     'perm' is either a 3-char permissions string in the form
+     "rwx" with the character - for no permission
+     or it is the octal representation of the permissions, a
+     value from 0 (equivalent to "---") to 7 ("rwx").
+     'uid' is a user name or a numerical uid.
+     'gid' is a group name or a numerical gid.
+
+
+For each file given as parameter, setfacl will either replace its
+complete ACL (-s, -f), or it will add, modify, or delete ACL
+entries.
+
+The following options are supported:
+
+-d   Delete one or more specified entries from the file's ACL.
+     The owner, group and others entries must not be deleted.
+     Acl_entries to be deleted should be specified without
+     permissions, as in the following list:
+
+         u[ser]:uid
+         g[roup]:gid
+         d[efault]:u[ser]:uid
+         d[efault]:g[roup]:gid
+         d[efault]:m[ask]:
+         d[efault]:o[ther]:
+
+-f   Take the Acl_entries from ACL_FILE one per line. Whitespace
+     characters are ignored, and the character "#" may be used
+     to start a comment.  The special filename "-" indicates
+     reading from stdin.
+     Required entries are
+     - One user entry for the owner of the file.
+     - One group entry for the group of the file.
+     - One other entry.
+     If additional user and group entries are given:
+     - A mask entry for the file group class of the file.
+     - No duplicate user or group entries with the same uid/gid.
+     If it is a directory:
+     - One default user entry for the owner of the file.
+     - One default group entry for the group of the file.
+     - One default mask entry for the file group class.
+     - One default other entry.
+
+-m   Add or modify one or more specified ACL entries.
+     Acl_entries is a comma-separated list of entries from the 
+     same list as above.
+
+-r   Causes the permissions specified in the mask entry to be
+     ignored and replaced by the maximum permissions needed for
+     the file group class.
+
+-s   Like -f, but substitute the file's ACL with Acl_entries
+     specified in a comma-separated list on the command line.
+
+While the -d and -m options may be used in the same command, the
+-f and -s options may be used only exclusively.
+
+Directories may contain default ACL entries.  Files created
+in a directory that contains default ACL entries will have
+permissions according to the combination of the current umask,
+the explicit permissions requested and the default ACL entries
+Note: Under Cygwin, the default ACL entries are not taken into
+account currently.
+
diff --git a/doc/acl-resources.txt b/doc/acl-resources.txt
new file mode 100644
index 0000000000..91079b46cf
--- /dev/null
+++ b/doc/acl-resources.txt
@@ -0,0 +1,442 @@
+General introduction:
+  http://www.suse.de/~agruen/acl/linux-acls/online/
+
+
+POSIX ACLs
+
+Documents from POSIX.1e (headers & functions) and POSIX.2c (utilities):
+  http://wt.xpilot.org/publications/posix.1e/download.html
+
+
+Linux ACLs
+
+Introduction:
+  http://www.suse.de/~agruen/acl/linux-acls/online/
+Hands-on tutorial:
+  http://www.vanemery.com/Linux/ACL/linux-acl.html
+
+Manual pages:
+  http://www.linuxmanpages.com/
+Includes:
+  <sys/acl.h>
+  <acl/libacl.h>
+Library:
+  -lacl
+Functions:
+  acl_add_perm
+  acl_calc_mask
+  acl_check
+  acl_clear_perms
+  acl_cmp
+  acl_copy_entry
+  acl_copy_ext
+  acl_copy_int
+  acl_create_entry
+  acl_delete_def_file
+  acl_delete_entry
+  acl_delete_perm
+  acl_dup
+  acl_entries
+  acl_equiv_mode
+  acl_error
+  acl_extended_fd
+  acl_extended_file
+  acl_free
+  acl_from_mode
+  acl_from_text
+  acl_get_entry
+  acl_get_fd
+  acl_get_file
+  acl_get_perm
+  acl_get_permset
+  acl_get_qualifier
+  acl_get_tag_type
+  acl_init
+  acl_set_fd
+  acl_set_file
+  acl_set_permset
+  acl_set_qualifier
+  acl_set_tag_type
+  acl_size
+  acl_to_any_text
+  acl_to_text
+  acl_valid
+Utilities:
+  getfacl
+  setfacl
+
+
+Solaris ACLs
+
+Introductions:
+  http://www.softpanorama.org/Solaris/ACL/index.shtml
+  http://www.cs.duke.edu/csl/faqs/solaris-acls.php
+Manual pages:
+  http://docs.sun.com/app/docs/doc/816-5167/acl-2?l=en&a=view
+  http://docs.sun.com/app/docs/doc/816-5165/getfacl-1?l=en&a=view
+  http://docs.sun.com/app/docs/doc/816-5165/setfacl-1?l=en&a=view
+Includes:
+  <sys/acl.h>
+Library:
+  -lsec
+Functions:
+  acl
+  facl
+  aclcheck
+  aclfrommode
+  aclfromtext
+  aclsort
+  acltomode
+  acltotext
+Utilities:
+  getfacl
+  setfacl
+  chmod
+
+
+FreeBSD ACLs
+
+Introduction:
+  http://www.freebsd.org/doc/en/books/handbook/fs-acl.html
+  http://www.onlamp.com/pub/a/bsd/2005/09/22/FreeBSD_Basics.html
+Manual pages:
+  http://www.freebsd.org/cgi/man.cgi
+  http://www.freebsd.org/cgi/man.cgi?query=acl&apropos=0&sektion=0&manpath=FreeBSD+7.0-RELEASE&format=html
+Includes:
+  <sys/acl.h>
+Library:
+  none needed
+Functions:
+  acl_add_perm
+  acl_calc_mask
+  acl_clear_perms
+  acl_copy_entry
+  acl_copy_ext
+  acl_copy_int
+  acl_create_entry
+  acl_delete_entry
+  acl_delete_fd_np
+  acl_delete_file_np
+  acl_delete_link_np
+  acl_delete_def_file
+  acl_delete_def_link_np
+  acl_delete_perm
+  acl_dup
+  acl_free
+  acl_from_text
+  acl_get
+  acl_get_entry
+  acl_get_fd
+  acl_get_fd_np
+  acl_get_file
+  acl_get_link_np
+  acl_get_perm_np
+  acl_get_permset
+  acl_get_qualifier
+  acl_get_tag_type
+  acl_init
+  acl_set
+  acl_set_fd
+  acl_set_fd_np
+  acl_set_file
+  acl_set_link_np
+  acl_set_permset
+  acl_set_qualifier
+  acl_set_tag_type
+  acl_size
+  acl_to_text
+  acl_valid
+  acl_valid_fd_np
+  acl_valid_file_np
+  acl_valid_link_np
+Utilities:
+  getfacl
+  setfacl
+
+
+NetBSD ACLs
+
+Not available.
+
+
+OpenBSD ACLs
+
+Not available.
+
+
+MacOS X ACLs
+
+Manual pages:
+  http://developer.apple.com/documentation/Darwin/Reference/ManPages/man3/acl.3.html
+Includes:
+  <sys/acl.h>
+Library:
+  none needed
+Functions:
+  acl_add_flag_np
+  acl_add_perm
+  acl_calc_mask
+  acl_clear_flags_np
+  acl_clear_perms
+  acl_copy_entry
+  acl_copy_ext
+  acl_copy_ext_native
+  acl_copy_int
+  acl_copy_int_native
+  acl_create_entry
+  acl_create_entry_np
+  acl_delete_def_file
+  acl_delete_fd_np (undeclared?)
+  acl_delete_file_np (undeclared?)
+  acl_delete_flag_np
+  acl_delete_link_np (undeclared?)
+  acl_delete_entry
+  acl_delete_perm
+  acl_dup
+  acl_free
+  acl_from_text
+  acl_get_entry
+  acl_get_fd
+  acl_get_fd_np
+  acl_get_file
+  acl_get_flag_np
+  acl_get_flagset_np
+  acl_get_link_np
+  acl_get_perm_np
+  acl_get_permset
+  acl_get_qualifier
+  acl_get_tag_type
+  acl_init
+  acl_set_fd
+  acl_set_fd_np
+  acl_set_file
+  acl_set_flagset_np
+  acl_set_link_np
+  acl_set_permset
+  acl_set_qualifier
+  acl_set_tag_type
+  acl_size
+  acl_to_text
+  acl_valid
+  acl_valid_fd_np
+  acl_valid_file_np
+  acl_valid_link_np
+Utilities:
+  chmod
+
+
+HP-UX ACLs
+
+Manual pages:
+  http://docs.hp.com/en/B2355-60105/acl.2.html
+  http://docs.hp.com/en/B2355-60105/lsacl.1.html
+  http://docs.hp.com/en/B2355-60105/chacl.1.html
+  http://docs.hp.com/en/B2355-60105/getacl.1.html
+Includes:
+  <acl.h> or <sys/acl.h>, optionally <aclv.h>
+Library:
+  none needed
+Functions:
+  getacl
+  fgetacl
+  fsetacl
+  setacl
+Functions only declared in <aclv.h>:
+  acl
+Utilities:
+  lsacl
+  chacl
+  getacl
+  setacl
+  chmod
+
+
+IRIX ACLs
+
+Manual pages:
+  http://techpubs.sgi.com/library/tpl/cgi-bin/browse.cgi?cmd=search&db=man&srch=acl&coll=0650&range=0,133
+  http://techpubs.sgi.com/library/tpl/cgi-bin/getdoc.cgi?coll=0650&db=man&fname=/usr/share/catman/p_man/cat4/acl.z
+Includes:
+  <sys/acl.h>
+Library:
+  none needed
+Functions:
+  acl_add_perm
+  acl_calc_mask
+  acl_clear_perms
+  acl_copy_entry
+  acl_copy_ext
+  acl_copy_int
+  acl_create_entry
+  acl_delete_def_file
+  acl_delete_entry
+  acl_delete_perm
+  acl_dup
+  acl_free
+  acl_from_text
+  acl_get_entry
+  acl_get_fd
+  acl_get_file
+  acl_get_permset
+  acl_get_qualifier
+  acl_get_tag_type
+  acl_init
+  acl_set_fd
+  acl_set_file
+  acl_set_permset
+  acl_set_qualifier
+  acl_set_tag_type
+  acl_size
+  acl_to_short_text
+  acl_to_text
+  acl_valid
+Utilities:
+  chacl
+
+
+Tru64 ACLs
+
+Manual pages:
+  http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/V51_HTML/MAN/MAN4/0083____.HTM
+Includes:
+  <sys/acl.h>
+Library:
+  -lpacl
+Functions:
+  acl_add_perm
+  acl_clear_perm
+  acl_copy_entry
+  acl_copy_ext
+  acl_copy_int
+  acl_create_entry
+  acl_delete_def_fd
+  acl_delete_def_file
+  acl_delete_entry
+  acl_delete_perm
+  acl_dup
+  acl_first_entry
+  acl_free
+  acl_free_qualifier
+  acl_free_text
+  acl_from_text
+  acl_get_entry
+  acl_get_fd
+  acl_get_file
+  acl_get_permset
+  acl_get_qualifier
+  acl_get_tag_type
+  acl_init
+  acl_set_fd
+  acl_set_file
+  acl_set_permset
+  acl_set_qualifier
+  acl_set_tag_type
+  acl_size
+  acl_to_text
+  acl_valid
+Unportable functions:
+  acl_add_entry
+  acl_delete_access_fd
+  acl_delete_access_file
+  acl_delete_def_dir_fd
+  acl_delete_def_dir_file
+  acl_ext_to_text
+  acl_find_entry
+  acl_get
+  acl_mod_perm
+  acl_set
+  acl_to_fmt_text
+  allocate_acl_entry
+  convert_to_er
+  isaclprop
+Utilities:
+  getacl
+  setacl
+
+
+AIX ACLs
+
+Documentation:
+  http://publib.boulder.ibm.com/infocenter/systems/index.jsp?topic=/com.ibm.aix.security/doc/security/access_control_list.htm
+Introduction:
+  http://www1.uni-hamburg.de/RRZ/Software/AIX/ACL.htm
+Includes:
+  <acl.h> or <sys/acl.h>
+  <sys/access.h>
+Library:
+  none needed
+Functions:
+  acl_chg
+  acl_fchg
+  acl_fget
+  acl_fput
+  acl_fset
+  acl_get
+  acl_put
+  acl_set
+  chacl
+  fchacl
+  fstatacl
+  statacl
+Function in AIX 5.3:
+  aclx_convert
+  aclx_fget
+  aclx_fput
+  aclx_get
+  aclx_gettypeinfo
+  aclx_gettypes
+  aclx_print
+  aclx_printStr
+  aclx_put
+  aclx_scan
+  aclx_scanStr
+Utilities:
+  aclget
+  aclput
+  acledit
+
+
+Cygwin ACLs
+
+Documentation:
+  http://www.cygwin.com/cygwin-ug-net/ntsec.html#ntsec-aclfuncs
+  acl-cygwin.txt
+Includes:
+  <sys/acl.h>
+Library:
+  none needed
+Functions:
+  acl
+  aclcheck
+  aclfrommode
+  aclfrompbits
+  aclfromtext
+  aclsort
+  acltomode
+  acltopbits
+  acltotext
+  facl
+  lacl
+Utilities:
+  getfacl
+  setfacl
+
+
+Win32 ACLs
+
+Introduction:
+  http://setacl.sourceforge.net/html/doc-basics.html
+Manual pages:
+  http://msdn.microsoft.com/en-us/library/aa374872(VS.85).aspx
+  http://msdn.microsoft.com/en-us/library/aa446659(VS.85).aspx
+  http://msdn.microsoft.com/en-us/library/aa374931(VS.85).aspx
+  http://en.wikipedia.org/wiki/Cacls
+Library:
+  ?
+Functions:
+  GetAclInformation
+  SetAclInformation
+  ...
+Utilities:
+  cacls
+