Bug 188786

Summary: Bug in inet(3) man page (inet_aton())
Product: Documentation Reporter: mtk.manpages
Component: Books & ArticlesAssignee: freebsd-doc (Nobody) <doc>
Status: Closed FIXED    
Severity: Affects Only Me    
Priority: Normal    
Version: Latest   
Hardware: Any   
OS: Any   

Description mtk.manpages 2014-04-19 08:10:00 UTC 
As http://www.freebsd.org/cgi/man.cgi?query=inet_aton&apropos=0&sektion=0&manpath=FreeBSD+10.0-RELEASE&arch=default&format=html, on sees the text:

     When a two	part address is	supplied, the last part	is interpreted as a
     24-bit quantity and placed	in the right most three	bytes of the network
     address.  This makes the two part address format convenient for specify-
     ing Class A network addresses as ``net.host''.

In the second line, there should I believe be the substitution: s/network$/host$/. 

I have no FreeBSD system to test, but have tested on OpenBSD and Linux.
Furthermore, the change makes sense when one reads the surrounding text.

I see the same text in the OpenBSD page, and also the NetBSD page. How
does this work -- should I submit bugs for each of those systems, or do
communicate such problems to one another?

Thanks,

Michael Kerrisk
(maintainer, Linux man-pages project)

Test code:
#define _BSD_SOURCE
#include <arpa/inet.h>
#include <stdio.h>
#include <stdlib.h>

static void
printBytes(in_addr_t a)
{
    printf("%d", (a >> 24) & 0xff);
    printf(".");
    printf("%d", (a >> 16) & 0xff);
    printf(".");
    printf("%d", (a >> 8) & 0xff);
    printf(".");
    printf("%d", (a & 0xff));
} /* printBytes */

int
main(int argc, char *argv[])
{
    struct in_addr addr;

    if (argc != 2) {
        fprintf(stderr, "%s <dotted-address>\n", argv[0]);
        exit(EXIT_FAILURE);
    }

    if (inet_aton(argv[1], &addr) == 0) {
        fprintf(stderr, "inet_aton() failed\n");
        exit(EXIT_FAILURE);
    }

    printf("%s\n", inet_ntoa(addr));

    struct in_addr n, h;

    n.s_addr = inet_netof(addr);
    printf("Network number       : ");
    printBytes(n.s_addr);
    printf("\n");

    h.s_addr = inet_lnaof(addr);
    printf("Local network address: ");
    printBytes(h.s_addr);
    printf("\n");

    addr = inet_makeaddr(n.s_addr, h.s_addr);
    printf("Made address: %s\n", inet_ntoa(addr));

    exit(EXIT_SUCCESS);
}

Fix: 

As above
Comment 1 Mark Linimon 2014-04-19 13:54:48 UTC 
On Sat, Apr 19, 2014 at 07:06:48AM +0000, Michael Kerrisk wrote:
> I see the same text in the OpenBSD page, and also the NetBSD page.
> How does this work -- should I submit bugs for each of those systems,
> or do communicate such problems to one another?

Short answer: we do't automatically sync with one another.

Longer answer: it would take some investigation to find out if one or
the other of the 3 has a "canonical" set of manpages that the others
have copied.  So, the best way is to open a PR for each.

Thanks.

mcl
Comment 2 mtk.manpages 2014-04-25 14:52:46 UTC 
Thanks for the info, Mark.

On Sat, Apr 19, 2014 at 2:54 PM, Mark Linimon <linimon@lonesome.com> wrote:
> On Sat, Apr 19, 2014 at 07:06:48AM +0000, Michael Kerrisk wrote:
>> I see the same text in the OpenBSD page, and also the NetBSD page.
>> How does this work -- should I submit bugs for each of those systems,
>> or do communicate such problems to one another?
>
> Short answer: we do't automatically sync with one another.
>
> Longer answer: it would take some investigation to find out if one or
> the other of the 3 has a "canonical" set of manpages that the others
> have copied.  So, the best way is to open a PR for each.
>
> Thanks.
>
> mcl



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
Comment 3 Benjamin Kaduk freebsd_committer freebsd_triage 2014-05-17 05:06:45 UTC 
State Changed
From-To: open->closed

I do not believe this is a bug. 

The text is just referring to an IP address when it says 
"network address", and the class-A addressing scheme is just 
taking the three octets from the second component and putting 
them as the last three octets of the IPv4 address. 
In the nearby portions of this document, "network address" 
is also referring to just an IPv4 address.
Comment 4 Mark Linimon 2014-05-21 22:21:16 UTC 
----- Forwarded message from "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com> -----

Date: Sat, 17 May 2014 07:30:18 +0200
From: "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>
To: bjk@freebsd.org
Cc: freebsd-doc@freebsd.org
Subject: Re: docs/188786: Bug in inet(3) man page (inet_aton())

Ben,

Okay -- I see what you mean--I was focused on that one piece, and
didn't note the other uses of "network address".

I think that what makes the page a little confusing is that it uses
both terms "Internet address" and "network address" without making it
clear that they are synonymous (and thus leaving the potential for the
reader to think they are not). This might not normally be problematic,
but given that the page is also talking about the 'network' and 'host'
components of the address, there is scope for confusion. Not a big
thing, I guess, but FWIW that's the confusion that I tried to avoid in
the Linux man page by using the term "binary address"; see
http://man7.org/linux/man-pages/man3/inet.3.html#DESCRIPTION

Cheers,

Michael

----- End forwarded message -----