/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
 44The
 45.Nm
 46facility is an application of the
 47.Xr sysctl 3
 48interface to provide management information about network interfaces
 49to client applications such as
 50.Xr netstat 1 ,
 51.Xr slstat 8 ,
 52and
 53.Tn SNMP
 54management agents.
 55This information is structured as a table, where
 56each row in the table represents a logical network interface (either a
 57hardware device or a software pseudo-device like
 58.Xr lo 4 ) .
 59There are two columns in the table, each containing a single
 60structure: one column contains generic information relevant to all
 61interfaces, and the other contains information specific to the
 62particular class of interface.
 63(Generally the latter will implement
 64the
 65.Tn SNMP
 66.Tn MIB
 67defined for that particular interface class, if one exists and can be
 68implemented in the kernel.)
 69.Pp
 70The
 71.Nm
 72facility is accessed via the
 73.Dq Li net.link.generic
 74branch of the
 75.Xr sysctl 3
 76MIB.
 77The manifest constants for each level in the
 78.Xr sysctl 3
 79.Ar name
 80are defined in
 81.In net/if_mib.h .
 82The 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 ) .
 90A management application searching for a particular interface should
 91start with row 1 and continue through the table row-by-row until the
 92desired interface is found, or the interface count is reached.
 93Note that the table may be sparse, i.e., a given row may not exist,
 94indicated by an
 95.Va errno
 96of
 97.Er ENOENT .
 98Such an error should be ignored, and the next row should be checked.
 99.Pp
100The generic interface information, common to all interfaces,
101can be accessed via the following procedure:
102.Bd -literal -offset indent
103int
104get_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
122The fields in
123.Li struct ifmibdata
124are as follows:
125.Bl -tag -width "ifmd_snd_drops"
126.It Li ifmd_name
127.Pq Li "char []"
128the name of the interface, including the unit number
129.It Li ifmd_pcount
130.Pq Li int
131the number of promiscuous listeners
132.It Li ifmd_flags
133.Pq Li int
134the interface's flags (defined in
135.In net/if.h )
136.It Li ifmd_snd_len
137.Pq Li int
138the current instantaneous length of the send queue
139.It Li ifmd_snd_drops
140.Pq Li int
141the number of packets dropped at this interface because the send queue
142was full
143.It Li ifmd_data
144.Pq Li struct if_data
145more information from a structure defined in
146.In net/if.h
147(see
148.Xr if_data 9 )
149.El
150.Pp
151Class-specific information can be retrieved by examining the
152.Dv IFDATA_LINKSPECIFIC
153column instead.
154Note that the form and length of the structure will
155depend on the class of interface.
156For
157.Dv IFT_ETHER ,
158.Dv IFT_ISO88023 ,
159and
160.Dv IFT_STARLAN
161interfaces, the structure is called
162.Dq Li struct ifmib_iso_8802_3
163(defined in
164.In net/if_mib.h ) ,
165and implements a superset of the
166.Tn "RFC 1650"
167MIB 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
180The
181.Nm
182interface first appeared in
183.Fx 2.2 .
184.Sh BUGS
185Many Ethernet-like interfaces do not yet support the Ethernet MIB;
186the interfaces known to support it include
187.Xr ed 4
188and
189.Xr de 4 .
190Regardless, all interfaces automatically support the generic MIB.