Re: [PATCH] prctl.2: Fix typo

enh
2023-10-31T16:20:12Z

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/>