From: Al Viro <viro@zeniv.linux.org.uk>
To: Edwin Zimmerman <edwin@211mainstreet.net>
Cc: 'Denis Efremov' <efremov@ispras.ru>,
'Casey Schaufler' <casey@schaufler-ca.com>,
"'Eric W. Biederman'" <ebiederm@xmission.com>,
'Eric Paris' <eparis@parisplace.org>,
'Kees Cook' <keescook@chromium.org>,
'John Johansen' <john.johansen@canonical.com>,
'James Morris' <jmorris@namei.org>,
"'Serge E. Hallyn'" <serge@hallyn.com>,
'Paul Moore' <paul@paul-moore.com>,
'Kentaro Takeda' <takedakn@nttdata.co.jp>,
linux-security-module@vger.kernel.org,
linux-kernel@vger.kernel.org
Subject: Re: [PATCH 06/10] security: fix documentation for the path_chmod hook
Date: Thu, 7 Feb 2019 14:46:55 +0000 [thread overview]
Message-ID: <20190207144654.GB2217@ZenIV.linux.org.uk> (raw)
In-Reply-To: <000001d4beee$caa8eff0$5ffacfd0$@211mainstreet.net>
On Thu, Feb 07, 2019 at 09:09:49AM -0500, Edwin Zimmerman wrote:
> > > diff --git a/include/linux/lsm_hooks.h b/include/linux/lsm_hooks.h
> > > index cb93972257be..5d6428d0027b 100644
> > > --- a/include/linux/lsm_hooks.h
> > > +++ b/include/linux/lsm_hooks.h
> > > @@ -304,8 +304,7 @@
> > > * Return 0 if permission is granted.
> > > * @path_chmod:
> > > * Check for permission to change DAC's permission of a file or directory.
> > > - * @dentry contains the dentry structure.
> > > - * @mnt contains the vfsmnt structure.
> > > + * @path contains the path structure.
> >
> > May I politely inquire about the value of these comments? How much information
> > is provided by refering to an argument as "the dentry structure" or "the path
> > structure", especially when there's nothing immediately above that would introduce
> > either. "Type of 'dentry' argument is somehow related to struct dentry,
> > try and guess what the value might be - we don't care, we just need every
> > argument commented"?
> >
> > Who needs that crap in the first place?
>
> The comments fill a valuable place to folks like me who are new to the linux security modules.
> In my spare time, I'm writing a new LSM specifically geared for parental controls uses, and the
> comments in lsm_hooks.h have helped me out more than once. Perhaps the comments could
> be inproved by changing them to something like this:
> "@[arg] contains the [type] structure, defined in linux/[?].h"
Um... The _type_ of argument is visible in declaration already;
it doesn't say a damn thing about the value of that argument.
In this particular case, dentry/mnt pair (whichever way it gets
passed; struct path is exactly such a pair) is actually used to
specify the location of file or directory in question, but
try to guess that by description given in this "documentation"...
As for "defined in"... that's what grep/ctags/etc. are for.
Again, the useful information about an argument is _what_ gets
passed in it, not just which type it is...
next prev parent reply other threads:[~2019-02-07 14:47 UTC|newest]
Thread overview: 20+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-02-07 12:44 [PATCH 00/10] LSM documentation update Denis Efremov
2019-02-07 12:44 ` [PATCH 01/10] security: fix documentation for the sb_copy_data hook Denis Efremov
2019-02-07 12:44 ` [PATCH 02/10] security: fix documentation for the syslog hook Denis Efremov
2019-02-07 12:44 ` [PATCH 03/10] security: fix documentation for the socket_post_create hook Denis Efremov
2019-02-07 12:44 ` [PATCH 04/10] security: fix documentation for the task_setscheduler hook Denis Efremov
2019-02-07 12:44 ` [PATCH 05/10] security: fix documentation for the socket_getpeersec_dgram hook Denis Efremov
2019-02-07 12:44 ` [PATCH 06/10] security: fix documentation for the path_chmod hook Denis Efremov
2019-02-07 13:49 ` Al Viro
2019-02-07 14:09 ` Edwin Zimmerman
2019-02-07 14:32 ` Stephen Smalley
2019-02-07 14:55 ` Stephen Smalley
2019-02-07 14:46 ` Al Viro [this message]
2019-02-17 18:45 ` efremov
2019-02-07 12:44 ` [PATCH 07/10] security: fix documentation for the audit_* hooks Denis Efremov
2019-02-07 12:44 ` [PATCH 08/10] security: fix documentation for the msg_queue_* hooks Denis Efremov
2019-02-07 12:44 ` [PATCH 09/10] security: fix documentation for the sem_* hooks Denis Efremov
2019-02-07 12:44 ` [PATCH 10/10] security: fix documentation for the shm_* hooks Denis Efremov
2019-02-11 19:28 ` [PATCH 00/10] LSM documentation update Kees Cook
2019-02-17 18:04 ` efremov
2019-02-17 22:15 ` Kees Cook
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20190207144654.GB2217@ZenIV.linux.org.uk \
--to=viro@zeniv.linux.org.uk \
--cc=casey@schaufler-ca.com \
--cc=ebiederm@xmission.com \
--cc=edwin@211mainstreet.net \
--cc=efremov@ispras.ru \
--cc=eparis@parisplace.org \
--cc=jmorris@namei.org \
--cc=john.johansen@canonical.com \
--cc=keescook@chromium.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-security-module@vger.kernel.org \
--cc=paul@paul-moore.com \
--cc=serge@hallyn.com \
--cc=takedakn@nttdata.co.jp \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.