[PATCH 5/6] cap_rights_get.2: retrieve Capsicum fd rights

[David Drysdale <drysdale@google.com>]

Signed-off-by: David Drysdale <drysdale@google.com>
---
 man2/cap_rights_get.2 | 134 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 134 insertions(+)
 create mode 100644 man2/cap_rights_get.2

diff --git a/man2/cap_rights_get.2 b/man2/cap_rights_get.2
new file mode 100644
index 000000000000..d6aa5b88c6af
--- /dev/null
+++ b/man2/cap_rights_get.2
@@ -0,0 +1,134 @@
+.\"
+.\" Copyright (c) 2008-2010 Robert N. M. Watson
+.\" Copyright (c) 2012-2013 The FreeBSD Foundation
+.\" Copyright (c) 2013-2014 Google, Inc.
+.\" All rights reserved.
+.\"
+.\" %%%LICENSE_START(BSD_2_CLAUSE)
+.\" 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.
+.\" %%%LICENSE_END
+.\"
+.TH CAP_RIGHTS_GET 2 2014-05-07 "Linux" "Linux Programmer's Manual"
+.SH NAME
+cap_rights_get \- retrieve Capsicum capability rights
+.SH SYNOPSIS
+.nf
+.B #include <sys/capsicum.h>
+.sp
+.BI "int cap_rights_get(int " fd ", struct cap_rights *" rights ,
+.BI "                   unsigned int *" fcntls ,
+.BI "                   int *" nioctls ", unsigned int *" ioctls );
+.SH DESCRIPTION
+Obtain the current Capsicum capability rights for a file descriptor.
+.PP
+The function will fill the
+.I rights
+argument (if non-NULL) with the primary capability rights of the
+.I fd
+descriptor. The
+.I rights
+field is a
+.I cap_rights
+structure, as described in
+.BR cap_rights_limit (2),
+and can be examined with the
+.BR cap_rights_is_set (3)
+family of functions.  The complete list of primary rights can be found in the
+.BR rights (7)
+manual page.
+.PP
+If the
+.I fcntls
+argument is non-NULL, it will be filled in with a bitmask of allowed
+.BR fcntl (2)
+commands; see
+.BR cap_rights_limit (2)
+for values.  If the file descriptor does not have the
+.B CAP_FCNTL
+primary right, the returned
+.I fcntls
+value will be zero.
+.PP
+If the
+.I nioctls
+argument is non-NULL, it will be filled in with the number of allowed
+.BR ioctl (2)
+commands, or with the value CAP_IOCTLS_ALL to indicate that all
+.BR ioctl (2)
+commands are allowed.  If the file descriptor does not have the
+.B CAP_IOCTL
+primary right, the returned
+.I nioctls
+value will be zero.
+.PP
+If the
+.I ioctls
+argument is non-NULL, the caller should specify the size of the
+provided buffer as the initial value of the
+.I nioctls
+argument (as a count of the number of
+.BR ioctl (2)
+command values the buffer can hold).
+On successful completion of the system call, the
+.I ioctls
+buffer is filled with the
+.BR ioctl (2)
+command values, up to maximum of the initial value of
+.BR nioctls .
+.PP
+If all
+.BR ioctl (2)
+commands are allowed (the
+.B CAP_IOCTL
+primary capability right is assigned to the file descriptor and the
+set of allowed
+.BR ioctl (2)
+commands was never limited for this file descriptor), the
+system call will not modify the buffer pointed to by the
+.I ioctls
+argument.
+.PP
+Capsicum capability rights assigned to a file descriptor can be reduced with the
+.BR cap_rights_limit (2)
+system call.
+.SH RETURN VALUE
+.BR cap_rights_get ()
+returns zero on success. On error, -1 is returned and
+.I errno
+is set appropriately.
+.SH ERRORS
+.TP
+.B EBADF
+.I fd
+isn't a valid open file descriptor.
+.TP
+.B EFAULT
+Invalid pointer argument.
+.SH VERSION
+Capsicum support was added to the kernel in version 3.???.
+.SH SEE ALSO
+.BR cap_enter (2),
+.BR cap_rights_limit (2),
+.BR cap_rights_init (3),
+.BR capsicum (7),
+.BR rights (7)
+
--
2.0.0.526.g5318336