Go to main content

man pages section 3: Extended Library Functions, Volume 4

Exit Print View

Updated: July 2017



zs_usage, zs_usage_read, zs_usage_diff, zs_usage_free - read system configuration and utilization


cc [ flag ... ] file... -lzonestat [ libary ... ]
#include <zonestat.h>

zs_usage_t zs_usage_read(zs_ctl_t zsctl);
zs_usage_t zs_usage_diff(zs_usage_t u1, zs_usage_t u2);
void zs_usage_free(zs_usage_t zsctl);


The zs_usage_read() function reads the system configuration and utilization with respect to zones, memory, and CPU.

    Each zs_usage_read() will return a zs_usage_t object, which includes the following information:

  • The current system resources and their utilization.

  • The currently running zones. All properties reflect the current running state of each zone.

  • The usage of each resource by each zone.

  • The usage by each zone of its configured limits.

  • The currently existing processor sets. All properties and usages reflect the current running state of each processor set.

  • The usage of each processor set by each zone utilizing it.

Increasing utilization values are described libzonestat(3LIB). Increasing values continually increase, starting at zero from the point at which zs_open(3ZONESTAT) was first called.

For all other utilization values, utilization information will be the usage at the point in time at which zs_usage_read() is called.

For zones and processors sets that were booted or created after zs_open() was called, the increasing usage values will be usage since the most recent boot or creation before the call to zs_usage_read().

The zs_usage_diff() function computes and returns the utilization differences between two zs_usage_t objects returned by zs_usage_read(). Both u1 and u2 must be read from the same zsctl object. u2 must be read after u1.

The purpose of zs_usage_diff() is to simplify the comparison of zs_usage_read() calls made at a interval.

    The returned zs_usage_t object will contain:

  • The current system resources, as they exist in u2.

  • The zones and processor sets that exist in u2.

  • For increasing utilization values, the value of (u2 - u1). If a specific value does not exist in u1 (such as the CPU utilization for a zone in u2 which does not exist in u1), the value will be the value from u2.

  • For non-increasing utilization values, the value of u2.

The zs_usage_free() function frees the memory associated with a zs_usage_t object returned by zs_usage_read() or zs_usage_diff().

Return Values

On success, zs_usage_free() and zs_usage_diff() return a pointer to a zonestat usage object. On failure, zs_open() returns NULL.


The zs_usage_diff() function will fail if:


Insufficient resources are available.


Insufficient memory is available.

The zs_usage_read() function will fail if:


Insufficient resources are available.


A signal was caught.


Insufficient memory is available.


Unable to connect to the zones monitoring service. See Notes.


Example 1 Read zone CPU utilization.

The following example uses zs_usage_read() to read each zones CPU utilization at a regular interval.

#include <zonestat.h>
extern int time_to_quit; /* hypothetical quit notification */

zs_ctl_t ctl;
zs_usage_t last;
zs_usage_t next;
zs_usage_t diff;
zs_zone_t zone;
timestruct_t time;
uint64_t cpus;

ctl = zs_usage_open();  /* Open zone statistics */
last = zs_usage_read(); /* Read initial usage */
for (;;) {

        next = zs_usage_read();
        diff = zs_usage_diff(last, next);

        /* Walk zones in usage data */
        for (zone = zs_zone_first(diff); zone != NULL ;
            zone = zs_zone_next(diff, zone)) {

                 * fetch cpu time used by zone over interval in terms of
                 * seconds and nanoseconds
                zs_resource_used_zone_time(zone, ZS_RESOURCE_CPU,

                 * fetch cpu time used by zone over interval in terms of
                 * cpu used.  100 equals one cpu.  For example, a
                 * value of 250 means the zone used 2.5 cpus worth of
                 * time between last and next.
                zs_resource_used_zone_uint64(zone, ZS_RESOURCE_CPU,

        last = next;

        if (time_to_quit)


See attributes(5) for descriptions of the following attributes:

Interface Stability
See below.

The zs_usage_*() functions are MT-safe, with the exception that only one thread may actively use a zs_ctl_t * object at any time. Synchronization is left to the application.

See Also

zonestat(1), pooladm(1M), psrset(1M), rcapadm(1M), swap(1M), zoneadm(1M), zonestatd(1M), libpool(3LIB), libzonestat(3LIB), zs_open(3ZONESTAT), zs_pset(3ZONESTAT), zs_property(3ZONESTAT), zs_pset_zone(3ZONESTAT), zs_resource(3ZONESTAT), zs_zone(3ZONESTAT), attributes(5), resource-controls(5)


The service svc:/system/zones-monitoring:default must be enabled in the global zone in order for zs_usage_read() to succeed. This requirement exists for use of libzonestat(3LIB) in both the global zone and non-global zones.

If the zones-monitoring service goes off line, ESRCH will be returned. At this point the zsctl object is no longer usable. Use zs_close(zsctl) and use zs_open(3ZONESTAT) to reconnect.