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().
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.
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 (;;) {
sleep(10);
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,
&time);
/*
* 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,
&cpus;
}
zs_usage_free(diff);
zs_usage_free(last);
last = next;
if (time_to_quit)
break;
}
zs_usage_free(last)
See attributes(5) for descriptions of the following attributes:
|
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.
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.