Issue in man page getent.1

Issue in man page getent.1

[Helge Kreutzmann]

Without further ado, the following was found:

Issue:    No "in succession" here on purpose?

"When no I<key> is provided, use B<sethostent>(3), B<gethostent>(3), and "
"B<endhostent>(3)  to enumerate the hosts database.  When one or more I<key> "
"arguments are provided, pass each I<key> to B<gethostbyaddr>(3)  or "
"B<gethostbyname2>(3), depending on whether a call to B<inet_pton>(3)  "
"indicates that the I<key> is an IPv6 or IPv4 address or not, and display the "
"result."

"When one I<key> is provided, pass the I<key> to B<setnetgrent>(3)  and, "
"using B<getnetgrent>(3)  display the resulting string triple (I<hostname>, "
"I<username>, I<domainname>).  Alternatively, three I<keys> may be provided, "
"which are interpreted as the I<hostname>, I<username>, and I<domainname> to "
"match to a netgroup name via B<innetgr>(3).  Enumeration is not supported on "
"B<netgroup>, so either one or three I<keys> must be provided."

"When no I<key> is provided, use B<setnetent>(3), B<getnetent>(3), and "
"B<endnetent>(3)  to enumerate the networks database.  When one or more "
"I<key> arguments are provided, pass each numeric I<key> to "
"B<getnetbyaddr>(3)  and each nonnumeric I<key> to B<getnetbyname>(3)  and "
"display the result."

"When no I<key> is provided, use B<setpwent>(3), B<getpwent>(3), and "
"B<endpwent>(3)  to enumerate the passwd database.  When one or more I<key> "
"arguments are provided, pass each numeric I<key> to B<getpwuid>(3)  and each "
"nonnumeric I<key> to B<getpwnam>(3)  and display the result."

"When no I<key> is provided, use B<setprotoent>(3), B<getprotoent>(3), and "
"B<endprotoent>(3)  to enumerate the protocols database.  When one or more "
"I<key> arguments are provided, pass each numeric I<key> to "
"B<getprotobynumber>(3)  and each nonnumeric I<key> to B<getprotobyname>(3)  "
"and display the result."

"When no I<key> is provided, use B<setrpcent>(3), B<getrpcent>(3), and "
"B<endrpcent>(3)  to enumerate the rpc database.  When one or more I<key> "
"arguments are provided, pass each numeric I<key> to B<getrpcbynumber>(3)  "
"and each nonnumeric I<key> to B<getrpcbyname>(3)  and display the result."

"When no I<key> is provided, use B<setservent>(3), B<getservent>(3), and "
"B<endservent>(3)  to enumerate the services database.  When one or more "
"I<key> arguments are provided, pass each numeric I<key> to "
"B<getservbynumber>(3)  and each nonnumeric I<key> to B<getservbyname>(3)  "
"and display the result."

Issue in man page getent.1

[Helge Kreutzmann]

Without further ado, the following was found:

Issue:    B<hosts> → B<hosts>(5)

"When no I<key> is provided, use B<sethostent>(3), B<gethostent>(3), and "
"B<endhostent>(3)  to enumerate the hosts database.  This is identical to "
"using B<hosts>.  When one or more I<key> arguments are provided, pass each "
"I<key> in succession to B<getaddrinfo>(3)  with the address family "
"B<AF_UNSPEC>, enumerating each socket address structure returned."

Re: Issue in man page getent.1

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 2928 bytes --]

Hi Helge,

On Wed, Nov 01, 2023 at 02:02:10PM +0000, Helge Kreutzmann wrote:
> Without further ado, the following was found:
> 
> Issue:    No "in succession" here on purpose?

I don't understand this report.  Please detail.

Thanks,
Alex

P.S.: Please send to <alx@kernel.org>, not to <alx.manpages@gmail.com>,
      since I'm deprecating that address.

> 
> "When no I<key> is provided, use B<sethostent>(3), B<gethostent>(3), and "
> "B<endhostent>(3)  to enumerate the hosts database.  When one or more I<key> "
> "arguments are provided, pass each I<key> to B<gethostbyaddr>(3)  or "
> "B<gethostbyname2>(3), depending on whether a call to B<inet_pton>(3)  "
> "indicates that the I<key> is an IPv6 or IPv4 address or not, and display the "
> "result."
> 
> "When one I<key> is provided, pass the I<key> to B<setnetgrent>(3)  and, "
> "using B<getnetgrent>(3)  display the resulting string triple (I<hostname>, "
> "I<username>, I<domainname>).  Alternatively, three I<keys> may be provided, "
> "which are interpreted as the I<hostname>, I<username>, and I<domainname> to "
> "match to a netgroup name via B<innetgr>(3).  Enumeration is not supported on "
> "B<netgroup>, so either one or three I<keys> must be provided."
> 
> "When no I<key> is provided, use B<setnetent>(3), B<getnetent>(3), and "
> "B<endnetent>(3)  to enumerate the networks database.  When one or more "
> "I<key> arguments are provided, pass each numeric I<key> to "
> "B<getnetbyaddr>(3)  and each nonnumeric I<key> to B<getnetbyname>(3)  and "
> "display the result."
> 
> "When no I<key> is provided, use B<setpwent>(3), B<getpwent>(3), and "
> "B<endpwent>(3)  to enumerate the passwd database.  When one or more I<key> "
> "arguments are provided, pass each numeric I<key> to B<getpwuid>(3)  and each "
> "nonnumeric I<key> to B<getpwnam>(3)  and display the result."
> 
> "When no I<key> is provided, use B<setprotoent>(3), B<getprotoent>(3), and "
> "B<endprotoent>(3)  to enumerate the protocols database.  When one or more "
> "I<key> arguments are provided, pass each numeric I<key> to "
> "B<getprotobynumber>(3)  and each nonnumeric I<key> to B<getprotobyname>(3)  "
> "and display the result."
> 
> "When no I<key> is provided, use B<setrpcent>(3), B<getrpcent>(3), and "
> "B<endrpcent>(3)  to enumerate the rpc database.  When one or more I<key> "
> "arguments are provided, pass each numeric I<key> to B<getrpcbynumber>(3)  "
> "and each nonnumeric I<key> to B<getrpcbyname>(3)  and display the result."
> 
> "When no I<key> is provided, use B<setservent>(3), B<getservent>(3), and "
> "B<endservent>(3)  to enumerate the services database.  When one or more "
> "I<key> arguments are provided, pass each numeric I<key> to "
> "B<getservbynumber>(3)  and each nonnumeric I<key> to B<getservbyname>(3)  "
> "and display the result."

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Issue in man page getent.1

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 762 bytes --]

On Wed, Nov 01, 2023 at 02:02:10PM +0000, Helge Kreutzmann wrote:
> Without further ado, the following was found:
> 
> Issue:    B<hosts> → B<hosts>(5)

Thanks!  Fixed:
<https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=f0d0efdf3e3997b00edaca6f7aa0c6a9b5e8d1cc>

Cheers,
Alex

> 
> "When no I<key> is provided, use B<sethostent>(3), B<gethostent>(3), and "
> "B<endhostent>(3)  to enumerate the hosts database.  This is identical to "
> "using B<hosts>.  When one or more I<key> arguments are provided, pass each "
> "I<key> in succession to B<getaddrinfo>(3)  with the address family "
> "B<AF_UNSPEC>, enumerating each socket address structure returned."

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Issue in man page getent.1

[Helge Kreutzmann]

[-- Attachment #1: Type: text/plain, Size: 1051 bytes --]

Hello Alejandro,
Am Wed, Nov 01, 2023 at 04:30:10PM +0100 schrieb Alejandro Colomar:
> Hi Helge,
> 
> On Wed, Nov 01, 2023 at 02:02:10PM +0000, Helge Kreutzmann wrote:
> > Without further ado, the following was found:
> > 
> > Issue:    No "in succession" here on purpose?
> 
> I don't understand this report.  Please detail.

In the other paragraphs (above and below) the man pages explicitly 
writes "in succession". I wondered why this is not present in these 
paragraphs. It could be on purpose, but it looks like an omission to 
me.

Greetings

             Helge
> P.S.: Please send to <alx@kernel.org>, not to <alx.manpages@gmail.com>,
>       since I'm deprecating that address.

Thanks. I updated my scripts and documentation.

-- 
      Dr. Helge Kreutzmann                     debian@helgefjell.de
           Dipl.-Phys.                   http://www.helgefjell.de/debian.php
        64bit GNU powered                     gpg signed mail preferred
           Help keep free software "libre": http://www.ffii.de/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Issue in man page getent.1

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1322 bytes --]

Hi Helge,

On Wed, Nov 01, 2023 at 03:44:58PM +0000, Helge Kreutzmann wrote:
> Hello Alejandro,
> Am Wed, Nov 01, 2023 at 04:30:10PM +0100 schrieb Alejandro Colomar:
> > Hi Helge,
> > 
> > On Wed, Nov 01, 2023 at 02:02:10PM +0000, Helge Kreutzmann wrote:
> > > Without further ado, the following was found:
> > > 
> > > Issue:    No "in succession" here on purpose?
> > 
> > I don't understand this report.  Please detail.
> 
> In the other paragraphs (above and below) the man pages explicitly 
> writes "in succession". I wondered why this is not present in these 
> paragraphs. It could be on purpose, but it looks like an omission to 
> me.

Hmm, I'm not sure.  I'm CCing glibc to gather their knowledge.

Cheers,
Alex

> 
> Greetings
> 
>              Helge
> > P.S.: Please send to <alx@kernel.org>, not to <alx.manpages@gmail.com>,
> >       since I'm deprecating that address.
> 
> Thanks. I updated my scripts and documentation.
> 
> -- 
>       Dr. Helge Kreutzmann                     debian@helgefjell.de
>            Dipl.-Phys.                   http://www.helgefjell.de/debian.php
>         64bit GNU powered                     gpg signed mail preferred
>            Help keep free software "libre": http://www.ffii.de/



-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Issue in man page getent.1

[Helge Kreutzmann]

Without further ado, the following was found:

Issue:    No "in succession" here on purpose?

"When no I<key> is provided, use B<sethostent>(3), B<gethostent>(3), and "
"B<endhostent>(3)  to enumerate the hosts database.  When one or more I<key> "
"arguments are provided, pass each I<key> to B<gethostbyaddr>(3)  or "
"B<gethostbyname2>(3), depending on whether a call to B<inet_pton>(3)  "
"indicates that the I<key> is an IPv6 or IPv4 address or not, and display the "
"result."

… and in many other paragraphs (I can provide you the full list). Last
time you said, that this is under review with glibc - are there any
results on this?

Re: Issue in man page getent.1

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1027 bytes --]

[Adding libc-help@]

Hi Helge,

On Sun, Nov 17, 2024 at 10:46:26AM GMT, Helge Kreutzmann wrote:
> Without further ado, the following was found:
> 
> Issue:    No "in succession" here on purpose?
> 
> "When no I<key> is provided, use B<sethostent>(3), B<gethostent>(3), and "
> "B<endhostent>(3)  to enumerate the hosts database.  When one or more I<key> "
> "arguments are provided, pass each I<key> to B<gethostbyaddr>(3)  or "
> "B<gethostbyname2>(3), depending on whether a call to B<inet_pton>(3)  "
> "indicates that the I<key> is an IPv6 or IPv4 address or not, and display the "
> "result."
> 
> … and in many other paragraphs (I can provide you the full list). Last
> time you said, that this is under review with glibc - are there any
> results on this?

They didn't respond.  I've added libc-help@ now.

For context for anyone from libc-help@:
<https://lore.kernel.org/linux-man/ZUJaYgd8DCnFdm1V@meinfjell.helgefjelltest.de/T/#u>

Cheers,
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Issue in man page getent.1

[Carlos O'Donell]

On 11/17/24 5:46 AM, Helge Kreutzmann wrote:
> Without further ado, the following was found:
> 
> Issue:    No "in succession" here on purpose?
> 
> "When no I<key> is provided, use B<sethostent>(3), B<gethostent>(3), and "
> "B<endhostent>(3)  to enumerate the hosts database.  When one or more I<key> "
> "arguments are provided, pass each I<key> to B<gethostbyaddr>(3)  or "
> "B<gethostbyname2>(3), depending on whether a call to B<inet_pton>(3)  "
> "indicates that the I<key> is an IPv6 or IPv4 address or not, and display the "
> "result."

This text is for the "hosts" database.

> … and in many other paragraphs (I can provide you the full list). Last
> time you said, that this is under review with glibc - are there any
> results on this?

As an upstream glibc maintainer I can comment on this.

The getent program today iterates over the keys passing them in succession to the calls
as listed for the "hosts" database i.e. nss/getent.c:hosts_keys.

I think the text could be improved by making it consistent for "hosts."

Each one of these instances is different so they each should be enumerated and reviewed
separately.

-- 
Cheers,
Carlos.

Re: Issue in man page getent.1

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1424 bytes --]

Hi Carlos,

On Tue, Nov 19, 2024 at 08:14:48AM -0500, Carlos O'Donell wrote:
> On 11/17/24 5:46 AM, Helge Kreutzmann wrote:
> > Without further ado, the following was found:
> > 
> > Issue:    No "in succession" here on purpose?
> > 
> > "When no I<key> is provided, use B<sethostent>(3), B<gethostent>(3), and "
> > "B<endhostent>(3)  to enumerate the hosts database.  When one or more I<key> "
> > "arguments are provided, pass each I<key> to B<gethostbyaddr>(3)  or "
> > "B<gethostbyname2>(3), depending on whether a call to B<inet_pton>(3)  "
> > "indicates that the I<key> is an IPv6 or IPv4 address or not, and display the "
> > "result."
> 
> This text is for the "hosts" database.
> 
> > … and in many other paragraphs (I can provide you the full list). Last
> > time you said, that this is under review with glibc - are there any
> > results on this?
> 
> As an upstream glibc maintainer I can comment on this.
> 
> The getent program today iterates over the keys passing them in succession to the calls
> as listed for the "hosts" database i.e. nss/getent.c:hosts_keys.
> 
> I think the text could be improved by making it consistent for "hosts."

Thanks!

> 
> Each one of these instances is different so they each should be enumerated and reviewed
> separately.

Would you mind proposing some patches?

Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]