Introduce ACL man pages en masse for library calls, and general introduction.

Introduce ACL man pages en masse for library calls, and general introduction.

Also, fix acl_valid.c non-portable calls to include _np in their names,
making them standard-happy as well as consistent with acl.h

1 files changed, 171 insertions, 0 deletions

diff --git a/lib/libc/posix1e/acl.3 b/lib/libc/posix1e/acl.3
new file mode 100644
index 0000000..a70a60f
--- /dev/null
+++ b/lib/libc/posix1e/acl.3
@@ -0,0 +1,171 @@
+.\"-
+.\" Copyright (c) 2000 Robert N. M. Watson
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\"       $FreeBSD$
+.\"
+.Dd January 28, 2000
+.Dt ACL 3
+.Os FreeBSD 4.0
+.Sh NAME
+.Nm acl \- introduction to the POSIX.1e ACL security API
+.Sh SYNOPSIS
+.Fd #include <sys/types.h>
+.Fd #include <sys/acl.h>
+.Sh DESCRIPTION
+As shipped, FreeBSD 4.0 permits file systems to export
+Access Control Lists via the VFS, and provides a library for userland
+access to and manipulation of these ACLs, but support for ACLs is not
+provided by any file systems shipped in the base operating system.
+The library calls shipped with 4.0 include routines to allocate,
+duplicate, retrieve, set, and validate ACLs associated with file objects.
+As well as the POSIX.1e routines, there are a number of non-portable
+extensions defined that allow for alternative ACL semantics than the
+POSIX.1e semantics, such as AFS, NTFS, Coda, and NWFS semantics.  Where
+routines are non-standard, they are suffixed with _np to indicate that
+they are not portable.
+
+POSIX.1e describes a set of ACL manipulation routines to manage the
+contents of ACLs, as well as their relationships with files.  This
+manipulation library is not currently implemented in FreeBSD, although
+a third party library was under development at the time this document
+was written.  There is a general concensus that the POSIX.1e manipulation
+routines are ambiguously defined in the specification, and don't meet the
+needs of most applications.  For the time being, applications may
+directly manipulate the ACL structures, defined in acl.h, although the
+recommended usage is to only ever handle text-form ACLs in applications,
+generated and maintained using
+.Fn acl_from_text
+and
+.Fn acl_to_text ,
+passed directly to and from the management routines.  In this manner,
+an application can remain safely unaware of the contents of ACLs.
+
+Available functions, sorted by behavior, include:
+
+.Fn acl_delete_def_file ,
+.Fn acl_delete_file_np ,
+.Fn acl_delete_fd_np 
+
+These functions are described in
+.Xr acl_delete 3 ,
+and may be used to delete ACLs from file system objects.
+
+.Fn acl_free
+
+This function is described in
+.Xr acl_free 3 ,
+and may be used to free userland working ACL storage.
+
+.Fn acl_from_text
+
+This function is described in
+.Xr acl_from_text 3 ,
+and may be used to convert a text-form ACL into working ACL state, if
+the ACL has POSIX.1e semantics.
+
+.Fn acl_get_file ,
+.Fn acl_get_fd ,
+.Fn acl_get_fd_np
+
+These functions are described in
+.Xr acl_get 3 ,
+and may be used to retrieve ACLs from file system objects.
+
+.Fn acl_init
+
+This function is described in
+.Xr acl_init 3 ,
+and may be used to allocate a fresh (empty) ACL structure.
+
+.Fn acl_dup
+
+This function is described in
+.Xr acl_dup 3 ,
+and may be used to duplicate an ACL structure.
+
+.Fn acl_set_file ,
+.Fn acl_set_fd ,
+.Fn acl_set_fd_np
+
+These funtions are described in
+.Xr acl_set 3 ,
+and may be used to assign an ACL to a file system object.
+
+.Fn acl_to_text
+
+This function is described in
+.Xr acl_to_text 3 ,
+and may be used to generate a text-form of a POSIX.1e semantics ACL.
+
+.Fn acl_valid ,
+.Fn acl_valid_file_np ,
+.Fn acl_valid_fd_np
+
+Thee functions are described in
+.Xr acl_valid 3 ,
+and may be used to validate an ACL as correct POSIX.1e-semantics, or
+as appropriate for a particular file system object regardless of semantics.
+
+Documentation of the internal kernel interfaces backing these calls may
+be found in
+.Xr acl 9 .
+The syscalls between the internal interfaces and the public library
+routines may change over time, and as such are not documented.  They are
+not intended to be called directly without going through the library.
+.Sh IMPLEMENTATION NOTES
+FreeBSD's support for POSIX.1e interfaces and features is still under
+development at this time.
+.Sh ENVIRONMENT
+POSIX.1e assigns security labels to all objects, extending the security
+functionality described in POSIX.1.  These additional labels provide
+fine-grained discretionary access control, fine-grained capabilities,
+and labels necessary for mandatory access control.  POSIX.2c describes
+a set of userland utilities for manipulating these labels.  These userland
+utilities are not bundled with FreeBSD 4.0 so as to discourage their
+use in the short term.
+.Sh FILES
+.Sh SEE ALSO
+.Xr acl 3 ,
+.Xr acl_dup 3 ,
+.Xr acl_free 3 ,
+.Xr acl_from_text 3 ,
+.Xr acl_get 3 ,
+.Xr acl_set 3 ,
+.Xr acl_to_text 3 ,
+.Xr acl_valid 3 ,
+.Xr acl 9
+.Sh STANDARDS
+POSIX.1e is described in IEEE POSIX.1e draft 17.  Discussion
+of the draft continues on the cross-platform POSIX.1e implementation
+mailing list.  To join this list, see the FreeBSD POSIX.1e implementation
+page for more information.
+.Sh HISTORY
+POSIX.1e support was introduced in FreeBSD 4.0, and development continues.
+.Sh AUTHORS
+Robert N M Watson
+.Sh BUGS
+These features are not yet fully implemented.  In particular, the shipped
+version of UFS/FFS does not support storage of additional security labels,
+and so is unable to (easily) provide support for most of these features.