- Uniformly use .In for header file references.
[dragonfly.git] / share / man / man4 / ifmib.4
CommitLineData
984263bc
MD
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: src/share/man/man4/ifmib.4,v 1.8.2.6 2002/10/10 18:21:41 johan Exp $
44cb301e 29.\" $DragonFly: src/share/man/man4/ifmib.4,v 1.5 2006/05/26 19:39:39 swildner Exp $
984263bc
MD
30.\"
31.Dd November 15, 1996
32.Dt IFMIB 4
33.Os
34.Sh NAME
35.Nm ifmib
36.Nd Management Information Base for network interfaces
37.Sh SYNOPSIS
38.In sys/types.h
39.In sys/socket.h
40.In sys/sysctl.h
41.In sys/time.h
42.In net/if.h
43.In net/if_mib.h
44.Sh DESCRIPTION
45The
46.Nm
47facility is an application of the
48.Xr sysctl 3
49interface to provide management information about network interfaces
50to client applications such as
51.Xr netstat 1 ,
52.Xr slstat 8 ,
53and
54.Tn SNMP
6c164f53
HP
55management agents.
56This information is structured as a table, where
984263bc
MD
57each row in the table represents a logical network interface (either a
58hardware device or a software pseudo-device like
59.Xr lo 4 ) .
60There are two columns in the table, each containing a single
61structure: one column contains generic information relevant to all
62interfaces, and the other contains information specific to the
6c164f53
HP
63particular class of interface.
64(Generally the latter will implement
984263bc
MD
65the
66.Tn SNMP
67.Tn MIB
68defined for that particular interface class, if one exists and can be
69implemented in the kernel.)
70.Pp
71The
72.Nm
73facility is accessed via the
74.Dq Li net.link.generic
75branch of the
76.Xr sysctl 3
6c164f53
HP
77MIB.
78The manifest constants for each level in the
984263bc
MD
79.Xr sysctl 3
80.Ar name
81are defined in
44cb301e 82.In net/if_mib.h .
984263bc
MD
83A count of interfaces (and thus rows in the table) is given by
84.Dq Li net.link.generic.system.ifcount
85(or, using the manifest constants,
86.Dv CTL_NET ,
87.Dv PF_LINK ,
88.Dv NETLINK_GENERIC ,
89.Dv IFMIB_SYSTEM ,
90.Dv IFMIB_IFCOUNT ) .
91A management application searching for a particular interface should
92start with row 1 and continue through the table row-by-row until the
93desired interface is found, or the interface count is reached.
94.Pp
95The generic interface information, common to all interfaces,
96can be accessed via the following procedure:
97.Bd -literal -offset indent
98int
99get_ifmib_general(int row, struct ifmibdata *ifmd)
100{
101 int name[6];
102 size_t len;
103
104 name[0] = CTL_NET;
105 name[1] = PF_LINK;
106 name[2] = NETLINK_GENERIC;
107 name[3] = IFMIB_IFDATA;
108 name[4] = row;
109 name[5] = IFDATA_GENERAL;
110
111 len = sizeof(*ifmd);
112
113 return sysctl(name, 6, ifmd, &len, (void *)0, 0);
114}
115.Ed
116.Pp
117The fields in
118.Li struct ifmibdata
119are as follows:
120.Bl -tag -width "ifmd_snd_drops"
121.It Li ifmd_name
122.Pq Li "char []"
123the name of the interface, including the unit number
124.It Li ifmd_pcount
125.Pq Li int
126the number of promiscuous listeners
127.It Li ifmd_flags
128.Pq Li int
129the interface's flags (defined in
44cb301e 130.In net/if.h )
984263bc
MD
131.It Li ifmd_snd_len
132.Pq Li int
133the current instantaneous length of the send queue
134.It Li ifmd_snd_drops
135.Pq Li int
136the number of packets dropped at this interface because the send queue
137was full
138.It Li ifmd_data
139.Pq Li struct if_data
140more information from a structure defined in
44cb301e 141.In net/if.h
984263bc
MD
142(see
143.Xr if_data 9 )
144.El
145.Pp
146Class-specific information can be retrieved by examining the
147.Dv IFDATA_LINKSPECIFIC
6c164f53
HP
148column instead.
149Note that the form and length of the structure will
150depend on the class of interface.
151For
984263bc
MD
152.Dv IFT_ETHER ,
153.Dv IFT_ISO88023 ,
154and
155.Dv IFT_STARLAN
156interfaces, the structure is called
157.Dq Li struct ifmib_iso_8802_3
158(defined in
44cb301e 159.In net/if_mib.h ) ,
984263bc
MD
160and implements a superset of the
161.Tn "RFC 1650"
162MIB for Ethernet-like networks.
163.\" This will eventually be defined in an ethermib(4) page.
164For
165.Dv IFT_SLIP ,
166the structure is a
167.Dq Li struct sl_softc
44cb301e 168.Pq In net/sl/if_slvar.h .
984263bc
MD
169.Sh SEE ALSO
170.Xr sysctl 3 ,
171.Xr intro 4 ,
172.Xr ifnet 9
173.\" .Xr ethermib 4 ,
174.Rs
175.%T "Definitions of Managed Objects for the Ethernet-like Interface Types Using SMIv2"
176.%A F. Kastenholz
177.%D August 1994
178.%O RFC 1650
179.Re
ac561d34
SW
180.Sh HISTORY
181The
182.Nm
183interface first appeared in
184.Fx 2.2 .
984263bc
MD
185.Sh BUGS
186Many Ethernet-like interfaces do not yet support the Ethernet MIB;
187the interfaces known to support it include
188.Xr ed 4
189and
190.Xr de 4 .
191Regardless, all interfaces automatically support the generic MIB.