Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1755556AbaF3K3z (ORCPT ); Mon, 30 Jun 2014 06:29:55 -0400 Received: from mail-lb0-f201.google.com ([209.85.217.201]:62034 "EHLO mail-lb0-f201.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1755410AbaF3K2q (ORCPT ); Mon, 30 Jun 2014 06:28:46 -0400 From: David Drysdale To: linux-security-module@vger.kernel.org, linux-kernel@vger.kernel.org, Greg Kroah-Hartman Cc: Alexander Viro , Meredydd Luff , Kees Cook , James Morris , linux-api@vger.kernel.org, David Drysdale Subject: [PATCH 5/5] man-pages: cap_rights_get: retrieve Capsicum fd rights Date: Mon, 30 Jun 2014 11:28:16 +0100 Message-Id: <1404124096-21445-17-git-send-email-drysdale@google.com> X-Mailer: git-send-email 2.0.0.526.g5318336 In-Reply-To: <1404124096-21445-1-git-send-email-drysdale@google.com> References: <1404124096-21445-1-git-send-email-drysdale@google.com> Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Signed-off-by: David Drysdale --- man2/cap_rights_get.2 | 126 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 126 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..966c0ed7e336 --- /dev/null +++ b/man2/cap_rights_get.2 @@ -0,0 +1,126 @@ +.\" +.\" 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 +.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 result 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 +The +.I ioctls +argument (if non-NULL) should point at memory that can hold up to +.I nioctls +values. +The system call populates the provided buffer with up to +.I nioctls +elements, but always returns the total number of +.BR ioctl (2) +commands allowed for the given file descriptor in +.I nioctls +as described above. +.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 -- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/