[PATCH v3] netdevice.7: Update documentation for SIOCGIFADDR SIOCSIFADDR SIOCDIFADDR

Unlike SIOCGIFADDR and SIOCSIFADDR which are supported by many protocol
families, SIOCDIFADDR is supported by AF_INET6 and AF_APPLETALK only.

Unlike other protocols, AF_INET6 uses struct in6_ifreq.

Signed-off-by: Pali Rohár <pali@kernel.org>
---
 man7/netdevice.7 | 64 +++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 55 insertions(+), 9 deletions(-)

diff --git a/man7/netdevice.7 b/man7/netdevice.7
index 15930807c..bdc2d1922 100644
--- a/man7/netdevice.7
+++ b/man7/netdevice.7

@@ -56,9 +56,27 @@ struct ifreq {
 .EE
 .in
 .PP
+.B AF_INET6
+is an exception.
+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

@@ -143,13 +161,33 @@ 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
+.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
+.B SIOCDIFADDR
+deletes only
+.B AF_INET6
+addresses.
+A
+.B AF_INET
+address can be deleted by setting it to zero via
+.BR SIOCSIFADDR .
 .TP
 .BR SIOCGIFDSTADDR ", " SIOCSIFDSTADDR
 Get or set the destination address of a point-to-point device using

@@ -351,10 +389,18 @@ The names of interfaces with no addresses or that don't have the
 flag set can be found via
 .IR /proc/net/dev .
 .PP
-Local IPv6 IP addresses can be found via
-.I /proc/net
+.B AF_INET6
+IPv6 addresses can be read from
+.I /proc/net/if_inet6
+file or via
+.BR rtnetlink (7).
+Adding a new or deleting an existing IPv6 address can be done via
+.BR SIOCSIFADDR " / " SIOCDIFADDR
 or via
 .BR rtnetlink (7).
+Retrieving or changing destination IPv6 addresses of a point-to-point
+interface is possible only via
+.BR rtnetlink (7).
 .SH BUGS
 glibc 2.1 is missing the
 .I ifr_newname

-- 
2.20.1

Hi Pali,

I was a patch for environ.7 while I found some pattern.
Please see below a minor fix.

Thanks,

Alex

On 1/16/21 11:36 PM, Pali Rohár wrote:

I found a few pages with the pattern [.BR X / Y],
but none like [.BR X " / " Y].

$ grep -rn '\.BR [a-zA-Z]* / [a-zA-Z]*' man?
man1/getent.1:365:.BR ahosts / getaddrinfo (3)
man2/sigaction.2:526:.BR SIGIO / SIGPOLL
man2/sigaction.2:638:.BR SIGIO / SIGPOLL
man2/sigaction.2:814:.BR SIGIO / SIGPOLL
man3/sysconf.3:181:.BR PAGESIZE / _SC_PAGESIZE .
man7/signal.7:539:.BR SIGINFO / SIGPWR
man7/pipe.7:114:.BR SIGPIPE / EPIPE
man7/environ.7:127:.BR EDITOR / VISUAL
$ grep -rn '\.BR [a-zA-Z]* " / " [a-zA-Z]*' man?
$

Please fix this for the next revision.
However, don't send a new one only for this.
I'd wait to see if someone reviews it or helps in any way ;)

 or via
 .BR rtnetlink (7).
+Retrieving or changing destination IPv6 addresses of a point-to-point
+interface is possible only via
+.BR rtnetlink (7).
 .SH BUGS
 glibc 2.1 is missing the
 .I ifr_newname

On Tuesday 19 January 2021 21:18:29 Alejandro Colomar (man-pages) wrote:

Hi Pali,

I was a patch for environ.7 while I found some pattern.
Please see below a minor fix.

Thanks,

Alex

On 1/16/21 11:36 PM, Pali Rohár wrote:

quoted

Unlike SIOCGIFADDR and SIOCSIFADDR which are supported by many protocol
families, SIOCDIFADDR is supported by AF_INET6 and AF_APPLETALK only.

Unlike other protocols, AF_INET6 uses struct in6_ifreq.

Signed-off-by: Pali Rohár <pali@kernel.org>
---
 man7/netdevice.7 | 64 +++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 55 insertions(+), 9 deletions(-)

diff --git a/man7/netdevice.7 b/man7/netdevice.7
index 15930807c..bdc2d1922 100644
--- a/man7/netdevice.7
+++ b/man7/netdevice.7

@@ -56,9 +56,27 @@ struct ifreq {
 .EE
 .in
 .PP
+.B AF_INET6
+is an exception.
+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

@@ -143,13 +161,33 @@ 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
+.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
+.B SIOCDIFADDR
+deletes only
+.B AF_INET6
+addresses.
+A
+.B AF_INET
+address can be deleted by setting it to zero via
+.BR SIOCSIFADDR .
 .TP
 .BR SIOCGIFDSTADDR ", " SIOCSIFDSTADDR
 Get or set the destination address of a point-to-point device using

@@ -351,10 +389,18 @@ The names of interfaces with no addresses or that don't have the
 flag set can be found via
 .IR /proc/net/dev .
 .PP
-Local IPv6 IP addresses can be found via
-.I /proc/net
+.B AF_INET6
+IPv6 addresses can be read from
+.I /proc/net/if_inet6
+file or via
+.BR rtnetlink (7).
+Adding a new or deleting an existing IPv6 address can be done via
+.BR SIOCSIFADDR " / " SIOCDIFADDR

I found a few pages with the pattern [.BR X / Y],
but none like [.BR X " / " Y].

$ grep -rn '\.BR [a-zA-Z]* / [a-zA-Z]*' man?
man1/getent.1:365:.BR ahosts / getaddrinfo (3)
man2/sigaction.2:526:.BR SIGIO / SIGPOLL
man2/sigaction.2:638:.BR SIGIO / SIGPOLL
man2/sigaction.2:814:.BR SIGIO / SIGPOLL
man3/sysconf.3:181:.BR PAGESIZE / _SC_PAGESIZE .
man7/signal.7:539:.BR SIGINFO / SIGPWR
man7/pipe.7:114:.BR SIGPIPE / EPIPE
man7/environ.7:127:.BR EDITOR / VISUAL
$ grep -rn '\.BR [a-zA-Z]* " / " [a-zA-Z]*' man?
$

Please fix this for the next revision.
However, don't send a new one only for this.

Ok!

I'd wait to see if someone reviews it or helps in any way ;)

Seems that nobody came up with suggestions for improvements...

quoted

 or via
 .BR rtnetlink (7).
+Retrieving or changing destination IPv6 addresses of a point-to-point
+interface is possible only via
+.BR rtnetlink (7).
 .SH BUGS
 glibc 2.1 is missing the
 .I ifr_newname

Hi Pali,

On 1/16/21 11:36 PM, Pali Rohár wrote:

Unlike SIOCGIFADDR and SIOCSIFADDR which are supported by many protocol
families, SIOCDIFADDR is supported by AF_INET6 and AF_APPLETALK only.

Unlike other protocols, AF_INET6 uses struct in6_ifreq.

Signed-off-by: Pali Rohár <pali@kernel.org>

Patch applied!

Thanks,

Alex

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

Hi Pali,

On 1/27/21 8:29 PM, Pali Rohár wrote:
[...]

quoted

Please fix this for the next revision.
However, don't send a new one only for this.

Ok!

I fixed that already.

quoted

I'd wait to see if someone reviews it or helps in any way ;)

Seems that nobody came up with suggestions for improvements...

Thanks for the ping.

I applied v3 with some minor fixes.

Thanks,

Alex

quoted

quoted

 or via
 .BR rtnetlink (7).
+Retrieving or changing destination IPv6 addresses of a point-to-point
+interface is possible only via
+.BR rtnetlink (7).
 .SH BUGS
 glibc 2.1 is missing the
 .I ifr_newname

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