From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-4.2 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,FREEMAIL_FORGED_FROMDOMAIN,FREEMAIL_FROM, HEADER_FROM_DIFFERENT_DOMAINS,MAILING_LIST_MULTI,NICE_REPLY_A,SPF_HELO_NONE, SPF_PASS,URIBL_BLOCKED,USER_AGENT_SANE_1 autolearn=no autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 6A189C433E0 for ; Thu, 28 Jan 2021 20:31:25 +0000 (UTC) Received: from kanga.kvack.org (kanga.kvack.org [205.233.56.17]) by mail.kernel.org (Postfix) with ESMTP id C007060235 for ; Thu, 28 Jan 2021 20:31:24 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org C007060235 Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=gmail.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=owner-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix) id 24A516B0005; Thu, 28 Jan 2021 15:31:24 -0500 (EST) Received: by kanga.kvack.org (Postfix, from userid 40) id 1D5246B0006; Thu, 28 Jan 2021 15:31:24 -0500 (EST) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 0751E6B006C; Thu, 28 Jan 2021 15:31:24 -0500 (EST) X-Delivered-To: linux-mm@kvack.org Received: from forelay.hostedemail.com (smtprelay0093.hostedemail.com [216.40.44.93]) by kanga.kvack.org (Postfix) with ESMTP id E0E4A6B0005 for ; Thu, 28 Jan 2021 15:31:23 -0500 (EST) Received: from smtpin23.hostedemail.com (10.5.19.251.rfc1918.com [10.5.19.251]) by forelay03.hostedemail.com (Postfix) with ESMTP id AA5488249980 for ; Thu, 28 Jan 2021 20:31:23 +0000 (UTC) X-FDA: 77756328846.23.light73_470778f275a2 Received: from filter.hostedemail.com (10.5.16.251.rfc1918.com [10.5.16.251]) by smtpin23.hostedemail.com (Postfix) with ESMTP id 8791837606 for ; Thu, 28 Jan 2021 20:31:23 +0000 (UTC) X-HE-Tag: light73_470778f275a2 X-Filterd-Recvd-Size: 8119 Received: from mail-wm1-f48.google.com (mail-wm1-f48.google.com [209.85.128.48]) by imf16.hostedemail.com (Postfix) with ESMTP for ; Thu, 28 Jan 2021 20:31:22 +0000 (UTC) Received: by mail-wm1-f48.google.com with SMTP id y187so5588286wmd.3 for ; Thu, 28 Jan 2021 12:31:22 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=cc:subject:to:references:from:message-id:date:user-agent :mime-version:in-reply-to:content-language:content-transfer-encoding; bh=lIO5kM+zDyYDd38SsYlTwtI8yepYfulfKs7DP0doKqU=; b=syRrrZb0JaALX1sz2rUrO22yiN5ffT0thUKVDW7NM/29x5HYSWhgb2aLQhdAO59sYM 4nZSHOhVo2UOBYI5cpz5WB09gqJ4MurLALRxR791BzLKluSZUld7QV9H4qSeGrZItMvS Tt79TKd8Ego/XtCAS5Te2sGhJJQ+UG8l/54OukZGuqCxZIB+qi8uh5GieSAFR5ORh8eC Ye7HKwSodsLROPjaJqCwxK5GOXBzKK3DUQ7f50X/4jJ+Bv5SJjMtM8Cuxezo5XUgYAcn q48YAAN+pZcBhUW4rmarBxf2Umk1F4+yRmJPtIIQKx1Z9yuVnONQw3yd2Az0hHDIZJDt 2auw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:cc:subject:to:references:from:message-id:date :user-agent:mime-version:in-reply-to:content-language :content-transfer-encoding; bh=lIO5kM+zDyYDd38SsYlTwtI8yepYfulfKs7DP0doKqU=; b=ZE1vvL6k9YvgrScnLMPjCzFc5Guay2GWKF4/OLjNvujv7Ofqfxdw8WKkZH8b9zxDlS ++vIwOFDhYgLIicc3LyfmTXNCYaIeqG0eua6K1uHgkA4J4+YPO2A/uaPiJBGTRJOeeCF s8C/qRagwoX/vVbJNy4+g6g3q+8sM3lI9ggsLa/tDpDp7K/czTaoeBBz6CDKvE/e6ykl lXhI9cWVZgajWjHmpLEjAnftMhf1DF/X4a8eLteGmXfqpJDwH0kUWonivGI+WtyR2hJC nG/Oxn0cSJjqBMThXMBxujloMda+fe3k83jFijhE9aYiLGUnB667GBvbqyega+3uMtJ5 wGkA== X-Gm-Message-State: AOAM532NQLzCLSvpxGxCpU0zozlDM0O9du43MvqTtLfzXPJefgTs+mPI Nu7zRAW7kC06g7+b7HADc6A= X-Google-Smtp-Source: ABdhPJz35IIaCFuBWIp85fYEBgf494zrQNqYq+/SP3Pr7n7zye6oMIunw2HLsGbqqpCO9tQtsuyQrA== X-Received: by 2002:a05:600c:24b:: with SMTP id 11mr840992wmj.17.1611865881702; Thu, 28 Jan 2021 12:31:21 -0800 (PST) Received: from ?IPv6:2a02:2455:e0:e000:3005:efab:c884:ced0? ([2a02:2455:e0:e000:3005:efab:c884:ced0]) by smtp.gmail.com with ESMTPSA id z63sm6975204wme.8.2021.01.28.12.31.19 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Thu, 28 Jan 2021 12:31:20 -0800 (PST) Cc: mtk.manpages@gmail.com, linux-man , Andrew Morton , Jann Horn , Kees Cook , Jeffrey Vander Stoep , Minchan Kim , Michal Hocko , Shakeel Butt , David Rientjes , =?UTF-8?Q?Edgar_Arriaga_Garc=c3=ada?= , Tim Murray , Linux-MM , SElinux list , linux-security-module , Linux API , lkml , Android Kernel Team Subject: Re: [PATCH 1/1] process_madvise.2: Add process_madvise man page To: Suren Baghdasaryan References: <20210120202337.1481402-1-surenb@google.com> From: "Michael Kerrisk (man-pages)" Message-ID: <6cd84701-fb65-7aa0-38db-b69fe5748754@gmail.com> Date: Thu, 28 Jan 2021 21:31:19 +0100 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:78.0) Gecko/20100101 Thunderbird/78.6.0 MIME-Version: 1.0 In-Reply-To: Content-Type: text/plain; charset=utf-8 Content-Language: en-US Content-Transfer-Encoding: 7bit X-Bogosity: Ham, tests=bogofilter, spamicity=0.000000, version=1.2.4 Sender: owner-linux-mm@kvack.org Precedence: bulk X-Loop: owner-majordomo@kvack.org List-ID: 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) > 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 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/