docs/187644: ifconfig man page address_family paragraph needs clarification

[Andrew Merenbach]

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