, zs_pset_zone_list

, zs_pset_zone_walk

, zs_pset_zone_get_zone

, zs_pset_zone_get_pset

, zs_pset_zone_property

, zs_pset_zone_used_time

, zs_pset_zone_used_cpus

, zs_pset_zone_used_pct

- libzonestat accessor methods for per-zone utilization of psets

Synopsis

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

int zs_pset_zone_list(zs_pset_t pset, zs_pset_zone_t *pzlist, int num);

zs_pset_zone_t zs_pset_zone_walk(zs_pset_t pset, zs_pset_zone_t pz);

zs_zone_t zs_pset_zone_get_zone(zs_pset_zone_t pz);

zs_pset_t zs_pset_zone_get_pset(zs_pset_zone_t pz);

zs_property_t zs_pset_zone_property(zs_pset_zone_t pz,
     zs_pz_property_t prop);

void zs_pset_zone_used_time(zs_pset_zone_t pz, timestruc_t *ts);

uint64_t zs_pset_zone_used_cpus(zs_pset_zone_t pz);

uint_t zs_pset_zone_used_pct(zs_pset_zone_t pz, zs_pz_pct_t pct);

Description

These functions are used to access the per-zone utilization information for a given pset. Each pset will have zero or more zones bound to it.

Typically, a zone will be bound to a single pset, but it is possible for the global zone to be bound to multiple psets, as well as non-global zones if psrset(1M) psets are used.

If a zone is bound to multiple psets, it's CPUs shares will be applied to each pset. For instance, if a zone has 10 shares, and has processes in both pset A and pset B, then the zone will have 10 shares in both pset A and pset B. The relative value of those shares will depend on the other zones running in each pset, and how many shares the other zones have.

If a zone is bound to multiple psets, then its CPU cap is applied across all psets. The zone may use up to its cap in CPU time. Some of this time could be spent in pset A, and the rest in pset B. Each zone does not get its full CPU cap per pset.

The zs_pset_zone_list() function returns the number of zs_pset_zone_t objects contained within pset. If pzlist is non-NULL, the pzlist array will be filled with up to num zs_pset_zone_t objects. The pzlist array must be first allocated by the caller. The zs_pset_zone_t objects will be returned in alphanumeric ordered by zone name.

The zs_pset_zone_walk() function is used to walk the list of zones using a pset. Zones are walked in alphanumeric order. If pz is NULL, the first zone is returned, otherwise the zone after pz is returned. NULL is returned if there are no more zones using the pset.

The zs_pset_zone_get_zone() function returns the zs_zone_t object representing the zone for pz.

The zs_pset_zone_get_pset() function returns the zs_pset_t object representing the pset for pz.

The zs_pset_zone_property() function will return the prop property of a pz. See libzonestat(3LIB) for a description of the ZS_PZ_PROP_* property codes.

The zs_pset_zone_used_time() function sets ts to the total CPU time that has been used in the pset by the zone, starting at zero from the point when zs_open(3ZONESTAT) was first called.

The zs_pset_zone_used_cpus() function sets ts to the total number of CPUs that has been used in the pset by the zone, starting at zero from the point when zs_open() was first called. The value returned is the number of CPUs used * 100. For example, if the zone used 1.5 CPUs in the pset, the returned value will be 1500.

The zs_pset_zone_used_pct() function returns the percentage of pct used by the zone in the pset. See the description of the ZS_PZ_PCT_* codes on the libzonestat(3LIB) manual page.

Return Values

See Description.

Errors

If a zs_pset_zone_*() function is called with an invalid property or pct code, the function will abort with abort(3C).

Examples

Example 1 Walk the list of zones and retrieve CPU data.

The following example walks the list of zones using the default pset, retrieving both the CPU shares and CPU cap, as well as the percent of each used.

#include <zonestat.h>
#include <strings.h>
...
extern zs_usage_t usage;        /* assume returned by zs_usage_read() */
...
zs_pset_t pset;
zs_pset_zone_t pz;
zs_property_t prop;
char *psetname;
char *zonename;
uint64_t shares;
uint64_t cap;
uint_t pct_shares;
uint_t pct_cap;

/* Get default pset and name, which is always the first pset */
pset = zs_pset_first(usage);
zs_pset_property(pset, ZS_PROP_PSET_NAME prop);
psetname = strdup(zs_property_string(prop));

for (pz = zs_pset_zone_first(pset); pz != NULL;
    pz = zs_pset_zone_next(pset, pz)) {

    /* Get name of zone */
    zone = zs_pset_zone_get_zone(pz);
    prop = zs_zone_property(pset, ZS_PROP_ZONE_NAME);
    zonename = strdup(zs_property_string(prop));

    /* get shares and cap */
    prop = zs_pset_zone_property(pz, ZS_PZ_PROP_CPU_SHARES);
    shares = zs_property_uint64(prop);
    prop = zs_pset_zone_property(pz, ZS_PZ_PROP_CPU_CAP);
    cap = zs_property_uint64(prop);

    /* get percent used of shares and cap */
    pct_shares = zs_pset_zone_used_pct(pz, ZS_PZ_PCT_CPU_SHARE);
    pct_cap = zs_pset_used_cpus(pz, ZS_PZ_PCT_CPU_CAP);
}

Attributes

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

See Also

zonestat(1), pooladm(1M), psrset(1M), rcapadm(1M), swap(1M), zoneadm(1M), zonestatd(1M), abort(3C), libpool(3LIB), libzonestat(3LIB), zs_open(3ZONESTAT), zs_property(3ZONESTAT), zs_pset(3ZONESTAT), zs_resource(3ZONESTAT), zs_usage(3ZONESTAT), zs_zone(3ZONESTAT), attributes(5), resource_controls(5)