NAME

ifstat.conf − interface configuration files for ifstat

DESCRIPTION

An ifstat.conf file contains configuration information for the ifstat utility.  The default ifstat.conf files are found in /etc/ifstat.conf.  A file consists of a device line followed by any number of code lines.  A line starting with the character "#" is considered a comment.  ifstat ignores the comment character and anything else on the line up to and including the new line character. 

The very first non-comment line in an ifstat.conf file must be the device line.  The device line has the following format:

device_name   action

Whitespace (space or tab characters) must appear between the two fields. The fields have the following meanings:

device_name
The name of the device that this configuration file corresponds to.  This is the full path name to the device.  If there exist multiple devices that are selectable by controller number, then the controller number should not appear in the device name.  For example, there may be multiple MVME376 Ethernet boards in a system.  The device_name field should be /dev/m376_c.  On the contrary, there is only one PPP device allowed in a system.  Its name is independent of a controller number, so the device_name would be /dev/ppp.  device_name may not be greater than 64 characters in length. 

action
The action must be one of append or ignore.  The former tells ifstat to append the controller number specified on its command line to device_name (see ifstat(1M)).  The latter action tells ifstat to ignore the controller number.  In our examples above, the MVME376 configuration file would specify append, while the PPP configuration file would specify ignore.  Note that in append mode, ifstat appends the controller string onto the end of the device_name string.  Again, this resultant string may not be greater than 64 characters in length. 

The rest of the file consists of code lines (plus any interspersed comment lines).  ifstat ignores any code lines beyond the 256th.  A code line has the following format:

code   :text

Whitespace may appear after the code as long as the ":" character precedes the text portion.  ifstat reads up to the first 256 characters (including new line character) of a code line.  Lines longer than this cause a parsing error.  The two fields have the following meanings:

code This field contains a numerical value specifying a code that the corresponding driver recognizes as a MACIOCSTAT code.  ifstat treats these codes as unsigned hexadecimal numbers.  All the codes listed in a configuration file correspond to a statistic found in the corresponding driver man page under the MACIOC_GETSTATS ioctl description.  Users creating their own (or modifying an existing) configuration file should examine a driver’s man page to learn all the available codes and their respective statistical meanings.  The code ffff is special.  It is ignored by the driver.  See following text field discussion for an example of its use. 

text The rest of the line (up to and including the new line character) after the ":" character is considered the text field.  ifstat uses this field as the format string to a printf system call when printing the statistic corresponding to code.  This text string must therefore contain exactly one conversion string (unless code is ffff).  Values returned from the driver are always unsigned integers, but the configuration file may interpret a value any way it likes.  A typical set of code lines could be:

ffff:These are the transmit-side statistics:
1   :    Number of transmit packets = %-10lu
2   :    Number of transmit errors  = %-10lu

The first code above would be ignored and the text string just printed.  The second two codes would have some meaning to the driver and the returned statistics would be printed using the conversion "%-10lu". 

Driver writers wishing to support the ifstat utility must support the MACIOC_GETSTATS ioctl.  Driver writers should examine the file sys/macioctl.h to learn more about how this ioctl operates.  In addition, driver writers must create a minimum of two configuration files.  The first should be named driver-prefix and the second driver-prefixall.  driver-prefix should be a short, descriptive name, preferably the same prefix used by ifconfig if the driver is usable under TCP/IP.  The latter file must contain all of the statistics obtainable by ifstat.  The former file should contain the most useful subset of statistics from the all file.  The former file should be short enough so that the resulting ifstat display fits on one screen without scrolling off the bottom. 

FILES

/etc/ifstat.conf/∗
/usr/include/sys/macioctl.h

SEE ALSO

ifconfig(1M), ifstat(1M), printf(3S), dlce(7), e1x7(7), lo(7), m376(7), m385(7), ppp(7), slip(7)