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

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

[Alejandro Colomar (man-pages)]

[ 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@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

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

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

[Pali Rohár]

On Sunday 10 January 2021 20:57:50 Alejandro Colomar (man-pages) wrote:
> [ 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@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

Hello Alex! I will try to explain configuring IPv4 and IPv6 addresses on
network interfaces, so you probably could have better way how to improve
description in "official" manpage. I'm not native English speaker, so I
would follow any suggestions from you.


AF_INET (via struct ifreq)

* SIOCGIFADDR - returns first/primary IPv4 address for ifr_name
* SIOCSIFADDR - changes first/primary IPv4 address for ifr_name
* SIOCDIFADDR - unsupported, returns error
* SIOCGIFDSTADDR - returns first/primary IPv4 peer/destination address
* SIOCSIFDSTADDR - changes first/primary IPv4 peer/destination address

Non-primary IPv4 addresses with label are present in virtual network
interfaces which have ':label' suffix. E.g. non-primary address for eth0
with label 0 can be changed by SIOCSIFADDR by specifying 'eth0:0' as
interface name. Non-primary IPv4 address which do not have assigned
label are invisible for SIOCGIFADDR / SIOCSIFADDR. Primary IPv4
addresses can be deleted by changing address to 0.0.0.0 via SIOCSIFADDR.
Similarly also for non-primary address with label. Non-primary IPv4
addresses without label can be listed, added or removed only via
rtnetlink interface.

SIOCGIFDSTADDR / SIOCSIFDSTADDR are like SIOCGIFADDR / SIOCSIFADDR
(including labels for non-primary).


AF_INET6 (via struct in6_ifreq):

* SIOCGIFADDR - unsupported, returns error
* SIOCSIFADDR - adds a new IPv6 address for ifr6_ifindex
* SIOCDIFADDR - deletes specified IPv6 address for ifr6_ifindex
* SIOCGIFDSTADDR - unsupported
* SIOCSIFDSTADDR - unsupported for IPv6 addresses

IPv6 addresses can be listed only via /proc/net/if_inet6 file or via
rtnetlink interface. SIOCSIFADDR for AF_INET6 (unlike AF_INET) adds a
new IPv6 address to interface (not change first/primary IPv6 address).
For IPv6 they do not have concept of first address and therefore for
deleting is needed to use different ioctl SIOCSIFADDR (not setting zero
address via SIOCSIFADDR as in IPv4).

Retrieving, adding and deleting IPv6 peer/destination addresses (e.g.
for point to point protocols) can be only via rtnetlink interface. IIRC
there is no other way, there is no ioctl/sysfs/procfs interface.


There is some strange way how to setup a new SIT (IPv6-in-IPv4) tunnel.
It is by using AF_INET6 SIOCSIFDSTADDR ioctl on sit0 master interface
(field ifr6_ifindex) with IPv4 address of remote peer set in low 32 bits
of 128 bit IPv6 address (field ifr6_addr). Other bits of IPv6 storage
needs to be zero. So SIOCSIFDSTADDR is there also for AF_INET6 socket,
but is doing something totally different as for AF_INET and what is
described in current netdevice.7 manpage. Also note that I have not
found a way how to retrieve this IPv4 peer address in other way than via
rtnetlink.

You can try this via 'ifconfig sit0 inet6 tunnel ::10.0.0.1' call to
create a new IPv6-in-IPv4 interface (sitN, N first unused) which
forwards IPv6 traffic encapsulated in IPv4 to IPv4 server 10.0.0.1.


Another thing which makes debugging hard, strace does not support
decoding these ioctl calls for AF_INET6 sockets and thinks that passed
structure is IPv4's struct ifreq, which is just a garbage on screen.

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

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

[Alejandro Colomar (man-pages)]

On 1/12/21 8:26 PM, Pali Rohár wrote:
> On Sunday 10 January 2021 20:57:50 Alejandro Colomar (man-pages) wrote:
>> [ 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@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
> 
> Hello Alex! I will try to explain configuring IPv4 and IPv6 addresses on
> network interfaces, so you probably could have better way how to improve
> description in "official" manpage. I'm not native English speaker, so I
> would follow any suggestions from you.
[...]

Hi Pali,

Thanks for explaining the process to me.
However, I don't feel that I understand it enough to help you co-writing
the text.  I lack much background to understand your explanation.  I'd
help you with the language happily, if it was only that :)

Maybe someone from netdev@ can help?  Or Michael?

Regards,

Alex


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

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

[Pali Rohár]

On Saturday 16 January 2021 01:41:24 Alejandro Colomar (man-pages) wrote:
> On 1/12/21 8:26 PM, Pali Rohár wrote:
> > On Sunday 10 January 2021 20:57:50 Alejandro Colomar (man-pages) wrote:
> >> [ 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@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
> > 
> > Hello Alex! I will try to explain configuring IPv4 and IPv6 addresses on
> > network interfaces, so you probably could have better way how to improve
> > description in "official" manpage. I'm not native English speaker, so I
> > would follow any suggestions from you.
> [...]
> 
> Hi Pali,
> 
> Thanks for explaining the process to me.
> However, I don't feel that I understand it enough to help you co-writing
> the text.  I lack much background to understand your explanation.  I'd
> help you with the language happily, if it was only that :)

OK! I will send a new patch version ...

> Maybe someone from netdev@ can help?  Or Michael?

... and other improvements can be done later.

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

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

[Pali Rohár]

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

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

[Alejandro Colomar (man-pages)]

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

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

[Pali Rohár]

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

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

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

[Alejandro Colomar (man-pages)]

Hi Pali,

On 1/27/21 8:29 PM, Pali Rohár wrote:
[...]
>>
>> Please fix this for the next revision.
>> However, don't send a new one only for this.
> 
> Ok!

I fixed that already.

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

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

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

[Alejandro Colomar (man-pages)]

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

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

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