/share/man/man4/ifmib.4

https://bitbucket.org/freebsd/freebsd-head/ · Forth · 190 lines · 187 code · 3 blank · 0 comment · 9 complexity · 8d5558f8f6b29a6c20669a9894baad38 MD5 · raw file

  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. name[0] = CTL_NET;
  109. name[1] = PF_LINK;
  110. name[2] = NETLINK_GENERIC;
  111. name[3] = IFMIB_IFDATA;
  112. name[4] = row;
  113. name[5] = IFDATA_GENERAL;
  114. len = sizeof(*ifmd);
  115. return sysctl(name, 6, ifmd, &len, (void *)0, 0);
  116. }
  117. .Ed
  118. .Pp
  119. The fields in
  120. .Li struct ifmibdata
  121. are as follows:
  122. .Bl -tag -width "ifmd_snd_drops"
  123. .It Li ifmd_name
  124. .Pq Li "char []"
  125. the name of the interface, including the unit number
  126. .It Li ifmd_pcount
  127. .Pq Li int
  128. the number of promiscuous listeners
  129. .It Li ifmd_flags
  130. .Pq Li int
  131. the interface's flags (defined in
  132. .In net/if.h )
  133. .It Li ifmd_snd_len
  134. .Pq Li int
  135. the current instantaneous length of the send queue
  136. .It Li ifmd_snd_drops
  137. .Pq Li int
  138. the number of packets dropped at this interface because the send queue
  139. was full
  140. .It Li ifmd_data
  141. .Pq Li struct if_data
  142. more information from a structure defined in
  143. .In net/if.h
  144. (see
  145. .Xr if_data 9 )
  146. .El
  147. .Pp
  148. Class-specific information can be retrieved by examining the
  149. .Dv IFDATA_LINKSPECIFIC
  150. column instead.
  151. Note that the form and length of the structure will
  152. depend on the class of interface.
  153. For
  154. .Dv IFT_ETHER ,
  155. .Dv IFT_ISO88023 ,
  156. and
  157. .Dv IFT_STARLAN
  158. interfaces, the structure is called
  159. .Dq Li struct ifmib_iso_8802_3
  160. (defined in
  161. .In net/if_mib.h ) ,
  162. and implements a superset of the
  163. .Tn "RFC 1650"
  164. MIB for Ethernet-like networks.
  165. .Sh SEE ALSO
  166. .Xr sysctl 3 ,
  167. .Xr intro 4 ,
  168. .Xr ifnet 9
  169. .\" .Xr ethermib 4 ,
  170. .Rs
  171. .%T "Definitions of Managed Objects for the Ethernet-like Interface Types Using SMIv2"
  172. .%A F. Kastenholz
  173. .%D August 1994
  174. .%O RFC 1650
  175. .Re
  176. .Sh HISTORY
  177. The
  178. .Nm
  179. interface first appeared in
  180. .Fx 2.2 .
  181. .Sh BUGS
  182. Many Ethernet-like interfaces do not yet support the Ethernet MIB;
  183. the interfaces known to support it include
  184. .Xr ed 4
  185. and
  186. .Xr de 4 .
  187. Regardless, all interfaces automatically support the generic MIB.