]> git.saurik.com Git - apple/xnu.git/blob - bsd/man/man4/ifmib.4
xnu-3789.70.16.tar.gz
[apple/xnu.git] / bsd / 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: /repoman/r/ncvs/src/share/man/man4/ifmib.4,v 1.20 2004/07/03 18:29:20 ru Exp $
29 .\"
30 .Dd November 15, 1996
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 .\" This will eventually be defined in an ethermib(4) page.
169 For
170 .Dv IFT_SLIP ,
171 the structure is a
172 .Dq Li struct sl_softc
173 .Pq In net/if_slvar.h .
174 .Sh SEE ALSO
175 .Xr sysctl 3 ,
176 .Xr intro 4 ,
177 .Xr ifnet 9
178 .\" .Xr ethermib 4 ,
179 .Rs
180 .%T "Definitions of Managed Objects for the Ethernet-like Interface Types Using SMIv2"
181 .%A F. Kastenholz
182 .%D August 1994
183 .%O RFC 1650
184 .Re
185 .Sh BUGS
186 Many Ethernet-like interfaces do not yet support the Ethernet MIB;
187 the interfaces known to support it include
188 .Xr ed 4
189 and
190 .Xr de 4 .
191 Regardless, all interfaces automatically support the generic MIB.
192 .Sh HISTORY
193 The
194 .Nm
195 interface first appeared in
196 .Fx 2.2 .