share/man/man4/ifmib.4

   1 .\" Copyright 1996 Massachusetts Institute of Technology
   2 .\"
   3 .\" Permission to use, copy, modify, and distribute this software and
   4 .\" its documentation for any purpose and without fee is hereby
   5 .\" granted, provided that both the above copyright notice and this
   6 .\" permission notice appear in all copies, that both the above
   7 .\" copyright notice and this permission notice appear in all
   8 .\" supporting documentation, and that the name of M.I.T. not be used
   9 .\" in advertising or publicity pertaining to distribution of the
  10 .\" software without specific, written prior permission.  M.I.T. makes
  11 .\" no representations about the suitability of this software for any
  12 .\" purpose.  It is provided "as is" without express or implied
  13 .\" warranty.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY M.I.T. ``AS IS''.  M.I.T. DISCLAIMS
  16 .\" ALL EXPRESS OR IMPLIED WARRANTIES WITH REGARD TO THIS SOFTWARE,
  17 .\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
  18 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT
  19 .\" SHALL M.I.T. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  20 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  21 .\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  22 .\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  23 .\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  24 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  25 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\" $FreeBSD$
  29 .\"
  30 .Dd October 28, 2009
  31 .Dt IFMIB 4
  32 .Os
  33 .Sh NAME
  34 .Nm ifmib
  35 .Nd Management Information Base for network interfaces
  36 .Sh SYNOPSIS
  37 .In sys/types.h
  38 .In sys/socket.h
  39 .In sys/sysctl.h
  40 .In sys/time.h
  41 .In net/if.h
  42 .In net/if_mib.h
  43 .Sh DESCRIPTION
  44 The
  45 .Nm
  46 facility is an application of the
  47 .Xr sysctl 3
  48 interface to provide management information about network interfaces
  49 to client applications such as
  50 .Xr netstat 1 ,
  51 .Xr slstat 8 ,
  52 and
  53 .Tn SNMP
  54 management agents.
  55 This information is structured as a table, where
  56 each row in the table represents a logical network interface (either a
  57 hardware device or a software pseudo-device like
  58 .Xr lo 4 ) .
  59 There are two columns in the table, each containing a single
  60 structure: one column contains generic information relevant to all
  61 interfaces, and the other contains information specific to the
  62 particular class of interface.
  63 (Generally the latter will implement
  64 the
  65 .Tn SNMP
  66 .Tn MIB
  67 defined for that particular interface class, if one exists and can be
  68 implemented in the kernel.)
  69 .Pp
  70 The
  71 .Nm
  72 facility is accessed via the
  73 .Dq Li net.link.generic
  74 branch of the
  75 .Xr sysctl 3
  76 MIB.
  77 The manifest constants for each level in the
  78 .Xr sysctl 3
  79 .Ar name
  80 are defined in
  81 .In net/if_mib.h .
  82 The index of the last row in the table is given by
  83 .Dq Li net.link.generic.system.ifcount
  84 (or, using the manifest constants,
  85 .Dv CTL_NET ,
  86 .Dv PF_LINK ,
  87 .Dv NETLINK_GENERIC ,
  88 .Dv IFMIB_SYSTEM ,
  89 .Dv IFMIB_IFCOUNT ) .
  90 A management application searching for a particular interface should
  91 start with row 1 and continue through the table row-by-row until the
  92 desired interface is found, or the interface count is reached.
  93 Note that the table may be sparse, i.e., a given row may not exist,
  94 indicated by an
  95 .Va errno
  96 of
  97 .Er ENOENT .
  98 Such an error should be ignored, and the next row should be checked.
  99 .Pp
 100 The generic interface information, common to all interfaces,
 101 can be accessed via the following procedure:
 102 .Bd -literal -offset indent
 103 int
 104 get_ifmib_general(int row, struct ifmibdata *ifmd)
 105 {
 106         int name[6];
 107         size_t len;
 108
 109         name[0] = CTL_NET;
 110         name[1] = PF_LINK;
 111         name[2] = NETLINK_GENERIC;
 112         name[3] = IFMIB_IFDATA;
 113         name[4] = row;
 114         name[5] = IFDATA_GENERAL;
 115
 116         len = sizeof(*ifmd);
 117
 118         return sysctl(name, 6, ifmd, &len, (void *)0, 0);
 119 }
 120 .Ed
 121 .Pp
 122 The fields in
 123 .Li struct ifmibdata
 124 are as follows:
 125 .Bl -tag -width "ifmd_snd_drops"
 126 .It Li ifmd_name
 127 .Pq Li "char []"
 128 the name of the interface, including the unit number
 129 .It Li ifmd_pcount
 130 .Pq Li int
 131 the number of promiscuous listeners
 132 .It Li ifmd_flags
 133 .Pq Li int
 134 the interface's flags (defined in
 135 .In net/if.h )
 136 .It Li ifmd_snd_len
 137 .Pq Li int
 138 the current instantaneous length of the send queue
 139 .It Li ifmd_snd_drops
 140 .Pq Li int
 141 the number of packets dropped at this interface because the send queue
 142 was full
 143 .It Li ifmd_data
 144 .Pq Li struct if_data
 145 more information from a structure defined in
 146 .In net/if.h
 147 (see
 148 .Xr if_data 9 )
 149 .El
 150 .Pp
 151 Class-specific information can be retrieved by examining the
 152 .Dv IFDATA_LINKSPECIFIC
 153 column instead.
 154 Note that the form and length of the structure will
 155 depend on the class of interface.
 156 For
 157 .Dv IFT_ETHER ,
 158 .Dv IFT_ISO88023 ,
 159 and
 160 .Dv IFT_STARLAN
 161 interfaces, the structure is called
 162 .Dq Li struct ifmib_iso_8802_3
 163 (defined in
 164 .In net/if_mib.h ) ,
 165 and implements a superset of the
 166 .Tn "RFC 1650"
 167 MIB for Ethernet-like networks.
 168 .Sh SEE ALSO
 169 .Xr sysctl 3 ,
 170 .Xr intro 4 ,
 171 .Xr ifnet 9
 172 .\" .Xr ethermib 4 ,
 173 .Rs
 174 .%T "Definitions of Managed Objects for the Ethernet-like Interface Types Using SMIv2"
 175 .%A F. Kastenholz
 176 .%D August 1994
 177 .%O RFC 1650
 178 .Re
 179 .Sh HISTORY
 180 The
 181 .Nm
 182 interface first appeared in
 183 .Fx 2.2 .
 184 .Sh BUGS
 185 Many Ethernet-like interfaces do not yet support the Ethernet MIB;
 186 the interfaces known to support it include
 187 .Xr ed 4
 188 and
 189 .Xr de 4 .
 190 Regardless, all interfaces automatically support the generic MIB.