PERFORCE change 156382 for review

[Robert Watson]

http://perforce.freebsd.org/chv.cgi?CH=156382

Change 156382 by rwatson at rwatson_freebsd_capabilities on 2009/01/19 12:27:34

	Attempt to sort capability rights alphabetically by name, rather
	than definition order, so that it's easier to find them as a
	reader.

Affected files ...

.. //depot/projects/trustedbsd/capabilities/src/lib/libc/sys/cap_new.2#6 edit

Differences ...

==== //depot/projects/trustedbsd/capabilities/src/lib/libc/sys/cap_new.2#6 (text+ko) ====

@@ -1,5 +1,5 @@
 .\"
-.\" Copyright (c) 2008 Robert N. M. Watson
+.\" Copyright (c) 2008-2009 Robert N. M. Watson
 .\" All rights reserved.
 .\"
 .\" WARNING: THIS IS EXPERIMENTAL SECURITY SOFTWARE THAT MUST NOT BE RELIED
@@ -98,75 +98,41 @@
 .Sh RIGHTS
 The following rights may be specified in a new capability rights mask:
 .Bl -tag -width CAP_EXTATTR_DELETE
-.It Dv CAP_READ
-Allow
-.Xr aio_read 2 ,
-.Xr pread 2 ,
-.Xr read 2 ,
-.Xr recv 2 ,
-.Xr recvfrom 2 ,
-.Xr recvmsg 2 ,
-and related system calls.
-.Pp
-For files and other seekable objects,
-.Dv CAP_SEEK
-may also be required.
-.Pp
-.It Dv CAP_WRITE
-Allow
-.Xr aio_write 2 ,
-.Xr pwrite 2 ,
-.Xr send 2 ,
-.Xr sendmsg 2 ,
-.Xr sendto 2 ,
-.Xr write 2 ,
-and related system calls.
-.Pp
-For files and other seekable objects,
-.Dv CAP_SEEK
-may also be required.
-.Pp
-For
-.Xr sendto 2
-with a non-NULL connection address,
-.Dv CAP_CONNECT
-is also required.
-.It Dv CAP_SEEK
-Permit operations that seek on the file descriptor, such as
-.Xr lseek 2 ,
-but also required for I/O system calls that modify the file offset, such as
-.Xr read 2
-and
-.Xr write 2 .
-.It Dv CAP_GETPEERNAME
+.It Dv CAP_ACCEPT
 Permit
-.Xr getpeername 2 .
-.It Dv CAP_GETSOCKNAME
+.Xr accept 2 .
+.It Dv CAP_ACL_CHECK
+Permit checking of an ACL on a file descriptor; there is no cross-reference
+for this system call.
+.It Dv CAP_ACL_DELETE
 Permit
-.Xr getsockname 2 .
-.It Dv CAP_FCHFLAGS
+.Xr acl_delete_fd_np 2 .
+.It Dv CAP_ACL_GET
 Permit
-.Xr fchflags 2 .
-.It Dv CAP_IOCTL
+.Xr acl_get_fd 2
+and
+.Xr acl_get_fd_np 2 .
+.It Dv CAP_ACL_SET
 Permit
-.Xr ioctl 2 .
-Be aware that this system call has enourmous scope, including potentially
-global scope for some objects.
-.It Dv CAP_FSTAT
+.Xr acl_set_fd 2
+and
+.Xr acl_set_fd_np 2 .
+.It Dv CAP_BIND
 Permit
-.Xr fstat 2 .
-.It Dv CAP_MMAP
-Permit
-.Xr mmap 2 ;
-specific invocations may also require
-.Dv CAP_READ
+.Xr bind 2 .
+Note that sockets can also become bound implicitly as a result of
+.Xr connect 2
 or
-.Dv CAP_WRITE .
-.It Dv CAP_FCNTL
+.Xr send 2 ,
+and that socket options set with
+.Xr setsockopt 2
+may also affect binding behavior.
+.It Dv CAP_CONNECT
 Permit
-.Xr fcntl 2 ;
-be aware that this call provides indirect access to other operations, such as
-.Xr flock 2 .
+.Xr connect 2 ;
+also required for
+.Xr sendto 2
+with a non-NULL destination address.
 .It Dv CAP_EVENT
 Permit
 .Xr select 2 ,
@@ -174,116 +140,81 @@
 and
 .Xr kevent 2
 to be used in monitoring the file descriptor for events.
-.It Dv CAP_FSYNC
+.It Dv CAP_FEXECVE
+Permit
+.Xr fexecve 2 ;
+.Dv CAP_READ
+will also be required.
+.It Dv CAP_EXTATTR_DELETE
+Permit
+.Xr extattr_delete_fd 2 .
+.It Dv CAP_EXTATTR_GET
+Permit
+.Xr extattr_get_fd 2 .
+.It Dv CAP_EXTATTR_LIST
+Permit
+.Xr extattr_list_fd 2 .
+.It Dv CAP_EXTATTR_SET
 Permit
-.Xr aio_fsync 2
-and
-.Xr fsync 2 .
-.Pp
-.It Dv CAP_FCHOWN
+.Xr extattr_set_fd 2 .
+.It Dv CAP_FCHFLAGS
 Permit
-.Xr fchown 2 .
+.Xr fchflags 2 .
 .It Dv CAP_FCHMOD
 Permit
 .Xr fchmod 2 .
-.It Dv CAP_FTRUNCATE
+.It Dv CAP_FCHOWN
+Permit
+.Xr fchown 2 .
+.It Dv CAP_FCNTL
 Permit
-.Xr ftruncate 2 .
+.Xr fcntl 2 ;
+be aware that this call provides indirect access to other operations, such as
+.Xr flock 2 .
 .It Dv CAP_FLOCK
 Permit
 .Xr flock 2
 and related calls.
-.It Dv CAP_FSTATFS
-Permit
-.Xr fstatfs 2 .
-.It Dv CAP_REVOKE
-Permit
-.Xr frevoke 2
-in certain ABI compatibility modes that support this system call.
-.It Dv CAP_FEXECVE
-Permit
-.Xr fexecve 2 ;
-.Dv CAP_READ
-will also be required.
 .It Dv CAP_FPATHCONF
 Permit
 .Xr fpathconf 2 .
-.It Dv CAP_FUTIMES
+.It Dv CAP_FSTAT
 Permit
-.Xr futimes 2 .
-.It Dv CAP_ACL_GET
+.Xr fstat 2 .
+.It Dv CAP_FSTATFS
 Permit
-.Xr acl_get_fd 2
-and
-.Xr acl_get_fd_np 2 .
-.It Dv CAP_ACL_SET
+.Xr fstatfs 2 .
+.It Dv CAP_FSYNC
 Permit
-.Xr acl_set_fd 2
+.Xr aio_fsync 2
 and
-.Xr acl_set_fd_np 2 .
-.It Dv CAP_ACL_DELETE
+.Xr fsync 2 .
+.Pp
+.It Dv CAP_FTRUNCATE
 Permit
-.Xr acl_delete_fd_np 2 .
-.It Dv CAP_ACL_CHECK
-Permit checking of an ACL on a file descriptor; there is no cross-reference
-for this system call.
-.It Dv CAP_EXTATTR_GET
+.Xr ftruncate 2 .
+.It Dv CAP_FUTIMES
 Permit
-.Xr extattr_get_fd 2 .
-.It Dv CAP_EXTATTR_SET
+.Xr futimes 2 .
+.It Dv CAP_GETPEERNAME
 Permit
-.Xr extattr_set_fd 2 .
-.It Dv CAP_EXTATTR_DELETE
+.Xr getpeername 2 .
+.It Dv CAP_GETSOCKNAME
 Permit
-.Xr extattr_delete_fd 2 .
-.It Dv CAP_EXTATTR_LIST
-Permit
-.Xr extattr_list_fd 2 .
-.It Dv CAP_MAC_GET
-Permit
-.Xr mac_get_fd 2 .
-.It Dv CAP_MAC_SET
-Permit
-.Xr mac_set_fd 2 .
-.It Dv CAP_ACCEPT
-Permit
-.Xr accept 2 .
-.It Dv CAP_CONNECT
-Permit
-.Xr connect 2 ;
-also required for
-.Xr sendto 2
-with a non-NULL destination address.
-.It Dv CAP_BIND
-Permit
-.Xr bind 2 .
-Note that sockets can also become bound implicitly as a result of
-.Xr connect 2
-or
-.Xr send 2 ,
-and that socket options set with
-.Xr setsockopt 2
-may also affect binding behavior.
+.Xr getsockname 2 .
 .It Dv CAP_GETSOCKOPT
 Permit
 .Xr getsockopt 2 .
-.It Dv CAP_SETSOCKOPT
+.It Dv CAP_IOCTL
 Permit
-.Xr setsockopt 2 ;
-this controls various aspects of socket behavior and may affect binding,
-connecting, and other behaviors with global scope.
+.Xr ioctl 2 .
+Be aware that this system call has enourmous scope, including potentially
+global scope for some objects.
 .It Dv CAP_LISTEN
 Permit
 .Xr listen 2 ;
 not much use (generally) without
 .Dv CAP_BIND .
-.It Dv CAP_SHUTDOWN
-Permit explicit
-.Xr shutdown 2 ;
-closing the socket will also generally shut down any connections on it.
-.It Dv CAP_PEELOFF
-Permit
-.Xr sctp_peeloff 2 .
 .It Dv CAP_LOOKUP
 Permit the file descriptor to be used as a starting directory for calls such
 as
@@ -295,6 +226,50 @@
 a global name space; see
 .Xr cap_enter 2
 for details.
+.It Dv CAP_MAC_GET
+Permit
+.Xr mac_get_fd 2 .
+.It Dv CAP_MAC_SET
+Permit
+.Xr mac_set_fd 2 .
+.It Dv CAP_MMAP
+Permit
+.Xr mmap 2 ;
+specific invocations may also require
+.Dv CAP_READ
+or
+.Dv CAP_WRITE .
+.Pp
+.It Dv CAP_PEELOFF
+Permit
+.Xr sctp_peeloff 2 .
+.It Dv CAP_READ
+Allow
+.Xr aio_read 2 ,
+.Xr pread 2 ,
+.Xr read 2 ,
+.Xr recv 2 ,
+.Xr recvfrom 2 ,
+.Xr recvmsg 2 ,
+and related system calls.
+.Pp
+For files and other seekable objects,
+.Dv CAP_SEEK
+may also be required.
+.It Dv CAP_REVOKE
+Permit
+.Xr frevoke 2
+in certain ABI compatibility modes that support this system call.
+.It Dv CAP_SEEK
+Permit operations that seek on the file descriptor, such as
+.Xr lseek 2 ,
+but also required for I/O system calls that modify the file offset, such as
+.Xr read 2
+and
+.Xr write 2 .
+.It Dv CAP_SEM_GETVALUE
+Permit
+.Xr sem_getvalue 3 .
 .It Dv CAP_SEM_POST
 Permit
 .Xr sem_post 3 .
@@ -303,9 +278,34 @@
 .Xr sem_wait 3
 and
 .Xr sem_trywait 3 .
-.It Dv CAP_SEM_GETVALUE
+.It Dv CAP_SETSOCKOPT
 Permit
-.Xr sem_getvalue 3 .
+.Xr setsockopt 2 ;
+this controls various aspects of socket behavior and may affect binding,
+connecting, and other behaviors with global scope.
+.It Dv CAP_SHUTDOWN
+Permit explicit
+.Xr shutdown 2 ;
+closing the socket will also generally shut down any connections on it.
+.It Dv CAP_WRITE
+Allow
+.Xr aio_write 2 ,
+.Xr pwrite 2 ,
+.Xr send 2 ,
+.Xr sendmsg 2 ,
+.Xr sendto 2 ,
+.Xr write 2 ,
+and related system calls.
+.Pp
+For files and other seekable objects,
+.Dv CAP_SEEK
+may also be required.
+.Pp
+For
+.Xr sendto 2
+with a non-NULL connection address,
+.Dv CAP_CONNECT
+is also required.
 .El
 .Sh CAVEAT
 The