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

["Alejandro Colomar (man-pages)" <alx.manpages@gmail.com>]

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
>