Chapter 3 Using the C Statistics API

The C Statistics API is used to retrieve information about the local configuration of Solaris Bandwidth Manager, and statistics for the classes of network traffic that are defined by the configuration.

It provides functions for the following types of operation:

• device handling

• interface handling

• class handling

• statistics handling

• event handling

• error handling

• memory handling

Linking with the Shared Library

The C Statistics API is implemented as the following shared library:

/opt/SUNWconn/lib/libba_stat.so.1

Your source code must include the following line:

#include <netinet/ba_stat.h>

To compile your application, use the cc(1B) command with the following switch:

-I/opt/SUNWconn/include

To link the shared library with your application, use the ld(1) command with the following switches:

-L/opt/SUNWconn/lib -R/opt/SUNWconn/lib -lba_stat

For example:

$ ld -o myexe myobj -L/opt/SUNWconn/lib -R/opt/SUNWconn/lib -lba_stat

For an example of how to use a Makefile to link your application, see the Makefile for the code examples, /opt/SUNWconn/ba/examples/Makefile.

Multithreading

The C Statistics API can be used safely in multithreaded mode, with the following restrictions:

• The same file descriptor is shared among all threads; therefore, all threads also share the same event mask. This means that if two threads call ba_get_next_event() at the same time, you cannot control which thread receives notification of the event.

• The ba_enable_signal() function should not be used in multithreaded mode, unless the signal mask has been correctly defined using the thr_sigsetmak() or pthread_sigmak() library functions.

• There is one variable ba_errno for each thread; therefore its value should always be checked in the thread from which the API was called.

Device Handling

The kernel module is viewed as a streams driver (/dev/ipqos) by the user process and as a streams module (ipqos) by the IP stack. The file /dev/ipqos is opened automatically by the first function call through the C Statistics API and its file descriptor is used to access the ipqos module.

The C Statistics API provides two functions that control the file /dev/ipqos directly:

• ba_open() opens the file /dev/ipqos and returns the file descriptor

• ba_close() closes the file /dev/ipqos

Interface Handling

The C Statistics API provides the following functions for interface handling:

• ba_encode_ifname()builds a Solaris Bandwidth Manager interface name from the interface's physical name and direction.

• ba_decode_ifname() extracts a physical interface name and direction from a Solaris Bandwidth Manager interface name.

• ba_get_num_interfaces() returns the number of interfaces that are managed by Solaris Bandwidth Manager.

• ba_list_interfaces() returns a list of the names of the interfaces that are managed by Solaris Bandwidth Manager.

• ba_get_interface_config() returns configuration information for a given interface.

• ba_list_interface_config() returns configuration information for all interfaces managed by Solaris Bandwidth Manager.

Class Handling

The C Statistics API provides the following functions for class handling:

• ba_get_num_classes() returns the number of classes that are defined for a given interface.

• ba_list_class_names() returns a list of the classes that are defined for a given interface, together with their respective parent classes.

• ba_list_classes() returns a list of the parent and child classes for a specified interface.

Statistics Handling

The C Statistics API provides the following functions for statistics handling:

• ba_get_class_stats() returns statistics for a given class of network traffic for a given interface. The information returned includes:

  • Number of packets sent

  • Number of bytes sent

  • Number of attempts made to borrow bandwidth

  • Number of packets dropped

  • Number of bytes dropped

• ba_reset_class_stats() is used to reset the statistics information for a given class and all its children. The process calling ba_reset_class_stats() must be privileged.

• ba_get_flow_stats() returns flow level statistics for the specified class.

Event Handling

The C Statistics API can be used to detect when certain events occur at the level of the ipqos module, and to return information about the event that has occurred. There are three ways to detect that an event has occurred:

• By using poll(2) or select(3c) to examine the file descriptor

• By enabling the device to send a signal directly to the user process

• By calling the function ba_get_next_event() to check for the next event

---

Note -

As events are buffered, if using poll(2) or select(3c), you must call ba_get_next_event() repeatedly in non-blocking mode to check that there are no outstanding events, to make sure that the next poll(2) works correctly.

---

Once you have detected that an event has occurred, for example, by using poll(2), call the function ba_get_next_event() to retrieve information about the event.

The C Statistics API provides the following functions for event handling:

• ba_set_event_mask() sets the event mask to indicate which of the events listed in Table 3-1 should be reported.

• ba_get_event_mask() retrieves the current event mask.

• ba_get_next_event() retrieves information about the most recent event that occurred.

• ba_enable_signal() enables the signalling mechanism so that the ipqos module can send a signal directly to the user process.

• ba_disable_signal() disables the signalling mechanism.

Table 3-1 lists the event types reported to the user process.

Table 3-1 Event Types

Event Type	Description
BA_EVENT_CONFIG_STARTING	Generated when the Solaris Bandwidth Manager policy agent starts to read a new configuration
BA_EVENT_CONFIG_ENDING	Generated when the Solaris Bandwidth Manager Policy Agent finishes reading a new configuration
BA_EVENT_DAEMON_ENDING	Generated when the Solaris Bandwidth Manager policy agent stops or is killed
BA_EVENT_FLOW_ACCOUNTING	Generated when a flow has timed out, or when the TOS field changes for a flow
BA_EVENT_STATS_RESET	Generated when a class has been reset or removed

To limit the number of events held in the buffer, edit the environment variable BA_EVENTBUFSIZE in the /etc/default/ba_info file. To buffer an unlimited number of events, set this value to 0, but note that this will lead to kernel memory exhaustion if all events are not retrieved.

Error Handling

If an error occurs during any call to the C Statistics API, the function returns with a value of -1, and the variable ba_errno is set to an error code that indicates the error condition. The possible error codes for ba_errno are listed in Table 4-2.

The C Statistics API provides the following functions for error handling:

• ba_strerror() returns the error message associated with an error code stored in ba_errno. It is equivalent to strerror(3C).

• ba_perror() prints the error code, followed by the error message returned by ba_strerror(), to standard output. It is equivalent to perror(3C).

---

Note -

Solaris Bandwidth Manager does not reset ba_errno following a successful function call. This means that the value of ba_errno is only valid when a function returns --1 to indicate an error condition.

---

Memory Handling

The C Statistics API uses two methods for allocating memory for arrays.

When using the ba_list_interfaces() and ba_list_class_names() functions, you must always allocate sufficient memory for the buffer, the size of which is dependent on the number of classes. For example, when using ba_list_interfaces():

nintface = ba_get_num_interfaces();
if (nintface > 0) {
	interfaces = (ba_name_t *) calloc(nintface, sizeof ba_name_t);
	if (ba_list_interfaces(interfaces) != -1) {
	/* process interfaces .. */
} else {
	/* error handling */
}
	free(interfaces);
}

When using the ba_list_interface_config(), ba_list_classes() and ba_get_flow_stats() functions, memory is allocated automatically. However, in this case the user must call the ba_free() function afterwards, in order to free this memory.

Examples

Solaris Bandwidth Manager includes the following examples:

• ba_classes.c returns a list of the classes configured for the specified interface. It illustrates the use of the class handling functions.

• ba_events.c prints event information as events occur, until the program is terminated with CTRL-C. It illustrates the use of the event handling functions.

• ba_get_stats.c returns the statistics information for a given class. It illustrates the use of the ba_get_class_stats() function.

• ba_interfaces.c returns a list of the configured interfaces. It illustrates the use of the interface handling functions.

• ba_reset_stats.c resets the statistics for a given class. It illustrates the use of the ba_reset_class_stats() function.

• ba_signals.c prints event information as events occur, until the program is terminated with CTRL-C. It illustrates the use of the event handling functions and the signalling mechanism.

• ba_get_flows.c recovers information about all of the flows associated with a particular class.

The examples are in the directory /opt/SUNWconn/ba/examples. This directory also contains a Makefile for the examples, Makefile.