Skip to contentSkip to conversation

netdevice.7: Update documentation for SIOCGIFADDR SIOCSIFADDR SIOCDIFADDR

PATCH In review Alejandro Colomar 3 participants 7 messages Jan 28, 2021 – Feb 9, 2021

Subsystems (3)
lore
Share & tools
lore
#0 lore raw

PATCH 1/2 netdevice.7: Update documentation for SIOCGIFADDR SIOCSIFADDR SIOCDIFADDR

From: Pali Rohár <[email protected]>

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.

---
 man7/netdevice.7 | 64 +++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 55 insertions(+), 9 deletions(-)
man7/netdevice.7 +55 -9
index 15930807c..bdc2d1922 100644
@@ -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
Signature · 1 line
2.30.0
#1 lore raw

PATCH 2/2 netdevice.7: Minor fixes to Pali's patch

---
 man7/netdevice.7 | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)
man7/netdevice.7 +3 -3
index bdc2d1922..4acf05c10 100644
@@ -390,12 +390,12 @@ flag set can be found via
 .IR /proc/net/dev .
 .PP
 .B AF_INET6
-IPv6 addresses can be read from
+IPv6 addresses can be read in
 .I /proc/net/if_inet6
-file or via
+or via
 .BR rtnetlink (7).
 Adding a new or deleting an existing IPv6 address can be done via
-.BR SIOCSIFADDR " / " SIOCDIFADDR
+.BR SIOCSIFADDR / SIOCDIFADDR
 or via
 .BR rtnetlink (7).
 Retrieving or changing destination IPv6 addresses of a point-to-point
Signature · 1 line
2.30.0
#2 lore raw

Re: [PATCH 2/2] netdevice.7: Minor fixes to Pali's patch

Hi Alex,

Quoted 10 lines · Alejandro Colomar
---
 man7/netdevice.7 | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)
man7/netdevice.7 +0 -0
index bdc2d1922..4acf05c10 100644

man7/netdevice.7 flag set can be found via · line 395

Quoted 8 lines
man7/netdevice.7 +2 -2
@@ -390,12 +390,12 @@ flag set can be found via
 .IR /proc/net/dev .
 .PP
 .B AF_INET6
-IPv6 addresses can be read from
+IPv6 addresses can be read in
 .I /proc/net/if_inet6
-file or via
+or via

I made a different fix. "read from" is a little better than "read in", but it needs to be either "read from the ... file" or "read from ...". I chose the latter.

Thanks,

Michael

Quoted 8 lines
man7/netdevice.7 +1 -1
 .BR rtnetlink (7).
 Adding a new or deleting an existing IPv6 address can be done via
-.BR SIOCSIFADDR " / " SIOCDIFADDR
+.BR SIOCSIFADDR / SIOCDIFADDR
 or via
 .BR rtnetlink (7).
 Retrieving or changing destination IPv6 addresses of a point-to-point
Signature · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
#3 lore raw

Re: [PATCH 2/2] netdevice.7: Minor fixes to Pali's patch

Hi Michael,

Quoted 26 lines · Michael Kerrisk (man-pages)

Hi Alex,

Quoted 10 lines · Alejandro Colomar
---
 man7/netdevice.7 | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)
man7/netdevice.7 +0 -0
index bdc2d1922..4acf05c10 100644

man7/netdevice.7 flag set can be found via · line 395

Quoted 8 lines
man7/netdevice.7 +2 -2
@@ -390,12 +390,12 @@ flag set can be found via
 .IR /proc/net/dev .
 .PP
 .B AF_INET6
-IPv6 addresses can be read from
+IPv6 addresses can be read in
 .I /proc/net/if_inet6
-file or via
+or via

I made a different fix. "read from" is a little better than "read in", but it needs to be either "read from the ... file" or "read from ...". I chose the latter.

Quoted 9 lines

Thanks,

Michael

Quoted 4 lines
man7/netdevice.7 +1 -1
 .BR rtnetlink (7).
 Adding a new or deleting an existing IPv6 address can be done via
-.BR SIOCSIFADDR " / " SIOCDIFADDR
+.BR SIOCSIFADDR / SIOCDIFADDR

I noticed you didn't apply this part. Did you forget it, or do you prefer it as is?

Rationale:

https://lore.kernel.org/linux-man/[email protected]/

Thanks,

Alex

Quoted 6 lines
Quoted 4 lines
man7/netdevice.7 +0 -0
 or via
 .BR rtnetlink (7).
 Retrieving or changing destination IPv6 addresses of a point-to-point
Signature · 3 lines
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
#4 lore raw

Re: [PATCH 2/2] netdevice.7: Minor fixes to Pali's patch

Hi Alex,

Quoted 3 lines · Alejandro Colomar (man-pages)

Hi Michael,

On 1/28/21 9:16 PM, Michael Kerrisk (man-pages) wrote:

[...]

Quoted 11 lines
Quoted 4 lines
Quoted 4 lines

.BR rtnetlink (7).
Adding a new or deleting an existing IPv6 address can be done via
-.BR SIOCSIFADDR " / " SIOCDIFADDR
+.BR SIOCSIFADDR / SIOCDIFADDR

I noticed you didn't apply this part. Did you forget it, or do you prefer it as is?

Rationale:

https://lore.kernel.org/linux-man/[email protected]/

I'm not sure, but overall I did not/do like the sentence structure. I applied the patch below.

Cheers,

Michael

man7/netdevice.7 +5 -2
@@ -394,8 +394,11 @@ IPv6 addresses can be read from
 .I /proc/net/if_inet6
 or via
 .BR rtnetlink (7).
-Adding a new or deleting an existing IPv6 address can be done via
-.BR SIOCSIFADDR " / " SIOCDIFADDR
+Adding a new IPv6 address and deleting an existing IPv6 address
+can be done via
+.B SIOCSIFADDRi
+and
+.B SIOCDIFADDR
 or via
 .BR rtnetlink (7).
 Retrieving or changing destination IPv6 addresses of a point-to-point
Signature · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
#5 lore raw

Re: [PATCH 2/2] netdevice.7: Minor fixes to Pali's patch

Quoted 31 lines · On Tuesday 09 February 2021 20:29:45 Michael Kerrisk (man-pages) wrote:

Hi Alex,

Quoted 3 lines · Alejandro Colomar (man-pages)

Hi Michael,

On 1/28/21 9:16 PM, Michael Kerrisk (man-pages) wrote:

[...]

Quoted 11 lines
Quoted 4 lines
Quoted 4 lines

.BR rtnetlink (7).
Adding a new or deleting an existing IPv6 address can be done via
-.BR SIOCSIFADDR " / " SIOCDIFADDR
+.BR SIOCSIFADDR / SIOCDIFADDR

I noticed you didn't apply this part. Did you forget it, or do you prefer it as is?

Rationale:

https://lore.kernel.org/linux-man/[email protected]/

I'm not sure, but overall I did not/do like the sentence structure. I applied the patch below.

Cheers,

Michael

man7/netdevice.7 IPv6 addresses can be read from · line 399

Quoted 8 lines
man7/netdevice.7 +3 -2
@@ -394,8 +394,11 @@ IPv6 addresses can be read from
 .I /proc/net/if_inet6
 or via
 .BR rtnetlink (7).
-Adding a new or deleting an existing IPv6 address can be done via
-.BR SIOCSIFADDR " / " SIOCDIFADDR
+Adding a new IPv6 address and deleting an existing IPv6 address
+can be done via
+.B SIOCSIFADDRi

Hello Michael! There is an extra 'i'.

Quoted 5 lines
man7/netdevice.7 +2 -0
+and
+.B SIOCDIFADDR
 or via
 .BR rtnetlink (7).
 Retrieving or changing destination IPv6 addresses of a point-to-point
#6 lore raw

Re: [PATCH 2/2] netdevice.7: Minor fixes to Pali's patch

Quoted 29 lines · Pali Rohár
Quoted 28 lines · On Tuesday 09 February 2021 20:29:45 Michael Kerrisk (man-pages) wrote:

Hi Alex,

Quoted 3 lines · Alejandro Colomar (man-pages)

Hi Michael,

On 1/28/21 9:16 PM, Michael Kerrisk (man-pages) wrote:

[...]

Quoted 11 lines
Quoted 4 lines
Quoted 4 lines

.BR rtnetlink (7).
Adding a new or deleting an existing IPv6 address can be done via
-.BR SIOCSIFADDR " / " SIOCDIFADDR
+.BR SIOCSIFADDR / SIOCDIFADDR

I noticed you didn't apply this part. Did you forget it, or do you prefer it as is?

Rationale:

https://lore.kernel.org/linux-man/[email protected]/

I'm not sure, but overall I did not/do like the sentence structure. I applied the patch below.

Cheers,

Michael

Quoted 13 lines

man7/netdevice.7 IPv6 addresses can be read from · line 399

Quoted 11 lines
man7/netdevice.7 +3 -2
@@ -394,8 +394,11 @@ IPv6 addresses can be read from
 .I /proc/net/if_inet6
 or via
 .BR rtnetlink (7).
-Adding a new or deleting an existing IPv6 address can be done via
-.BR SIOCSIFADDR " / " SIOCDIFADDR
+Adding a new IPv6 address and deleting an existing IPv6 address
+can be done via
+.B SIOCSIFADDRi

Hello Michael! There is an extra 'i'.

Thanks, Pali! Fixed.

Cheers,

Michael

Signature · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/