Date: Sun, 16 Mar 2014 22:39:11 GMT From: Andrew Merenbach <andrew@merenbach.com> To: freebsd-gnats-submit@FreeBSD.org Subject: docs/187644: ifconfig man page address_family paragraph needs clarification Message-ID: <201403162239.s2GMdB0T094775@cgiserv.freebsd.org> Resent-Message-ID: <201403162240.s2GMe1P4011944@freefall.freebsd.org>
index | next in thread | raw e-mail
>Number: 187644
>Category: docs
>Synopsis: ifconfig man page address_family paragraph needs clarification
>Confidential: no
>Severity: non-critical
>Priority: low
>Responsible: freebsd-doc
>State: open
>Quarter:
>Keywords:
>Date-Required:
>Class: doc-bug
>Submitter-Id: current-users
>Arrival-Date: Sun Mar 16 22:40:01 UTC 2014
>Closed-Date:
>Last-Modified:
>Originator: Andrew Merenbach
>Release: 10.0-RELEASE
>Organization:
>Environment:
FreeBSD chitsa 10.0-RELEASE FreeBSD 10.0-RELEASE #0 r260789: Thu Jan 16 22:34:59 UTC 2014 root@snap.freebsd.org:/usr/obj/usr/src/sys/GENERIC amd64
>Description:
man 8 ifconfig states the following:
address_family
Specify the address family which affects interpretation of the
remaining parameters. Since an interface can receive transmis‐
sions in differing protocols with different naming schemes, spec‐
ifying the address family is recommended. The address or proto‐
col families currently supported are “inet”, “inet6”, “atalk”,
“ipx”, and “link”. The default if available is “inet” or other‐
wise “link”. “ether” and “lladdr” are synonyms for “link”.
The last paragraph here asserts that link, ether, and lladdr are synonymous. When running ifconfig to check a list of available interfaces (-l flag) this does not appear to be the case.
>How-To-Repeat:
What I see:
$ ifconfig -l link
em0 lo0
$ ifconfig -l lladdr
em0 lo0
$ ifconfig -l ether
em0
What I expected to see:
$ ifconfig -l link
em0 lo0
$ ifconfig -l lladdr
em0 lo0
$ ifconfig -l ether
em0 lo0
Since the source code (ifconfig.c:328) contains a 'special case for "ether" address family' that appears to exclude layer 2 vlan, bridge, and straight-out Ethernet interfaces, I feel that the documentation should be updated to reflect this.
>Fix:
A patch is attached. I would not be surprised if someone knows of a better way to phrase this, though, so please let me know if I may revise.
Fix is a modification to the last sentence of the man page, currently ifconfig.8:172-176.
Preview of change included in patch:
> The default if available is "inet" or otherwise "link". "ether" and "lladdr" are synonyms for "link".
becomes
> The default if available is "inet" or otherwise "link". "ether" and "lladdr" are synonyms for "link", with one caveat: if the -l flag is specified in conjunction with the “ether” address family, non-ethernet interfaces will be excluded in the output.
Patch attached with submission follows:
--- ifconfig.8 2014-01-16 12:36:52.000000000 -0800
+++ ifconfig.8 2014-03-16 15:14:38.720858851 -0700
@@ -173,7 +173,12 @@
and
.Dq lladdr
are synonyms for
-.Dq link .
+.Dq link ,
+with one caveat: if the
+.Fl l
+flag is specified in conjunction with the
+.Dq ether
+address family, non-ethernet interfaces will be excluded from the output.
.It Ar dest_address
Specify the address of the correspondent on the other end
of a point to point link.
>Release-Note:
>Audit-Trail:
>Unformatted:
help
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201403162239.s2GMdB0T094775>