From: enh <enh@google.com>
To: Alejandro Colomar <alx@kernel.org>
Cc: Stefan Puiu <stefan.puiu@gmail.com>,
Bruno Haible <bruno@clisp.org>,
linux-man@vger.kernel.org,
GNU C Library <libc-alpha@sourceware.org>
Subject: Re: [PATCH] prctl.2: Fix typo
Date: Tue, 31 Oct 2023 09:19:56 -0700 [thread overview]
Message-ID: <CAJgzZorygh1++Nk3b+t_DhiROL5PQAme+H-ZaKjW9oscu2=LSg@mail.gmail.com> (raw)
In-Reply-To: <ZUEnQmDDLwwfCd_g@debian>
On Tue, Oct 31, 2023 at 9:12 AM Alejandro Colomar <alx@kernel.org> wrote:
>
> Hi Stefan,
>
> On Tue, Oct 31, 2023 at 04:31:58PM +0200, Stefan Puiu wrote:
> > Hi Alex and Bruno,
> >
> > On Tue, Oct 31, 2023 at 4:06 PM Alejandro Colomar <alx@kernel.org> wrote:
> > >
> > > Hi Bruno,
> > >
> > > On Sun, Oct 29, 2023 at 09:51:55PM +0100, Bruno Haible wrote:
> > > > The synopsis of the prctl.2 page has:
> > > >
> > > > int prctl(int option, ...
> > > >
> > > > This makes no sense, because
> > > > - the first argument is not optional; it is mandatory.
> > > > - the title of the page is "operations on a process or thread".
> > > >
> > > > It is thus clear that the first argument indicates the operation to perform.
> > > >
> > > > Find attached the correction.
> > >
> > > Agree. I've seen there are other similarly incorrect uses of the word
> > > "option" where "operation" should have been used in the same page (but
> > > there are some that are correctly used). Would you mind checking the
> > > entire page for those other replacements?
> >
> > Hmm, 'option' is not the same as 'optional'. I guess the first
>
> Yes, I don't think it means optional, but rather a choice from all the
> available operations. However, "operation" would be a more precise
> name.
>
> > parameter can be seen as an 'option' passed to prctl() along with some
> > other parameters, right?
> >
> > Also, there are multiple occurrences of 'option' in the page (e.g.
> > 'This option is mainly intended...'), so only changing the argument
> > name would introduce an inconsistency in the page. The argument is
>
> Yes, I think we should also update those when they refer to the first
> argument, that is, the operation that prctl(2) will perform.
>
> > also called '__option' in glibc headers on my system (in
> > /usr/include/x86_64-linux-gnu/sys/prctl.h):
> >
> > /* Control process execution. */
> > #ifndef __USE_TIME_BITS64
> > extern int prctl (int __option, ...) __THROW;
> > #else
> > # ifdef __REDIRECT
> > extern int __REDIRECT_NTH (prctl, (int __option, ...), __prctl_time64);
>
> I've CCed glibc in case they want to rename it too.
>
> >
> > So, I would say I'm not sure this improves things.
>
> I think a consistent use of operation instead of option would improve
> things. We just need to make sure it's consistent.
i certainly like that idea philosophically --- i actually tried to use
the minimal number of different words when naming arguments in
bionic's headers, to minimize the number of words folks who don't
speak english would need to learn.
looking at man7, i note that ioctl() and ptrace() have "request".
fcntl() has "command". flock() has "operation".
> Cheers,
> Alex
>
> >
> > Just my 2 cents,
> > Stefan.
>
> --
> <https://www.alejandro-colomar.es/>
next prev parent reply other threads:[~2023-10-31 16:20 UTC|newest]
Thread overview: 26+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-10-29 20:51 [PATCH] prctl.2: Fix typo Bruno Haible
2023-10-31 12:40 ` Alejandro Colomar
2023-10-31 14:31 ` Stefan Puiu
2023-10-31 16:11 ` Alejandro Colomar
2023-10-31 16:19 ` enh [this message]
2023-10-31 18:40 ` Alejandro Colomar
2023-10-31 19:15 ` enh
2023-10-31 21:23 ` Alejandro Colomar
2023-11-01 0:37 ` enh
2023-11-01 10:16 ` Alejandro Colomar
2024-03-03 12:15 ` [PATCH 0/2] Use terms consistently in function parameter names Alejandro Colomar
2024-03-03 12:15 ` [PATCH 1/2] man*/: epoll_*(), fcntl(), flock(), ioctl(), msgctl(), *prctl(), ptrace(), quotactl(), reboot(), semctl(), shmctl(), lockf(): Consistently use 'op' and 'operation' Alejandro Colomar
2024-03-05 18:12 ` Alejandro Colomar
2024-03-05 19:19 ` enh
2024-03-03 12:15 ` [PATCH 2/2] clock_nanosleep.2, nanosleep.2: Use 'duration' rather than 'request' Alejandro Colomar
2024-03-03 12:45 ` Bruno Haible
2024-03-03 12:55 ` Alejandro Colomar
2024-03-03 13:02 ` [PATCH v2 2/2] " Alejandro Colomar
2024-03-05 0:18 ` [PATCH 2/2] clock_nanosleep.2, " enh
2024-03-05 0:34 ` Alejandro Colomar
2024-03-05 0:56 ` enh
2024-03-05 1:11 ` Alejandro Colomar
2024-03-05 1:26 ` [PATCH v3 3/3] clock_nanosleep.2: Use 't' " Alejandro Colomar
2024-03-05 22:22 ` [PATCH 2/2] clock_nanosleep.2, nanosleep.2: Use 'duration' " enh
2023-10-31 17:08 ` [PATCH] prctl.2: Fix typo Bruno Haible
2023-10-31 21:20 ` Alejandro Colomar
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='CAJgzZorygh1++Nk3b+t_DhiROL5PQAme+H-ZaKjW9oscu2=LSg@mail.gmail.com' \
--to=enh@google.com \
--cc=alx@kernel.org \
--cc=bruno@clisp.org \
--cc=libc-alpha@sourceware.org \
--cc=linux-man@vger.kernel.org \
--cc=stefan.puiu@gmail.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 read-only IMAP folder(s) and NNTP newsgroup(s).