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:

quoted

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@kernel.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

quoted

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.

quoted

+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).

quoted

+.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.

quoted

+.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.

quoted

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