netdev - Re: [PATCH v2] netdevice.7: Update documentation for SIOCGIFADDR SIOCSIFADDR SIOCDIFADDR

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [thread-next>] [day] [month] [year] [list]

Message-ID: <16eaf3ce-3e76-5e34-5909-be065502abca@gmail.com>
Date:   Sun, 10 Jan 2021 20:57:50 +0100
From:   "Alejandro Colomar (man-pages)" <alx.manpages@...il.com>
To:     Pali Rohár <pali@...nel.org>,
        Michael Kerrisk <mtk.manpages@...il.com>
Cc:     linux-man@...r.kernel.org, netdev@...r.kernel.org
Subject: Re: [PATCH v2] netdevice.7: Update documentation for SIOCGIFADDR
 SIOCSIFADDR SIOCDIFADDR

[ CC += netdev ]

On 1/10/21 5:38 PM, Pali Rohár wrote:
> On Saturday 02 January 2021 19:39:52 Pali Rohár wrote:
>> Also add description for struct in6_ifreq which is used for IPv6 addresses.
>>
>> SIOCSIFADDR and SIOCDIFADDR can be used to add or delete IPv6 address and
>> pppd is using these ioctls for a long time. Surprisingly SIOCDIFADDR cannot
>> be used for deleting IPv4 address but only for IPv6 addresses.
>>
>> Signed-off-by: Pali Rohár <pali@...nel.org>
>> ---
>>  man7/netdevice.7 | 50 +++++++++++++++++++++++++++++++++++++++++-------
>>  1 file changed, 43 insertions(+), 7 deletions(-)
> 
> Hello! Is something else needed for this patch?

Hello Pali,

Sorry, I forgot to comment a few more formatting/wording issues: see
below.  Apart from that, I'd prefer Michael to review this one.

Thanks,

Alex

> 
>> diff --git a/man7/netdevice.7 b/man7/netdevice.7
>> index 488e83d9a..12f94bfd7 100644
>> --- a/man7/netdevice.7
>> +++ b/man7/netdevice.7
>> @@ -55,9 +55,26 @@ struct ifreq {
>>  .EE
>>  .in
>>  .PP
>> +AF_INET6 is an exception.

[
.B AF_INET6
is an exception.
]

Sorry, this was my mistake on the previous review,
as I mixed expected output with actual code, and confused you.

>> +It passes an
>> +.I in6_ifreq
>> +structure:
>> +.PP
>> +.in +4n
>> +.EX
>> +struct in6_ifreq {
>> +    struct in6_addr     ifr6_addr;
>> +    u32                 ifr6_prefixlen;
>> +    int                 ifr6_ifindex; /* Interface index */
>> +};
>> +.EE
>> +.in
>> +.PP
>>  Normally, the user specifies which device to affect by setting
>>  .I ifr_name
>> -to the name of the interface.
>> +to the name of the interface or
>> +.I ifr6_ifindex
>> +to the index of the interface.
>>  All other members of the structure may
>>  share memory.
>>  .SS Ioctls
>> @@ -142,13 +159,32 @@ IFF_ISATAP:Interface is RFC4214 ISATAP interface.
>>  .PP
>>  Setting the extended (private) interface flags is a privileged operation.
>>  .TP
>> -.BR SIOCGIFADDR ", " SIOCSIFADDR
>> -Get or set the address of the device using
>> -.IR ifr_addr .
>> -Setting the interface address is a privileged operation.
>> -For compatibility, only
>> +.BR SIOCGIFADDR ", " SIOCSIFADDR ", " SIOCDIFADDR
>> +Get, set or delete the address of the device using

[Get, set, or delete ...]

Note the extra comma (Oxford comma).

>> +.IR ifr_addr ,
>> +or
>> +.I ifr6_addr
>> +with
>> +.IR ifr6_prefixlen .
>> +Setting or deleting the interface address is a privileged operation.
>> +For compatibility,
>> +.B SIOCGIFADDR
>> +returns only
>>  .B AF_INET
>> -addresses are accepted or returned.
>> +addresses,
>> +.B SIOCSIFADDR
>> +accepts
>> +.B AF_INET
>> +and
>> +.B AF_INET6
>> +addresses and

[addresses, and]

Rationale: clearly separate SIOCS* text from SIOCD* text.

>> +.B SIOCDIFADDR
>> +deletes only
>> +.B AF_INET6
>> +addresses.
>> +.B AF_INET
>> +address can be deleted by setting zero address via

Suggestion:

[
A
.B XXX
address ... by setting it to zero via
]

Although I don't know exactly how all this works,
so it's only a suggestion, but that needs some wording fix.

>> +.BR SIOCSIFADDR .
>>  .TP
>>  .BR SIOCGIFDSTADDR ", " SIOCSIFDSTADDR
>>  Get or set the destination address of a point-to-point device using
>> -- 
>> 2.20.1
>>


-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/