[apple/xnu.git] / bsd / man / man4 / ifmib.4

.\" Copyright 1996 Massachusetts Institute of Technology
.\"
.\" Permission to use, copy, modify, and distribute this software and
.\" its documentation for any purpose and without fee is hereby
.\" granted, provided that both the above copyright notice and this
.\" permission notice appear in all copies, that both the above
.\" copyright notice and this permission notice appear in all
.\" supporting documentation, and that the name of M.I.T. not be used
.\" in advertising or publicity pertaining to distribution of the
.\" software without specific, written prior permission.  M.I.T. makes
.\" no representations about the suitability of this software for any
.\" purpose.  It is provided "as is" without express or implied
.\" warranty.
.\"
.\" THIS SOFTWARE IS PROVIDED BY M.I.T. ``AS IS''.  M.I.T. DISCLAIMS
.\" ALL EXPRESS OR IMPLIED WARRANTIES WITH REGARD TO THIS SOFTWARE,
.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT
.\" SHALL M.I.T. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
.\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD: /repoman/r/ncvs/src/share/man/man4/ifmib.4,v 1.20 2004/07/03 18:29:20 ru Exp $
.\"
.Dd November 15, 1996
.Dt IFMIB 4
.Os
.Sh NAME
.Nm ifmib
.Nd Management Information Base for network interfaces
.Sh SYNOPSIS
.In sys/types.h
.In sys/socket.h
.In sys/sysctl.h
.In sys/time.h
.In net/if.h
.In net/if_mib.h
.Sh DESCRIPTION
The
.Nm
facility is an application of the
.Xr sysctl 3
interface to provide management information about network interfaces
to client applications such as
.Xr netstat 1 ,
.Xr slstat 8 ,
and
.Tn SNMP
management agents.
This information is structured as a table, where
each row in the table represents a logical network interface (either a
hardware device or a software pseudo-device like
.Xr lo 4 ) .
There are two columns in the table, each containing a single
structure: one column contains generic information relevant to all
interfaces, and the other contains information specific to the
particular class of interface.
(Generally the latter will implement
the
.Tn SNMP
.Tn MIB
defined for that particular interface class, if one exists and can be
implemented in the kernel.)
.Pp
The
.Nm
facility is accessed via the
.Dq Li net.link.generic
branch of the
.Xr sysctl 3
MIB.
The manifest constants for each level in the
.Xr sysctl 3
.Ar name
are defined in
.In net/if_mib.h .
The index of the last row in the table is given by
.Dq Li net.link.generic.system.ifcount
(or, using the manifest constants,
.Dv CTL_NET ,
.Dv PF_LINK ,
.Dv NETLINK_GENERIC ,
.Dv IFMIB_SYSTEM ,
.Dv IFMIB_IFCOUNT ) .
A management application searching for a particular interface should
start with row 1 and continue through the table row-by-row until the
desired interface is found, or the interface count is reached.
Note that the table may be sparse, i.e., a given row may not exist,
indicated by an
.Va errno
of
.Er ENOENT .
Such an error should be ignored, and the next row should be checked.
.Pp
The generic interface information, common to all interfaces,
can be accessed via the following procedure:
.Bd -literal -offset indent
int
get_ifmib_general(int row, struct ifmibdata *ifmd)
{
	int name[6];
	size_t len;

	name[0] = CTL_NET;
	name[1] = PF_LINK;
	name[2] = NETLINK_GENERIC;
	name[3] = IFMIB_IFDATA;
	name[4] = row;
	name[5] = IFDATA_GENERAL;

	len = sizeof(*ifmd);

	return sysctl(name, 6, ifmd, &len, (void *)0, 0);
}
.Ed
.Pp
The fields in
.Li struct ifmibdata
are as follows:
.Bl -tag -width "ifmd_snd_drops"
.It Li ifmd_name
.Pq Li "char []"
the name of the interface, including the unit number
.It Li ifmd_pcount
.Pq Li int
the number of promiscuous listeners
.It Li ifmd_flags
.Pq Li int
the interface's flags (defined in
.In net/if.h )
.It Li ifmd_snd_len
.Pq Li int
the current instantaneous length of the send queue
.It Li ifmd_snd_drops
.Pq Li int
the number of packets dropped at this interface because the send queue
was full
.It Li ifmd_data
.Pq Li struct if_data
more information from a structure defined in
.In net/if.h
(see
.Xr if_data 9 )
.El
.Pp
Class-specific information can be retrieved by examining the
.Dv IFDATA_LINKSPECIFIC
column instead.
Note that the form and length of the structure will
depend on the class of interface.
For
.Dv IFT_ETHER ,
.Dv IFT_ISO88023 ,
and
.Dv IFT_STARLAN
interfaces, the structure is called
.Dq Li struct ifmib_iso_8802_3
(defined in
.In net/if_mib.h ) ,
and implements a superset of the
.Tn "RFC 1650"
MIB for Ethernet-like networks.
.\" This will eventually be defined in an ethermib(4) page.
For
.Dv IFT_SLIP ,
the structure is a
.Dq Li struct sl_softc
.Pq In net/if_slvar.h .
.Sh SEE ALSO
.Xr sysctl 3 ,
.Xr intro 4 ,
.Xr ifnet 9
.\" .Xr ethermib 4 ,
.Rs
.%T "Definitions of Managed Objects for the Ethernet-like Interface Types Using SMIv2"
.%A F. Kastenholz
.%D August 1994
.%O RFC 1650
.Re
.Sh BUGS
Many Ethernet-like interfaces do not yet support the Ethernet MIB;
the interfaces known to support it include
.Xr ed 4
and
.Xr de 4 .
Regardless, all interfaces automatically support the generic MIB.
.Sh HISTORY
The
.Nm
interface first appeared in
.Fx 2.2 .
Commit	Line	Data
91447636 A	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 .