Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1758141AbaGAOSv (ORCPT ); Tue, 1 Jul 2014 10:18:51 -0400 Received: from mail-la0-f49.google.com ([209.85.215.49]:42462 "EHLO mail-la0-f49.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1757465AbaGAOSs convert rfc822-to-8bit (ORCPT ); Tue, 1 Jul 2014 10:18:48 -0400 MIME-Version: 1.0 In-Reply-To: <20140701091900.GB2242@google.com> References: <1404124096-21445-1-git-send-email-drysdale@google.com> <1404124096-21445-17-git-send-email-drysdale@google.com> <20140701091900.GB2242@google.com> From: Andy Lutomirski Date: Tue, 1 Jul 2014 07:18:26 -0700 Message-ID: Subject: Re: [PATCH 5/5] man-pages: cap_rights_get: retrieve Capsicum fd rights To: David Drysdale Cc: LSM List , "linux-kernel@vger.kernel.org" , Greg Kroah-Hartman , Alexander Viro , Meredydd Luff , Kees Cook , James Morris , Linux API Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8BIT Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On Tue, Jul 1, 2014 at 2:19 AM, David Drysdale wrote: > On Mon, Jun 30, 2014 at 03:28:14PM -0700, Andy Lutomirski wrote: >> On Mon, Jun 30, 2014 at 3:28 AM, David Drysdale wrote: >> > 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 >> >> I assume you mean "up to the initial value of *nioctls elements" or >> something. Can you clarify? >> >> --Andy > > Yeah, that's what I meant. Is this clearer? > > If the ioctls argument is non-NULL, the caller should specify > the size of the provided buffer as the initial value of the > nioctls argument (as a count of the number of ioctl(2) command > values the buffer can hold). On successful completion of the > system call, the ioctls buffer is filled with the ioctl(2) com‐ > mand values, up to maximum of the initial value of nioctls. > Yes. Thanks. --Andy -- Andy Lutomirski AMA Capital Management, LLC -- 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/