From owner-freebsd-doc@FreeBSD.ORG Sun Mar 16 22:40:01 2014 Return-Path: Delivered-To: freebsd-doc@smarthost.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id D76222B4 for ; Sun, 16 Mar 2014 22:40:01 +0000 (UTC) Received: from freefall.freebsd.org (freefall.freebsd.org [IPv6:2001:1900:2254:206c::16:87]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id B3BB8C7A for ; Sun, 16 Mar 2014 22:40:01 +0000 (UTC) Received: from freefall.freebsd.org (localhost [127.0.0.1]) by freefall.freebsd.org (8.14.8/8.14.8) with ESMTP id s2GMe1NT011945 for ; Sun, 16 Mar 2014 22:40:01 GMT (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.14.8/8.14.8/Submit) id s2GMe1P4011944; Sun, 16 Mar 2014 22:40:01 GMT (envelope-from gnats) Resent-Date: Sun, 16 Mar 2014 22:40:01 GMT Resent-Message-Id: <201403162240.s2GMe1P4011944@freefall.freebsd.org> Resent-From: FreeBSD-gnats-submit@FreeBSD.org (GNATS Filer) Resent-To: freebsd-doc@FreeBSD.org Resent-Reply-To: FreeBSD-gnats-submit@FreeBSD.org, Andrew Merenbach 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 ; 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 ; 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 ; 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 To: freebsd-gnats-submit@FreeBSD.org X-Send-Pr-Version: www-3.1 Subject: docs/187644: ifconfig man page address_family paragraph needs clarification X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 16 Mar 2014 22:40:01 -0000 >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: