xnetload1

Usage

Overview

This manual page documents version 1.11 of xnetload, a program that displays the number of bytes (or packets) transmitted per second in and out of the system over a network connection, in an X window. If the interface it is assigned to monitor goes offline, xnetload terminates itself.

The first line of test displays the interface that this instance of xnetload is monitoring, and the amount of time that has passed since the program was started. This is very useful to keep track of how long you've been online in case of a dail-up connection. Displaying this line can be turned off by using the -ni switch or setting the noInterface resource to True.

Next follow a line of text showing the incoming bytes. Three numbers are shown; the current value, the maximum value seen in this session (between ()), and the amount of bytes received (between []). Showing this line can be turned off by using the -nv switch or setting the noValues resource to True. The number of bytes is averaged over the last five samples by default. Also by default, the samples are taken and the screen is updated every second.

Below that is a graphical representation of the incoming stream. The graph displays log10 of the numbers of bytes by default, but it can also show the amount in kilobytes (by using the -kb switch). The kilobytes value can be scaled by a command-line parameter (-s factor).

The line of text and the graph are repeated for outgoing bytes.

This program requires the /proc filesystem. If you want to display (k)bytes/s you'll need a 2.1.x kernel or newer kernel. As of version 1.7.0, support for ip-accounting for 2.0.x kernels is dropped. Version 1.6.1 is still available for those wishing to use ip-accounting on a 2.0.x kernel.

Options

This program accepts the standard X Toolkit Intrinsics options (see X(1)).

It accepts the following additional options:

-? or -h or --help or no arguments

This prints a short help message.

-novalues or -nv

This inhibits showing the traffic numbers.

-nointerface or -ni

This inhibits showing of the "interface" line at the top of the window. Combining -nv and -ni comes in handy when using xnetload as a dock applet.

-nocharts or -nc

This inhibits the display of packet traffic graphs.

-kilobytes or -kb

Display the chart/values as kilobytes. This doesn't work on a 2.0.x kernel, since there is no byte count in /proc/net/dev in those kernels.

-scale factor or -s factor

Scales the kilobytes display by a given value, which must be > 1. Used in combination with -kilobytes or -kb.

-u seconds, -update seconds

Number of seconds between screen updates. The default is 1 second.

-a count or -average count

The number of samples that is averaged. The values and graphs show this average. The default value is 5 samples.

-interface interface or -if interface or interface

The name of the network interface to monitor, e.g. lo for the loopback device, or sl0 for the first slip device.

-zeroonreset or -zr

Resets the counters to zero, if the interface has gone down, or the counter in the kernel has rolled over.

Resources

In addition to the resources available to the widget, xnetload also defines the following custom application resources:

interface (class Interface)

The name of the network interface to monitor. This is set by the command-line option -if.

noValues (class NoValues)

This is a boolean value that, if True, inhibits the display of the packet count value. It defaults to False. This resource can be set to True on the command-line by specifying the -nv option.

noInterface (class NoInterface)

This is a boolean value that, if True, inhibits the display of the interface line at the top of the window. It defaults to False. This resource can be set to True on the command-line by specifying the -ni option.

noCharts (class NoCharts)

This is a boolean value that, if True, inhibits the display of the packet count graph. It defaults to False. Specifying the -nc option on the command-line sets this resource to True.

kilobytes (class Kilobytes)

This boolean makes the program convert the values it reads to kilobytes. It defaults to False. Specifying the -kb option on the command-line sets this resource to True.

scale (class Scale)

This value makes the program scale the graph by the given amount, if the graph is showing kilobytes. This resource can also be specified on the command-line via the -s option.

upd (class Upd)

Number of seconds between updates. This resource can also be set on the command-line with the -u or -update option.

agv (class Avg)

The number of samples that is averaged. This resource can also be set on the command-line with the -a or -average option.

zeroOnReset (class ZeroOnReset)

Resets the counters to zero, if the interface has gone down, or the counter in the kernel has rolled over. This resource can also be set on the command-line with the -zr or -zeroonreset option.

Widgets

The widget tree for xnetload is as shown below. It shows the widget class name followed by the widget instance name.

XNetload xnetload
   Paned paned
       Label interface
       Label in
       StripChart str_in
       Label out
       StripChart str_out

If the -nocharts option is given, or the noCharts resource is set to True, the StripCharts are missing.

If the -novalues option is given, or the noValues resource is set to True, the Labels in and out are missing.

If the -nointerface option is given, or the noInterface resource is set to True, the Label interface is missing.

Files

/proc/net/dev -- network device statistics for Linux.

XNetload -- application defaults file.

Diagnostics

The following messages can be generated on the console:

No network interface specified

The interface argument on the command line was omitted.

Could not open /proc/net/dev

Opening the /proc/net/dev file failed. xnetload reads the data it displays from this file. Make sure it exists and is readable. Try `cat /proc/net/dev'. If this returns the error `No such file or directory' you need to enable the /proc filesystem in the Linux kernel.

Interface not found in /proc/net/dev

The interface you've specified is not listed in /proc/net/dev. Try `cat /proc/net/dev' and see what interfaces are listed. Maybe you misspelled the name?

Error scanning /proc/net/dev

There was an error scanning the counts from /proc/net/dev. There might have been a change in the format of these files (especially in the development kernels). Please send the maintainer a listing of that file.

Not enough memory to read /proc/net/dev

The program couldn't allocate enough memory to contain the whole /proc/net/dev file.

Average count must be > 0

You specified a negative number with the -a or -average options, or the avg resource. This is not allowed.

Scale must be > 1

You specified a small or negative number with the -s or -scale options, or the scale resource. This is not allowed.

Update time must be > 0

You specified a negative number with the -u or -update options, or the upd resource. This is not allowed.

Memory allocation error

The program could not get the memory it needs to operate. Maybe you have specified a huge average count, or your system has very little memory and/or swap space.