From nobody@FreeBSD.org  Sun Mar 16 22:39:13 2014
Return-Path: <nobody@FreeBSD.org>
Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115])
	(using TLSv1 with cipher ADH-AES256-SHA (256/256 bits))
	(No client certificate requested)
	by hub.freebsd.org (Postfix) with ESMTPS id 0C7172A7
	for <freebsd-gnats-submit@FreeBSD.org>; Sun, 16 Mar 2014 22:39:13 +0000 (UTC)
Received: from cgiserv.freebsd.org (cgiserv.freebsd.org [IPv6:2001:1900:2254:206a::50:4])
	(using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits))
	(No client certificate requested)
	by mx1.freebsd.org (Postfix) with ESMTPS id D2E3DC72
	for <freebsd-gnats-submit@FreeBSD.org>; Sun, 16 Mar 2014 22:39:12 +0000 (UTC)
Received: from cgiserv.freebsd.org ([127.0.1.6])
	by cgiserv.freebsd.org (8.14.8/8.14.8) with ESMTP id s2GMdB5V094779
	for <freebsd-gnats-submit@FreeBSD.org>; Sun, 16 Mar 2014 22:39:11 GMT
	(envelope-from nobody@cgiserv.freebsd.org)
Received: (from nobody@localhost)
	by cgiserv.freebsd.org (8.14.8/8.14.8/Submit) id s2GMdB0T094775;
	Sun, 16 Mar 2014 22:39:11 GMT
	(envelope-from nobody)
Message-Id: <201403162239.s2GMdB0T094775@cgiserv.freebsd.org>
Date: Sun, 16 Mar 2014 22:39:11 GMT
From: Andrew Merenbach <andrew@merenbach.com>
To: freebsd-gnats-submit@FreeBSD.org
Subject: ifconfig man page address_family paragraph needs clarification
X-Send-Pr-Version: www-3.1
X-GNATS-Notify:

>Number:         187644
>Category:       docs
>Synopsis:       [patch] ifconfig.8 man page address_family paragraph needs clarification
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Sun Mar 16 22:40:01 UTC 2014
>Closed-Date:    Tue May 27 21:47:37 UTC 2014
>Last-Modified:  Tue May 27 21:47:37 UTC 2014
>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&#8208;
             sions in differing protocols with different naming schemes, spec&#8208;
             ifying the address family is recommended.  The address or proto&#8208;
             col families currently supported are inet, inet6, atalk,
             ipx, and link.  The default if available is inet or other&#8208;
             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:

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/187644: commit references a PR
Date: Tue, 27 May 2014 20:45:20 +0000 (UTC)

 Author: allanjude (doc committer)
 Date: Tue May 27 20:45:15 2014
 New Revision: 266774
 URL: http://svnweb.freebsd.org/changeset/base/266774
 
 Log:
   improve ifconfig(8) man page by describing special behaviour of -l ether
   
   PR:		docs/187644
   Submitted by:	Andrew Merenbach (original patch)
   Approved by:	bcr (mentor)
 
 Modified:
   head/sbin/ifconfig/ifconfig.8
 
 Modified: head/sbin/ifconfig/ifconfig.8
 ==============================================================================
 --- head/sbin/ifconfig/ifconfig.8	Tue May 27 20:22:36 2014	(r266773)
 +++ head/sbin/ifconfig/ifconfig.8	Tue May 27 20:45:15 2014	(r266774)
 @@ -169,6 +169,18 @@ and
  .Dq lladdr
  are synonyms for
  .Dq link .
 +When using the
 +.Fl l
 +flag, the
 +.Dq ether
 +address family has special meaning and is no longer synonymous with
 +.Dq link
 +or
 +.Dq lladdr .
 +Specifying
 +.Fl l Dq ether
 +will list only ethernet interfaces, excluding all other interface types,
 +including the loopback interface.
  .It Ar dest_address
  Specify the address of the correspondent on the other end
  of a point to point link.
 @@ -2554,6 +2566,11 @@ The
  .Fl l
  flag may be used to list all available interfaces on the system, with
  no other additional information.
 +If an
 +.Ar address_family
 +is specified, only interfaces of that type will be listed.
 +.Fl l Dq ether
 +will list only ethernet adapters, excluding the loopback interface.
  Use of this flag is mutually exclusive
  with all other flags and commands, except for
  .Fl d
 _______________________________________________
 svn-src-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/svn-src-all
 To unsubscribe, send any mail to "svn-src-all-unsubscribe@freebsd.org"
 
State-Changed-From-To: open->closed 
State-Changed-By: allanjude 
State-Changed-When: Tue May 27 21:47:16 UTC 2014 
State-Changed-Why:  
fix committed r266774 

http://www.freebsd.org/cgi/query-pr.cgi?pr=187644 
>Unformatted:
