From: "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>
To: Suren Baghdasaryan <surenb@google.com>
Cc: mtk.manpages@gmail.com, linux-man <linux-man@vger.kernel.org>,
"Andrew Morton" <akpm@linux-foundation.org>,
"Jann Horn" <jannh@google.com>,
"Kees Cook" <keescook@chromium.org>,
"Jeffrey Vander Stoep" <jeffv@google.com>,
"Minchan Kim" <minchan@kernel.org>,
"Michal Hocko" <mhocko@suse.com>,
"Shakeel Butt" <shakeelb@google.com>,
"David Rientjes" <rientjes@google.com>,
"Edgar Arriaga García" <edgararriaga@google.com>,
"Tim Murray" <timmurray@google.com>,
Linux-MM <linux-mm@kvack.org>,
"SElinux list" <selinux@vger.kernel.org>,
linux-security-module <linux-security-module@vger.kernel.org>,
"Linux API" <linux-api@vger.kernel.org>,
lkml <linux-kernel@vger.kernel.org>,
"Android Kernel Team" <kernel-team@android.com>
Subject: Re: [PATCH 1/1] process_madvise.2: Add process_madvise man page
Date: Thu, 28 Jan 2021 21:31:19 +0100 [thread overview]
Message-ID: <6cd84701-fb65-7aa0-38db-b69fe5748754@gmail.com> (raw)
In-Reply-To: <CAJuCfpEfMgA6z5S5gmHwJB_3KWwmKKp434GeHheUGF3yC7r01w@mail.gmail.com>
Hello Suren,
On 1/28/21 7:40 PM, Suren Baghdasaryan wrote:
> On Thu, Jan 28, 2021 at 4:24 AM Michael Kerrisk (man-pages)
> <mtk.manpages@gmail.com> wrote:
>>
>> Hello Suren,
>>
>> Thank you for writing this page! Some comments below.
>
> Thanks for the review!
> Couple questions below and I'll respin the new version once they are clarified.
Okay. See below.
>> On Wed, 20 Jan 2021 at 21:36, Suren Baghdasaryan <surenb@google.com> wrote:
>>>
[...]
Thanks for all the acks. That let's me know that you saw what I said.
>>> RETURN VALUE
>>> On success, process_madvise() returns the number of bytes advised. This
>>> return value may be less than the total number of requested bytes, if an
>>> error occurred. The caller should check return value to determine whether
>>> a partial advice occurred.
>>
>> So there are three return values possible,
>
> Ok, I think I see your point. How about this instead:
Well, I'm glad you saw it, because I forgot to finish it. But yes,
you understood what I forgot to say.
> RETURN VALUE
> On success, process_madvise() returns the number of bytes advised. This
> return value may be less than the total number of requested bytes, if an
> error occurred after some iovec elements were already processed. The caller
> should check the return value to determine whether a partial
> advice occurred.
>
> On error, -1 is returned and errno is set appropriately.
We recently standardized some wording here:
s/appropriately/to indicate the error/.
>>> +.PP
>>> +The pointer
>>> +.I iovec
>>> +points to an array of iovec structures, defined in
>>
>> "iovec" should be formatted as
>>
>> .I iovec
>
> I think it is formatted that way above. What am I missing?
But also in "an array of iovec structures"...
> BTW, where should I be using .I vs .IR? I was looking for an answer
> but could not find it.
.B / .I == bold/italic this line
.BR / .IR == alternate bold/italic with normal (Roman) font.
So:
.I iovec
.I iovec , # so that comma is not italic
.BR process_madvise ()
etc.
[...]
>>> +.I iovec
>>> +if one of its elements points to an invalid memory
>>> +region in the remote process. No further elements will be
>>> +processed beyond that point.
>>> +.PP
>>> +Permission to provide a hint to external process is governed by a
>>> +ptrace access mode
>>> +.B PTRACE_MODE_READ_REALCREDS
>>> +check; see
>>> +.BR ptrace (2)
>>> +and
>>> +.B CAP_SYS_ADMIN
>>> +capability that caller should have in order to affect performance
>>> +of an external process.
>>
>> The preceding sentence is garbled. Missing words?
>
> Maybe I worded it incorrectly. What I need to say here is that the
> caller should have both PTRACE_MODE_READ_REALCREDS credentials and
> CAP_SYS_ADMIN capability. The first part I shamelessly copy/pasted
> from https://man7.org/linux/man-pages/man2/process_vm_readv.2.html and
> tried adding the second one to it, obviously unsuccessfully. Any
> advice on how to fix that?
I think you already got pretty close. How about:
[[
Permission to provide a hint to another process is governed by a
ptrace access mode
.B PTRACE_MODE_READ_REALCREDS
check (see
BR ptrace (2));
in addition, the caller must have the
.B CAP_SYS_ADMIN
capability.
]]
[...]
>>> +.TP
>>> +.B ESRCH
>>> +No process with ID
>>> +.I pidfd
>>> +exists.
>>
>> Should this maybe be:
>> [[
>> The target process does not exist (i.e., it has terminated and
>> been waited on).
>> ]]
>>
>> See pidfd_send_signal(2).
>
> I "borrowed" mine from
> https://man7.org/linux/man-pages/man2/process_vm_readv.2.html but
> either one sounds good to me. Maybe for pidfd_send_signal the wording
> about termination is more important. Anyway, it's up to you. Just let
> me know which one to use.
I think the pidfd_send_signal(2) wording fits better.
[...]
Thanks,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
next prev parent reply other threads:[~2021-01-28 20:31 UTC|newest]
Thread overview: 8+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-01-20 20:23 [PATCH 1/1] process_madvise.2: Add process_madvise man page Suren Baghdasaryan
2021-01-25 13:19 ` Michal Hocko
2021-01-26 0:14 ` Suren Baghdasaryan
2021-01-28 12:24 ` Michael Kerrisk (man-pages)
2021-01-28 18:40 ` Suren Baghdasaryan
2021-01-28 20:31 ` Michael Kerrisk (man-pages) [this message]
2021-01-28 20:37 ` Suren Baghdasaryan
2021-01-29 7:15 ` Suren Baghdasaryan
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=6cd84701-fb65-7aa0-38db-b69fe5748754@gmail.com \
--to=mtk.manpages@gmail.com \
--cc=akpm@linux-foundation.org \
--cc=edgararriaga@google.com \
--cc=jannh@google.com \
--cc=jeffv@google.com \
--cc=keescook@chromium.org \
--cc=kernel-team@android.com \
--cc=linux-api@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-man@vger.kernel.org \
--cc=linux-mm@kvack.org \
--cc=linux-security-module@vger.kernel.org \
--cc=mhocko@suse.com \
--cc=minchan@kernel.org \
--cc=rientjes@google.com \
--cc=selinux@vger.kernel.org \
--cc=shakeelb@google.com \
--cc=surenb@google.com \
--cc=timmurray@google.com \
/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 a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).