d/freebsd-nq
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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

Browse Source 
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
This commit is contained in:
Robert Watson 2000-01-28 20:07:00 +00:00
parent 49de1b5759
commit a889d1fb76
26 changed files with 2524 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
lib/libc/posix1e/Makefile
View File

@ -11,6 +11,28 @@ SRCS+= acl_delete.c \
acl_to_text.c \
acl_valid.c
MAN3= posix1e.3
MAN3= acl.3 \
acl_delete.3 \
acl_dup.3 \
acl_free.3 \
acl_from_text.3 \
acl_get.3 \
acl_init.3 \
acl_set.3 \
acl_to_text.3 \
acl_valid.3 \
posix1e.3
MLINKS+=acl_delete.3 acl_delete_def_file.3 \
acl_delete.3 acl_delete_file_np.3 \
acl_delete.3 acl_delete_fd_np.3 \
acl_get.3 acl_get_file.3 \
acl_get.3 acl_get_fd.3 \
acl_get.3 acl_get_fd_np.3 \
acl_set.3 acl_set_file.3 \
acl_set.3 acl_set_fd.3 \
acl_set.3 acl_set_fd_np.3 \
acl_valid.3 acl_valid_file_np.3 \
acl_valid.3 acl_valid_fd_np.3
.include <bsd.lib.mk>

171
lib/libc/posix1e/acl.3 Normal file
View File

@ -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.

120
lib/libc/posix1e/acl_delete.3 Normal file
View File

@ -0,0 +1,120 @@
.\"-
.\" 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_DELETE 3
.Os FreeBSD 4.0
.Sh NAME
.Nm acl_delete_def_file ,
.Nm acl_delete_file_np ,
.Nm acl_delete_fd_np
.Nd Delete an ACL from a file
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/acl.h>
.Ft int
.Fn acl_delete_def_file "const char *path_p"
.Ft int
.Fn acl_delete_file_np "const char *path_p" "acl_type_t type"
.Ft int
.Fn acl_delete_fd_np "int filedes" "acl_type_t type"
.Sh DESCRIPTION
The
.Fn acl_delete_def_file ,
.Fn acl_delete_file_np ,
and
.Fn acl_delete_fd_np
each allow the deletion of an ACL from a file.
.Fn acl_delete_def_file
is a POSIX.1e call that deletes the default ACL from a file (normally a
directory) by name; the other two calls are non-portable extensions that
allow deleting of arbitrary ACL types from a file/directory by either path
name, or by file descriptor.
.Sh IMPLEMENTATION NOTES
FreeBSD's support for POSIX.1e interfaces and features is still under
development at this time.
.Sh RETURN VALUES
In the event of success, 0 is returned. In the event of failure, -1 is
returned, and
.Va errno
is set to indicate the error.
.Sh ERRORS
If any of the following conditions occur, these functions shall return -1
and set
.Va errno
to teh corresponding value:
.Bl -tag -width Er
.It Bq Er EACCES
Search permission is denied for a component of the path prefix, or the
object exists and the process does not have appropriate access rights.
.It Bq Er EBADF
The
.Va fd
argument is not a valid file descriptor.
.It Bq Er EINVAL
The ACL type passed is invalid for this file object.
.It Bq Er ENAMETOOLONG
A component of a pathname exceeded 255 characters, or an
entire path name exceeded 1023 characters.
.It Bq Er ENOENT
The named object does not exist, or the
.Va path_p
argument points to an empty string.
.It Bq Er ENOMEM
Insufficient memory available to fulfill request.
.It Bq Er ENOTDIR
A component of the path prefix is not a directory.
Argument
.Va path_p
must be a directory, and is not.
.It Bq Er EOPNOTSUPP
The file system does not support ACL deletion.
.It Bq Er EPERM
The process does not have appropriate privilege to perform the operation
to delete an ACL.
.It Bq Er EROFS
The file system is read-only.
.El
.Sh SEE ALSO
.Xr acl 3 ,
.Xr acl_get 3 ,
.Xr acl_set 3 ,
.Xr posix1e 3
.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.

101
lib/libc/posix1e/acl_dup.3 Normal file
View File

@ -0,0 +1,101 @@
.\"-
.\" 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_DUP 3
.Os FreeBSD 4.0
.Sh NAME
.Nm acl_dup
.Nd Duplicate an ACL
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/acl.h>
.Ft acl_t
.Fn acl_dup "acl_t acl"
.Sh DESCRIPTION
The
.Fn acl_dup
function returns a pointer to a copy of the ACL pointed to by the argument
.Va acl .
This function may cause memory to be allocated. Teh caller should free any
releaseable memory, when the new ACL is no longer required, by calling
.Xr acl_free 3
with the
.Va (void*)acl_t
as an argument.
Any existing ACL pointers that refer to the ACL referred to by
.Va acl
shall continue to refer to the ACL.
.Sh IMPLEMENTATION NOTES
FreeBSD's support for POSIX.1e interfaces and features is still under
development at this time.
.Sh RETURN VALUES
Upon successful completion, this function shall return a pointer to the
duplicate ACL. Otherwise, a value of
.Va (acl_t)NULL
shall be returned, and
.Va errno
shall be set to indicate the error.
.Sh ERRORS
If any of the following conditions occur, the
.Fn acl_init
function shall return a value of
.Va (acl_t)NULL
and set
.Va errno
to the corresponding value:
.Bl -tag -width Er
.It Bq Er EINVAL
Argument
.Va acl
does not point to a valid ACL.
.It Bq Er ENOMEM
The
.Va acl_t
to be returned requires more memory than is allowed by the hardware or
system-imposed memory management constraints.
.El
.Sh SEE ALSO
.Xr acl 3 ,
.Xr acl_free 3 ,
.Xr acl_get 3 ,
.Xr posix1e 3
.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.

85
lib/libc/posix1e/acl_free.3 Normal file
View File

@ -0,0 +1,85 @@
.\"-
.\" 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_FREE 3
.Os FreeBSD 4.0
.Sh NAME
.Nm acl_free
.Nd Free ACL working state
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/acl.h>
.Ft int
.Fn acl_free "void *obj_p"
.Sh DESCRIPTION
The
.Fn acl_free
call allows the freeing of ACL working space, such as is allocated by
.Xr acl_dup 3 ,
or
.Xr acl_from_text 3 .
.Sh IMPLEMENTATION NOTES
FreeBSD's support for POSIX.1e interfaces and features is still under
development at this time.
.Sh RETURN VALUES
In the event of success, 0 is returned. In the event of failure, -1 is
returned, and
.Va errno
is set to indicate the error.
.Sh ERRORS
If any of the following conditions occur, the
.Fn acl_free
function shall return -1 and set
.Va errno
to the corresponding value:
.Bl -tag -width Er
.It Bq Er EINVAL
The value of the
.Va obj_p
argument is invalid.
.El
.Sh SEE ALSO
.Xr acl 3 ,
.Xr acl_dup 3 ,
.Xr acl_from_text 3 ,
.Xr acl_get 3 ,
.Xr acl_init 3 ,
.Xr posix1e 3
.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.

121
lib/libc/posix1e/acl_from_text.3 Normal file
View File

@ -0,0 +1,121 @@
.\"-
.\" 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_FROM_TEXT 3
.Os FreeBSD 4.0
.Sh NAME
.Nm acl_from_text
.Nd Create an ACL from text
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/acl.h>
.Ft int
.Fn acl_from_text "const char *buf_p"
.Sh DESCRIPTION
The
.Fn acl_from_text
function converts the text form of an ACL referred to by
.Va buf_p
into the internal working structure for ACLs, appropriate for applying to
files or manipulating.
This function may cause memory to be allocated. The caller should free any
releasable memory, when the new ACL is no longer required, by calling
.Xr acl_free 3
with the
.Va (void *)acl_t
as an argument.
.Sh IMPLEMENTATION NOTES
FreeBSD's support for POSIX.1e interfaces and features is still under
development at this time.
.Sh RETURN VALUES
Upon successful completion, the function shall return a pointer to the
internal representation of the ACL in working storage. Otherwise, a value
of
.Va (acl_t)NULL
shall be returned, and
.Va errno
shall be set to indicate the error.
.Sh ERRORS
If any of the following conditions occur, the
.Fn acl_from_text
function shall return a value of
.Va (acl_t)NULL
and set
.Va errno
to the corresponding value:
.Bl -tag -width Er
.It Bq Er EACCES
Search permission is denied for a component of the path prefix, or the
object exists and the process does not have appropriate access rights.
.It Bq Er EINVAL
Argument
.Va buf_p
cannot be translated into an ACL.
.It Bq Er ENOMEM
The ACL working storage requires more memory than is allowed by the
hardware or system-imposed memory management constraints.
.El
.Sh SEE ALSO
.Xr acl 3 ,
.Xr acl_free 3 ,
.Xr acl_get 3 ,
.Xr acl_to_text 3 ,
.Xr posix1e 3
.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.
.Fn acl_from_text
and
.Fn acl_to_text
rely on the
.Xr getpwent 3
library calls to manage username and uid mapping, as well as the
.Xr getgrent 3
library calls to manage groupname and gid mapping. These calls are not
thread safe, and so transitively, neither are
.Fn acl_from_text
and
.Fn acl_to_text .
These functions may also interfere with stateful
calls associated with the
.Fn getpwent
and
.Fn getgrent
calls.

135
lib/libc/posix1e/acl_get.3 Normal file
View File

@ -0,0 +1,135 @@
.\"-
.\" 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_GET 3
.Os FreeBSD 4.0
.Sh NAME
.Fd int
.Nm acl_get_file ,
.Nm acl_get_fd ,
.Nm acl_get_fd_np
.Nd Get an ACL for a file
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/acl.h>
.Ft int
.Fn acl_get_file "const char *path_p" "acl_type_t type"
.Ft int
.Fn acl_get_fd "int fd"
.Ft int
.Fn acl_get_fd_np "int fd" "acl_type_t type"
.Sh DESCRIPTION
The
.Fn acl_get_file ,
.Fn acl_get_fd ,
and
.Fn acl_get_fd_np
each allow the retrieval of an ACL from a file.
.Fn acl_get_file
is a POSIX.1e call that allows the retrieval of a
specified type of ACL from a file by name;
.Fn acl_get_fd
is a POSIX.1e call that allows the retrieval of an ACL of type
ACL_TYPE_ACCESS
from a file descriptor.
.Fn acl_get_fd_np
is a non-portable form of
.Fn acl_get_fd
that allows the retrieval of any type of ACL from a file descriptor.
This function may cause memory to be allocated. The caller should free
any releaseable memory, when the new ACL is no longer required, by calling
.Xr acl_free 3
with the
.Va (void *)acl_t
as an argument.
The ACL in the working storage is an independent copy of the ACL associated
with the object referred to by
.Va fd .
The ACL in the working storage shall not participate in any access control
decisions.
.Sh IMPLEMENTATION NOTES
FreeBSD's support for POSIX.1e interfaces and features is still under
development at this time.
.Sh RETURN VALUES
Upon successful completion, the function shall return a pointer to the ACL
that was retrieved. Otherwise, a value of
.Va (acl_t)NULL
shall be returned, and
.Va errno
shall be set to indicate the error.
.Sh ERRORS
If any of the following conditions occur, the
.Fn acl_get_fd
function shall return a value of
.Va (acl_t)NULL
and set
.Va errno
to the corresponding value:
.Bl -tag -width Er
.It Bq Er EACCES
Search permission is denied for a component of the path prefix, or the
object exists and the process does not have appropriate access rights.
.It Bq Er EBADF
The
.Va fd
argument is not a valid file descriptor.
.It Bq Er EINVAL
The ACL type passed is invalid for this file object.
.It Bq Er ENAMETOOLONG
A component of a pathname exceeded 255 characters, or an
entire path name exceeded 1023 characters.
.It Bq Er ENOENT
The named object does not exist, or the
.Va path_p
argument points to an empty string.
.It Bq Er ENOMEM
Insufficient memory available to fulfill request.
.It Bq Er EOPNOTSUPP
The file system does not support ACL retrieval.
.El
.Sh SEE ALSO
.Xr acl 3 ,
.Xr acl_free 3 ,
.Xr acl_get 3 ,
.Xr acl_set 3 ,
.Xr posix1e 3
.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.

100
lib/libc/posix1e/acl_init.3 Normal file
View File

@ -0,0 +1,100 @@
.\"-
.\" 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_INIT 3
.Os FreeBSD 4.0
.Sh NAME
.Nm acl_init
.Nd Initialize ACL working storage
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/acl.h>
.Ft acl_t
.Fn acl_init "int count"
.Sh DESCRIPTION
The
.Fn acl_init
function allocates and initializes the working storage for an ACL of at
least
.Va count
ACL entries. A pointer to the working storage is returned. The working
storage allocated to contain the ACL is freed by a call to
.Xr acl_free 3 .
When the area is first allocated, it shall contain an an ACL that contains
no ACL entries.
This function may cause memory to be allocated. Teh caller should free any
releaseable memory, when the new ACL is no longer required, by calling
.Xr acl_free 3
with the
.Va (void*)acl_t
as an argument.
.Sh IMPLEMENTATION NOTES
FreeBSD's support for POSIX.1e interfaces and features is still under
development at this time.
.Sh RETURN VALUES
Upon successful completion, this function shall return a pointer to the
working storage. Otherwise, a value of
.Va (acl_t)NULL
shall be returned, and
.Va errno
shall be set to indicate the error.
.Sh ERRORS
If any of the following conditions occur, the
.Fn acl_init
function shall return a value of
.Va (acl_t)NULL
and set
.Va errno
to the corresponding value:
.Bl -tag -width Er
.It Bq Er EINVAL
The value of count is less than zero.
.It Bq Er ENOMEM
The
.Va acl_t
to be returned requires more memory than is allowed by the hardware or
system-imposed memory management constraints.
.El
.Sh SEE ALSO
.Xr acl 3 ,
.Xr acl_free 3 ,
.Xr posix1e 3
.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.

128
lib/libc/posix1e/acl_set.3 Normal file
View File

@ -0,0 +1,128 @@
.\"-
.\" 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_SET 3
.Os FreeBSD 4.0
.Sh NAME
.Fd int
.Nm acl_set_file ,
.Nm acl_set_fd ,
.Nm acl_set_fd_np
.Nd Get an ACL for a file
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/acl.h>
.Ft int
.Fn acl_set_file "const char *path_p" "acl_type_t type" "acl_t acl"
.Ft int
.Fn acl_set_fd "int fd" "acl_t acl"
.Ft int
.Fn acl_set_fd_np "int fd" "acl_t acl" "acl_type_t type"
.Sh DESCRIPTION
The
.Fn acl_set_file ,
.Fn acl_set_fd ,
and
.Fn acl_set_fd_np
each associate an ACL with an object referred to by
.Va fd
or
.Va path_p .
All except
.Fn acl_set_fd_np
are POSIX.1e calls--
.Fn acl_set_fd
allows only the setting of ACLs of type ACL_TYPE_ACCESS
where as
.Fn acl_set_fd_np
allows the setting of ACLs of any type.
.Sh IMPLEMENTATION NOTES
FreeBSD's support for POSIX.1e interfaces and features is still under
development at this time.
.Sh RETURN VALUES
Upon successfull completion, the function shall return a value of zero.
Otherwise, a value of -1 shall be returned and
.Va errno
shall be set to indicate the error.
.Sh ERRORS
If any of the following conditions occur, these functions shall return
-1 and set
.Va errno
to the corresponding value:
.Bl -tag -width Er
.It Bq Er EACCES
Search permission is denied for a component of the path prefix, or the
object exists and the process does not have appropriate access rights.
.It Bq Er EBADF
The
.Va fd
argument is not a valid file descriptor.
.It Bq Er EINVAL
Argument
.Va acl
does not point to a valid ACL for this object, or the ACL type
specified in
.Va type
is invalid for this object, or both.
.It Bq Er ENAMETOOLONG
A component of a pathname exceeded 255 characters, or an
entire path name exceeded 1023 characters.
.It Bq Er ENOENT
The named object does not exist, or the
.Va path_p
argument points to an empty string.
.It Bq Er ENOMEM
Insufficient memory available to fulfill request.
.It Bq Er ENOSPC
The directory or file system that would contain the new ACL cannot be
extended, or the file system is out of file allocation resources.
.It Bq Er EOPNOTSUPP
The file system does not support ACL retrieval.
.It Bq Er EROFS
This function requires modification of a file system which is currently
read-only.
.El
.Sh SEE ALSO
.Xr acl 3 ,
.Xr acl_delete 3 ,
.Xr acl_get 3 ,
.Xr acl_valid 3 ,
.Xr posix1e 3
.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.

128
lib/libc/posix1e/acl_to_text.3 Normal file
View File

@ -0,0 +1,128 @@
.\"-
.\" 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_TO_TEXT 3
.Os FreeBSD 4.0
.Sh NAME
.Nm acl_to_text
.Nd Convert an ACL to Text
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/acl.h>
.Ft char *
.Fn acl_to_text "acl_t acl" "ssize_t *len_p"
.Sh DESCRIPTION
The
.Fn acl_to_text
function translates the ACL pointed to by argument
.Va acl
into a NULL terminated character string. If the pointer
.Va len_p
is not NULL, then the function shall return the length of the string (not
including the NULL terminator) in the location pointed to by
.Va len_p .
Teh format of the text string returned by
.Fn acl_to_text
shall be the POSIX.1e long ACL form.
This function allocates any memory necessary to contain the string and
returns a pointer to the string. The caller should free any releaseable
memory, when the new string is no longer required, by calling
.Xr acl_free 3
with the
.Va (void*)char
as an argument.
.Sh IMPLEMENTATION NOTES
FreeBSD's support for POSIX.1e interfaces and features is still under
development at this time.
.Sh RETURN VALUES
Upon successful completion, the function shall return a pointer to the
long text form of an ACL. Otherwise, a value of
.Va (char*)NULL
shall be returned and
.Va errno
shall be set to indicate the error.
.Sh ERRORS
If any of the following conditions occur, the
.Fn acl_to_text
function shall return a value of
.Va (acl_t)NULL
and set
.Va errno
to the corresponding value:
.Bl -tag -width Er
.It Bq Er EINVAL
Argument
.Va acl
does not point to a valid ACL.
The ACL denoted by
.Va acl
contains one or more improperly formed ACL entries, or for some other
reason cannot be translated into a text form of an ACL.
.It Bq Er ENOMEM
The character string to be returned requires more memory than is allowed
by the hardware or software-imposed memory management constraints.
.El
.Sh SEE ALSO
.Xr acl 3 ,
.Xr acl_free 3 ,
.Xr acl_from_text 3 ,
.Xr posix1e 3
.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.
.Fn acl_from_text
and
.Fn acl_to_text
rely on the
.Xr getpwent 3
library calls to manage username and uid mapping, as well as the
.Xr getgrent 3
library calls to manage groupname and gid mapping. These calls are not
thread safe, and so transitively, neither are
.Fn acl_from_text
and
.Fn acl_to_text .
These functions may also interfere with stateful
calls associated with the
.Fn getpwent
and
.Fn getgrent
calls.

143
lib/libc/posix1e/acl_valid.3 Normal file
View File

@ -0,0 +1,143 @@
.\"-
.\" 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_VALID 3
.Os FreeBSD 4.0
.Sh NAME
.Fd int
.Nm acl_valid ,
.Nm acl_valid_fd_np ,
.Nm acl_valid_file_np
.Nd Validate an ACL
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/acl.h>
.Ft int
.Fn acl_valid "acl_t acl"
.Ft int
.Fn acl_valid_fd_np "int fd" "acl_type_t type" "acl_t acl"
.Ft int
.Fn acl_valid_file_np "const char *path_p" "acl_type_t type" "acl_t acl"
.Sh DESCRIPTION
These functions check that the ACL referred to by the argument
.Va acl
is valid. The POSIX.1e routine,
.Fn acl_valid ,
checks this validity only with POSIX.1e ACL semantics, and irrespective
of the context in which the ACL is to be used. The non-portable forms,
.Fn acl_valid_fd_np
and
.Fn acl_valid_file_np ,
allow an ACL to be checked in the context of a specific acl type,
.Va type ,
and file system object. In environments where additional ACL types are
supported than just POSIX.1e, this makes more sense.
For POSIX.1e semantics, the checks include:
.Bd -literal -offset indent
The three required entries (ACL_USER_OBJ, ACL_GROUP_OBJ,
and ACL_OTHER) shall exist exactly once in the ACL. If
the ACL contains any ACL_USER, ACL_GROUP, or any other
implementation-defined entries in the file group class
then one ACL_MASK entry shall also be required. The ACL
shall contain at most on ACL_MASK entry.
The qualifier field shall be unique among all entries of
the same POSIX.1e ACL facility defined tag type. The
tag type field shall contain valid values including any
implementatino-defined values. Validation of the values
of the qualifier field is implementation-defined.
.Ed
The POSIX.1e
.Fn acl_valid
function may reorder the ACL for the purposes of verification; the
non-portable validation functions will not.
.Sh IMPLEMENTATION NOTES
FreeBSD's support for POSIX.1e interfaces and features is still under
development at this time.
.Sh RETURN VALUES
Upon successfull completion, the function shall return a value of zero.
Otherwise, a value of -1 shall be returned and
.Va errno
shall be set to indicate the error.
.Sh ERRORS
If any of the following conditions occur, these functions shall return
-1 and set
.Va errno
to the corresponding value:
.Bl -tag -width Er
.It Bq Er EACCES
Search permission is denied for a component of the path prefix, or the
object exists and the process does not have appropriate access rights.
.It Bq Er EBADF
The
.Va fd
argument is not a valid file descriptor.
.It Bq Er EINVAL
Argument
.Va acl
does not point to a valid ACL.
One or more of the required ACL entries is not present in
.Va acl .
The ACL contains entries that are not unique.
The file system rejects the ACL based on fs-specific semantics issues.
.It Bq Er ENAMETOOLONG
A component of a pathname exceeded 255 characters, or an
entire path name exceeded 1023 characters.
.It Bq Er ENOENT
The named object does not exist, or the
.Va path_p
argument points to an empty string.
.It Bq Er ENOMEM
Insufficient memory available to fulfill request.
.It Bq Er EOPNOTSUPP
The file system does not support ACL retrieval.
.El
.Sh SEE ALSO
.Xr acl 3 ,
.Xr acl_get 3 ,
.Xr acl_init 3 ,
.Xr acl_set 3 ,
.Xr posix1e 3
.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.

11
lib/libc/posix1e/acl_valid.c
View File

@ -41,12 +41,11 @@
*
* Implemented by calling the acl_check routine in acl_support, which
* requires ordering. We call acl_support's acl_sort to make this
* true.
*
* POSIX.1e allows acl_valid() to reorder the ACL as it sees fit.
* true. POSIX.1e allows acl_valid() to reorder the ACL as it sees fit.
*
* This call is deprecated, as it doesn't ask whether the ACL is valid
* for a particular target.
* for a particular target. However, this call is standardized, unlike
* the other two forms.
*/
int
acl_valid(acl_t acl)
@ -65,7 +64,7 @@ acl_valid(acl_t acl)
int
acl_valid_file(const char *pathp, acl_type_t type, acl_t acl)
acl_valid_file_np(const char *pathp, acl_type_t type, acl_t acl)
{
int error;
@ -82,7 +81,7 @@ acl_valid_file(const char *pathp, acl_type_t type, acl_t acl)
int
acl_valid_fd(int fd, acl_type_t type, acl_t acl)
acl_valid_fd_np(int fd, acl_type_t type, acl_t acl)
{
int error;

2
lib/libc/posix1e/posix1e.3
View File

@ -54,6 +54,8 @@ operating system. 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.
Available API calls relating to ACLs are described in detail in
.Xr acl 3 .
The patches supporting other POSIX.1e features are not available in the
base operating system at this time--however, more information on them

24
lib/libposix1e/Makefile
View File

@ -11,6 +11,28 @@ SRCS+= acl_delete.c \
acl_to_text.c \
acl_valid.c
MAN3= posix1e.3
MAN3= acl.3 \
acl_delete.3 \
acl_dup.3 \
acl_free.3 \
acl_from_text.3 \
acl_get.3 \
acl_init.3 \
acl_set.3 \
acl_to_text.3 \
acl_valid.3 \
posix1e.3
MLINKS+=acl_delete.3 acl_delete_def_file.3 \
acl_delete.3 acl_delete_file_np.3 \
acl_delete.3 acl_delete_fd_np.3 \
acl_get.3 acl_get_file.3 \
acl_get.3 acl_get_fd.3 \
acl_get.3 acl_get_fd_np.3 \
acl_set.3 acl_set_file.3 \
acl_set.3 acl_set_fd.3 \
acl_set.3 acl_set_fd_np.3 \
acl_valid.3 acl_valid_file_np.3 \
acl_valid.3 acl_valid_fd_np.3
.include <bsd.lib.mk>

171
lib/libposix1e/acl.3 Normal file
View File

@ -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.

120
lib/libposix1e/acl_delete.3 Normal file
View File

@ -0,0 +1,120 @@
.\"-
.\" 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_DELETE 3
.Os FreeBSD 4.0
.Sh NAME
.Nm acl_delete_def_file ,
.Nm acl_delete_file_np ,
.Nm acl_delete_fd_np
.Nd Delete an ACL from a file
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/acl.h>
.Ft int
.Fn acl_delete_def_file "const char *path_p"
.Ft int
.Fn acl_delete_file_np "const char *path_p" "acl_type_t type"
.Ft int
.Fn acl_delete_fd_np "int filedes" "acl_type_t type"
.Sh DESCRIPTION
The
.Fn acl_delete_def_file ,
.Fn acl_delete_file_np ,
and
.Fn acl_delete_fd_np
each allow the deletion of an ACL from a file.
.Fn acl_delete_def_file
is a POSIX.1e call that deletes the default ACL from a file (normally a
directory) by name; the other two calls are non-portable extensions that
allow deleting of arbitrary ACL types from a file/directory by either path
name, or by file descriptor.
.Sh IMPLEMENTATION NOTES
FreeBSD's support for POSIX.1e interfaces and features is still under
development at this time.
.Sh RETURN VALUES
In the event of success, 0 is returned. In the event of failure, -1 is
returned, and
.Va errno
is set to indicate the error.
.Sh ERRORS
If any of the following conditions occur, these functions shall return -1
and set
.Va errno
to teh corresponding value:
.Bl -tag -width Er
.It Bq Er EACCES
Search permission is denied for a component of the path prefix, or the
object exists and the process does not have appropriate access rights.
.It Bq Er EBADF
The
.Va fd
argument is not a valid file descriptor.
.It Bq Er EINVAL
The ACL type passed is invalid for this file object.
.It Bq Er ENAMETOOLONG
A component of a pathname exceeded 255 characters, or an
entire path name exceeded 1023 characters.
.It Bq Er ENOENT
The named object does not exist, or the
.Va path_p
argument points to an empty string.
.It Bq Er ENOMEM
Insufficient memory available to fulfill request.
.It Bq Er ENOTDIR
A component of the path prefix is not a directory.
Argument
.Va path_p
must be a directory, and is not.
.It Bq Er EOPNOTSUPP
The file system does not support ACL deletion.
.It Bq Er EPERM
The process does not have appropriate privilege to perform the operation
to delete an ACL.
.It Bq Er EROFS
The file system is read-only.
.El
.Sh SEE ALSO
.Xr acl 3 ,
.Xr acl_get 3 ,
.Xr acl_set 3 ,
.Xr posix1e 3
.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.

101
lib/libposix1e/acl_dup.3 Normal file
View File

@ -0,0 +1,101 @@
.\"-
.\" 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_DUP 3
.Os FreeBSD 4.0
.Sh NAME
.Nm acl_dup
.Nd Duplicate an ACL
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/acl.h>
.Ft acl_t
.Fn acl_dup "acl_t acl"
.Sh DESCRIPTION
The
.Fn acl_dup
function returns a pointer to a copy of the ACL pointed to by the argument
.Va acl .
This function may cause memory to be allocated. Teh caller should free any
releaseable memory, when the new ACL is no longer required, by calling
.Xr acl_free 3
with the
.Va (void*)acl_t
as an argument.
Any existing ACL pointers that refer to the ACL referred to by
.Va acl
shall continue to refer to the ACL.
.Sh IMPLEMENTATION NOTES
FreeBSD's support for POSIX.1e interfaces and features is still under
development at this time.
.Sh RETURN VALUES
Upon successful completion, this function shall return a pointer to the
duplicate ACL. Otherwise, a value of
.Va (acl_t)NULL
shall be returned, and
.Va errno
shall be set to indicate the error.
.Sh ERRORS
If any of the following conditions occur, the
.Fn acl_init
function shall return a value of
.Va (acl_t)NULL
and set
.Va errno
to the corresponding value:
.Bl -tag -width Er
.It Bq Er EINVAL
Argument
.Va acl
does not point to a valid ACL.
.It Bq Er ENOMEM
The
.Va acl_t
to be returned requires more memory than is allowed by the hardware or
system-imposed memory management constraints.
.El
.Sh SEE ALSO
.Xr acl 3 ,
.Xr acl_free 3 ,
.Xr acl_get 3 ,
.Xr posix1e 3
.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.

85
lib/libposix1e/acl_free.3 Normal file
View File

@ -0,0 +1,85 @@
.\"-
.\" 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_FREE 3
.Os FreeBSD 4.0
.Sh NAME
.Nm acl_free
.Nd Free ACL working state
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/acl.h>
.Ft int
.Fn acl_free "void *obj_p"
.Sh DESCRIPTION
The
.Fn acl_free
call allows the freeing of ACL working space, such as is allocated by
.Xr acl_dup 3 ,
or
.Xr acl_from_text 3 .
.Sh IMPLEMENTATION NOTES
FreeBSD's support for POSIX.1e interfaces and features is still under
development at this time.
.Sh RETURN VALUES
In the event of success, 0 is returned. In the event of failure, -1 is
returned, and
.Va errno
is set to indicate the error.
.Sh ERRORS
If any of the following conditions occur, the
.Fn acl_free
function shall return -1 and set
.Va errno
to the corresponding value:
.Bl -tag -width Er
.It Bq Er EINVAL
The value of the
.Va obj_p
argument is invalid.
.El
.Sh SEE ALSO
.Xr acl 3 ,
.Xr acl_dup 3 ,
.Xr acl_from_text 3 ,
.Xr acl_get 3 ,
.Xr acl_init 3 ,
.Xr posix1e 3
.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.

121
lib/libposix1e/acl_from_text.3 Normal file
View File

@ -0,0 +1,121 @@
.\"-
.\" 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_FROM_TEXT 3
.Os FreeBSD 4.0
.Sh NAME
.Nm acl_from_text
.Nd Create an ACL from text
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/acl.h>
.Ft int
.Fn acl_from_text "const char *buf_p"
.Sh DESCRIPTION
The
.Fn acl_from_text
function converts the text form of an ACL referred to by
.Va buf_p
into the internal working structure for ACLs, appropriate for applying to
files or manipulating.
This function may cause memory to be allocated. The caller should free any
releasable memory, when the new ACL is no longer required, by calling
.Xr acl_free 3
with the
.Va (void *)acl_t
as an argument.
.Sh IMPLEMENTATION NOTES
FreeBSD's support for POSIX.1e interfaces and features is still under
development at this time.
.Sh RETURN VALUES
Upon successful completion, the function shall return a pointer to the
internal representation of the ACL in working storage. Otherwise, a value
of
.Va (acl_t)NULL
shall be returned, and
.Va errno
shall be set to indicate the error.
.Sh ERRORS
If any of the following conditions occur, the
.Fn acl_from_text
function shall return a value of
.Va (acl_t)NULL
and set
.Va errno
to the corresponding value:
.Bl -tag -width Er
.It Bq Er EACCES
Search permission is denied for a component of the path prefix, or the
object exists and the process does not have appropriate access rights.
.It Bq Er EINVAL
Argument
.Va buf_p
cannot be translated into an ACL.
.It Bq Er ENOMEM
The ACL working storage requires more memory than is allowed by the
hardware or system-imposed memory management constraints.
.El
.Sh SEE ALSO
.Xr acl 3 ,
.Xr acl_free 3 ,
.Xr acl_get 3 ,
.Xr acl_to_text 3 ,
.Xr posix1e 3
.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.
.Fn acl_from_text
and
.Fn acl_to_text
rely on the
.Xr getpwent 3
library calls to manage username and uid mapping, as well as the
.Xr getgrent 3
library calls to manage groupname and gid mapping. These calls are not
thread safe, and so transitively, neither are
.Fn acl_from_text
and
.Fn acl_to_text .
These functions may also interfere with stateful
calls associated with the
.Fn getpwent
and
.Fn getgrent
calls.

135
lib/libposix1e/acl_get.3 Normal file
View File

@ -0,0 +1,135 @@
.\"-
.\" 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_GET 3
.Os FreeBSD 4.0
.Sh NAME
.Fd int
.Nm acl_get_file ,
.Nm acl_get_fd ,
.Nm acl_get_fd_np
.Nd Get an ACL for a file
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/acl.h>
.Ft int
.Fn acl_get_file "const char *path_p" "acl_type_t type"
.Ft int
.Fn acl_get_fd "int fd"
.Ft int
.Fn acl_get_fd_np "int fd" "acl_type_t type"
.Sh DESCRIPTION
The
.Fn acl_get_file ,
.Fn acl_get_fd ,
and
.Fn acl_get_fd_np
each allow the retrieval of an ACL from a file.
.Fn acl_get_file
is a POSIX.1e call that allows the retrieval of a
specified type of ACL from a file by name;
.Fn acl_get_fd
is a POSIX.1e call that allows the retrieval of an ACL of type
ACL_TYPE_ACCESS
from a file descriptor.
.Fn acl_get_fd_np
is a non-portable form of
.Fn acl_get_fd
that allows the retrieval of any type of ACL from a file descriptor.
This function may cause memory to be allocated. The caller should free
any releaseable memory, when the new ACL is no longer required, by calling
.Xr acl_free 3
with the
.Va (void *)acl_t
as an argument.
The ACL in the working storage is an independent copy of the ACL associated
with the object referred to by
.Va fd .
The ACL in the working storage shall not participate in any access control
decisions.
.Sh IMPLEMENTATION NOTES
FreeBSD's support for POSIX.1e interfaces and features is still under
development at this time.
.Sh RETURN VALUES
Upon successful completion, the function shall return a pointer to the ACL
that was retrieved. Otherwise, a value of
.Va (acl_t)NULL
shall be returned, and
.Va errno
shall be set to indicate the error.
.Sh ERRORS
If any of the following conditions occur, the
.Fn acl_get_fd
function shall return a value of
.Va (acl_t)NULL
and set
.Va errno
to the corresponding value:
.Bl -tag -width Er
.It Bq Er EACCES
Search permission is denied for a component of the path prefix, or the
object exists and the process does not have appropriate access rights.
.It Bq Er EBADF
The
.Va fd
argument is not a valid file descriptor.
.It Bq Er EINVAL
The ACL type passed is invalid for this file object.
.It Bq Er ENAMETOOLONG
A component of a pathname exceeded 255 characters, or an
entire path name exceeded 1023 characters.
.It Bq Er ENOENT
The named object does not exist, or the
.Va path_p
argument points to an empty string.
.It Bq Er ENOMEM
Insufficient memory available to fulfill request.
.It Bq Er EOPNOTSUPP
The file system does not support ACL retrieval.
.El
.Sh SEE ALSO
.Xr acl 3 ,
.Xr acl_free 3 ,
.Xr acl_get 3 ,
.Xr acl_set 3 ,
.Xr posix1e 3
.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.

100
lib/libposix1e/acl_init.3 Normal file
View File

@ -0,0 +1,100 @@
.\"-
.\" 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_INIT 3
.Os FreeBSD 4.0
.Sh NAME
.Nm acl_init
.Nd Initialize ACL working storage
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/acl.h>
.Ft acl_t
.Fn acl_init "int count"
.Sh DESCRIPTION
The
.Fn acl_init
function allocates and initializes the working storage for an ACL of at
least
.Va count
ACL entries. A pointer to the working storage is returned. The working
storage allocated to contain the ACL is freed by a call to
.Xr acl_free 3 .
When the area is first allocated, it shall contain an an ACL that contains
no ACL entries.
This function may cause memory to be allocated. Teh caller should free any
releaseable memory, when the new ACL is no longer required, by calling
.Xr acl_free 3
with the
.Va (void*)acl_t
as an argument.
.Sh IMPLEMENTATION NOTES
FreeBSD's support for POSIX.1e interfaces and features is still under
development at this time.
.Sh RETURN VALUES
Upon successful completion, this function shall return a pointer to the
working storage. Otherwise, a value of
.Va (acl_t)NULL
shall be returned, and
.Va errno
shall be set to indicate the error.
.Sh ERRORS
If any of the following conditions occur, the
.Fn acl_init
function shall return a value of
.Va (acl_t)NULL
and set
.Va errno
to the corresponding value:
.Bl -tag -width Er
.It Bq Er EINVAL
The value of count is less than zero.
.It Bq Er ENOMEM
The
.Va acl_t
to be returned requires more memory than is allowed by the hardware or
system-imposed memory management constraints.
.El
.Sh SEE ALSO
.Xr acl 3 ,
.Xr acl_free 3 ,
.Xr posix1e 3
.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.

128
lib/libposix1e/acl_set.3 Normal file
View File

@ -0,0 +1,128 @@
.\"-
.\" 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_SET 3
.Os FreeBSD 4.0
.Sh NAME
.Fd int
.Nm acl_set_file ,
.Nm acl_set_fd ,
.Nm acl_set_fd_np
.Nd Get an ACL for a file
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/acl.h>
.Ft int
.Fn acl_set_file "const char *path_p" "acl_type_t type" "acl_t acl"
.Ft int
.Fn acl_set_fd "int fd" "acl_t acl"
.Ft int
.Fn acl_set_fd_np "int fd" "acl_t acl" "acl_type_t type"
.Sh DESCRIPTION
The
.Fn acl_set_file ,
.Fn acl_set_fd ,
and
.Fn acl_set_fd_np
each associate an ACL with an object referred to by
.Va fd
or
.Va path_p .
All except
.Fn acl_set_fd_np
are POSIX.1e calls--
.Fn acl_set_fd
allows only the setting of ACLs of type ACL_TYPE_ACCESS
where as
.Fn acl_set_fd_np
allows the setting of ACLs of any type.
.Sh IMPLEMENTATION NOTES
FreeBSD's support for POSIX.1e interfaces and features is still under
development at this time.
.Sh RETURN VALUES
Upon successfull completion, the function shall return a value of zero.
Otherwise, a value of -1 shall be returned and
.Va errno
shall be set to indicate the error.
.Sh ERRORS
If any of the following conditions occur, these functions shall return
-1 and set
.Va errno
to the corresponding value:
.Bl -tag -width Er
.It Bq Er EACCES
Search permission is denied for a component of the path prefix, or the
object exists and the process does not have appropriate access rights.
.It Bq Er EBADF
The
.Va fd
argument is not a valid file descriptor.
.It Bq Er EINVAL
Argument
.Va acl
does not point to a valid ACL for this object, or the ACL type
specified in
.Va type
is invalid for this object, or both.
.It Bq Er ENAMETOOLONG
A component of a pathname exceeded 255 characters, or an
entire path name exceeded 1023 characters.
.It Bq Er ENOENT
The named object does not exist, or the
.Va path_p
argument points to an empty string.
.It Bq Er ENOMEM
Insufficient memory available to fulfill request.
.It Bq Er ENOSPC
The directory or file system that would contain the new ACL cannot be
extended, or the file system is out of file allocation resources.
.It Bq Er EOPNOTSUPP
The file system does not support ACL retrieval.
.It Bq Er EROFS
This function requires modification of a file system which is currently
read-only.
.El
.Sh SEE ALSO
.Xr acl 3 ,
.Xr acl_delete 3 ,
.Xr acl_get 3 ,
.Xr acl_valid 3 ,
.Xr posix1e 3
.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.

128
lib/libposix1e/acl_to_text.3 Normal file
View File

@ -0,0 +1,128 @@
.\"-
.\" 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_TO_TEXT 3
.Os FreeBSD 4.0
.Sh NAME
.Nm acl_to_text
.Nd Convert an ACL to Text
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/acl.h>
.Ft char *
.Fn acl_to_text "acl_t acl" "ssize_t *len_p"
.Sh DESCRIPTION
The
.Fn acl_to_text
function translates the ACL pointed to by argument
.Va acl
into a NULL terminated character string. If the pointer
.Va len_p
is not NULL, then the function shall return the length of the string (not
including the NULL terminator) in the location pointed to by
.Va len_p .
Teh format of the text string returned by
.Fn acl_to_text
shall be the POSIX.1e long ACL form.
This function allocates any memory necessary to contain the string and
returns a pointer to the string. The caller should free any releaseable
memory, when the new string is no longer required, by calling
.Xr acl_free 3
with the
.Va (void*)char
as an argument.
.Sh IMPLEMENTATION NOTES
FreeBSD's support for POSIX.1e interfaces and features is still under
development at this time.
.Sh RETURN VALUES
Upon successful completion, the function shall return a pointer to the
long text form of an ACL. Otherwise, a value of
.Va (char*)NULL
shall be returned and
.Va errno
shall be set to indicate the error.
.Sh ERRORS
If any of the following conditions occur, the
.Fn acl_to_text
function shall return a value of
.Va (acl_t)NULL
and set
.Va errno
to the corresponding value:
.Bl -tag -width Er
.It Bq Er EINVAL
Argument
.Va acl
does not point to a valid ACL.
The ACL denoted by
.Va acl
contains one or more improperly formed ACL entries, or for some other
reason cannot be translated into a text form of an ACL.
.It Bq Er ENOMEM
The character string to be returned requires more memory than is allowed
by the hardware or software-imposed memory management constraints.
.El
.Sh SEE ALSO
.Xr acl 3 ,
.Xr acl_free 3 ,
.Xr acl_from_text 3 ,
.Xr posix1e 3
.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.
.Fn acl_from_text
and
.Fn acl_to_text
rely on the
.Xr getpwent 3
library calls to manage username and uid mapping, as well as the
.Xr getgrent 3
library calls to manage groupname and gid mapping. These calls are not
thread safe, and so transitively, neither are
.Fn acl_from_text
and
.Fn acl_to_text .
These functions may also interfere with stateful
calls associated with the
.Fn getpwent
and
.Fn getgrent
calls.

143
lib/libposix1e/acl_valid.3 Normal file
View File

@ -0,0 +1,143 @@
.\"-
.\" 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_VALID 3
.Os FreeBSD 4.0
.Sh NAME
.Fd int
.Nm acl_valid ,
.Nm acl_valid_fd_np ,
.Nm acl_valid_file_np
.Nd Validate an ACL
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/acl.h>
.Ft int
.Fn acl_valid "acl_t acl"
.Ft int
.Fn acl_valid_fd_np "int fd" "acl_type_t type" "acl_t acl"
.Ft int
.Fn acl_valid_file_np "const char *path_p" "acl_type_t type" "acl_t acl"
.Sh DESCRIPTION
These functions check that the ACL referred to by the argument
.Va acl
is valid. The POSIX.1e routine,
.Fn acl_valid ,
checks this validity only with POSIX.1e ACL semantics, and irrespective
of the context in which the ACL is to be used. The non-portable forms,
.Fn acl_valid_fd_np
and
.Fn acl_valid_file_np ,
allow an ACL to be checked in the context of a specific acl type,
.Va type ,
and file system object. In environments where additional ACL types are
supported than just POSIX.1e, this makes more sense.
For POSIX.1e semantics, the checks include:
.Bd -literal -offset indent
The three required entries (ACL_USER_OBJ, ACL_GROUP_OBJ,
and ACL_OTHER) shall exist exactly once in the ACL. If
the ACL contains any ACL_USER, ACL_GROUP, or any other
implementation-defined entries in the file group class
then one ACL_MASK entry shall also be required. The ACL
shall contain at most on ACL_MASK entry.
The qualifier field shall be unique among all entries of
the same POSIX.1e ACL facility defined tag type. The
tag type field shall contain valid values including any
implementatino-defined values. Validation of the values
of the qualifier field is implementation-defined.
.Ed
The POSIX.1e
.Fn acl_valid
function may reorder the ACL for the purposes of verification; the
non-portable validation functions will not.
.Sh IMPLEMENTATION NOTES
FreeBSD's support for POSIX.1e interfaces and features is still under
development at this time.
.Sh RETURN VALUES
Upon successfull completion, the function shall return a value of zero.
Otherwise, a value of -1 shall be returned and
.Va errno
shall be set to indicate the error.
.Sh ERRORS
If any of the following conditions occur, these functions shall return
-1 and set
.Va errno
to the corresponding value:
.Bl -tag -width Er
.It Bq Er EACCES
Search permission is denied for a component of the path prefix, or the
object exists and the process does not have appropriate access rights.
.It Bq Er EBADF
The
.Va fd
argument is not a valid file descriptor.
.It Bq Er EINVAL
Argument
.Va acl
does not point to a valid ACL.
One or more of the required ACL entries is not present in
.Va acl .
The ACL contains entries that are not unique.
The file system rejects the ACL based on fs-specific semantics issues.
.It Bq Er ENAMETOOLONG
A component of a pathname exceeded 255 characters, or an
entire path name exceeded 1023 characters.
.It Bq Er ENOENT
The named object does not exist, or the
.Va path_p
argument points to an empty string.
.It Bq Er ENOMEM
Insufficient memory available to fulfill request.
.It Bq Er EOPNOTSUPP
The file system does not support ACL retrieval.
.El
.Sh SEE ALSO
.Xr acl 3 ,
.Xr acl_get 3 ,
.Xr acl_init 3 ,
.Xr acl_set 3 ,
.Xr posix1e 3
.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.

11
lib/libposix1e/acl_valid.c
View File

@ -41,12 +41,11 @@
*
* Implemented by calling the acl_check routine in acl_support, which
* requires ordering. We call acl_support's acl_sort to make this
* true.
*
* POSIX.1e allows acl_valid() to reorder the ACL as it sees fit.
* true. POSIX.1e allows acl_valid() to reorder the ACL as it sees fit.
*
* This call is deprecated, as it doesn't ask whether the ACL is valid
* for a particular target.
* for a particular target. However, this call is standardized, unlike
* the other two forms.
*/
int
acl_valid(acl_t acl)
@ -65,7 +64,7 @@ acl_valid(acl_t acl)
int
acl_valid_file(const char *pathp, acl_type_t type, acl_t acl)
acl_valid_file_np(const char *pathp, acl_type_t type, acl_t acl)
{
int error;
@ -82,7 +81,7 @@ acl_valid_file(const char *pathp, acl_type_t type, acl_t acl)
int
acl_valid_fd(int fd, acl_type_t type, acl_t acl)
acl_valid_fd_np(int fd, acl_type_t type, acl_t acl)
{
int error;

2
lib/libposix1e/posix1e.3
View File

@ -54,6 +54,8 @@ operating system. 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.
Available API calls relating to ACLs are described in detail in
.Xr acl 3 .
The patches supporting other POSIX.1e features are not available in the
base operating system at this time--however, more information on them