'\" te
.\" Copyright (c) 2011, 2015, Oracle and/or its affiliates. All rights                reserved.
.TH zs_resource 3ZONESTAT "21 May 2015" "SunOS 5.11" "Zones Statistics Library Functions"
.SH NAME
zs_resource, zs_resource_property, zs_resource_type, zs_resource_total_uint64, zs_resource_total_time, zs_resource_used_uint64, zs_resource_used_time, zs_resource_used_pct, zs_resource_used_zone_uint64, zs_resource_used_zone_time, zs_resource_used_zone_pct \- libzonestat resource accessor methods
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR ... ] \fIfile\fR... -lzonestat [ \fIlibary\fR ... ]
#include <zonestat.h>

zs_property_t zs_resource_property(zs_usage_t \fIusage\fR,
      zs_resource_property_t \fIprop\fR);
.fi

.LP
.nf
zs_resource_type_t zs_resource_type(zs_resource_t \fIresource\fR);
.fi

.LP
.nf
uint64_t zs_resource_total_uint64(zs_usage_t \fIusage\fR,
     zs_resource_t \fIresource\fR);
.fi

.LP
.nf
void zs_resource_total_time(zs_usage_t \fIusage\fR,
     zs_resource_t \fIresource\fR, timestruc_t *\fIts\fR);
.fi

.LP
.nf
uint64_t zs_resource_used_uint64(zs_usage_t \fIusage\fR,
     zs_resource_t \fIresource\fR, zs_user_t \fIuser\fR);
.fi

.LP
.nf
void zs_resource_used_time(zs_usage_t \fIusage\fR, zs_resource_t \fIresource\fR,
     zs_user_t \fIuser\fR, timestruc_t *\fIts\fR);
.fi

.LP
.nf
uint_t zs_resource_used_pct(zs_usage_t \fIusage\fR, zs_resource_t \fIresource\fR,
     zs_user_t \fIuser\fR);
.fi

.LP
.nf
uint64_t zs_resource_used_zone_uint64(zs_zone_t \fIzone\fR,
     zs_resource_t \fIresource\fR);
.fi

.LP
.nf
void zs_resource_used_zone_time(zs_zone_t \fIzone\fR, zs_resource_t \fIresource\fR,
     timestruc_t *\fIts\fR);
.fi

.LP
.nf
uint_t zs_resource_used_zone_pct(zs_zone_t \fIzone\fR, zs_resource_t \fIresource\fR);
.fi

.SH DESCRIPTION
.sp
.LP
These functions are used to access properties and utilization information of the system resources. Also provided by the \fBzs_resource_used_zone_*()\fR functions is per-zone utilization information of each resource.
.sp
.LP
See \fBlibzonestat\fR(3LIB) for the \fBZS_RESOURCE_\fR* resource codes and the \fBZS_USER_\fR* user codes.
.sp
.LP
The \fBzs_resource_property()\fR function returns resource property \fIprop\fR. See \fBlibzonestat\fR(3LIB) for a description of the \fBZS_RESOURCE_PROP_\fR* property codes.
.sp
.LP
The \fBzs_resource_type()\fR function returns the data type of the resource. The following types can be returned:
.sp
.ne 2
.mk
.na
\fB\fBZS_RESOURCE_TYPE_TIME\fR\fR
.ad
.sp .6
.RS 4n
The resource and its usage can be retrieved in terms of time.  This limit can be passed to \fBzs_resource_total_time()\fR and \fBzs_resource_used_time()\fR, as well as all other \fBzs_resource_*()\fR functions.
.RE

.sp
.ne 2
.mk
.na
\fB\fBZS_RESOURCE_TYPE_COUNT\fR\fR
.ad
.sp .6
.RS 4n
The resource reflects a quantity of discrete objects. For instance, a limit on the number of processes.
.RE

.sp
.ne 2
.mk
.na
\fB\fBZS_RESOURCE_TYPE_BYTES\fR\fR
.ad
.sp .6
.RS 4n
The resource reflects a quantity of bytes.
.RE

.sp
.LP
The \fBzs_resource_total_uint64()\fR function returns the total resource available of type \fIresource\fR.
.sp
.LP
The \fBzs_resource_total_time()\fR function sets \fIts\fR to the total time available for the given resource. This is supported only for the \fBZS_RESOURCE_CPU\fR resource. The total CPU time represents the total CPU time available since \fBzs_open\fR(3ZONESTAT) was called.
.sp
.LP
The \fBzs_resource_used_uint64()\fR function returns the total resource used for the given resource by the given user.
.sp
.LP
The \fBzs_resource_used_time()\fR function sets \fIts\fR to the total time used for \fIresource\fR by \fIuser\fR. This is supported only for the \fBZS_RESOURCE_CPU\fR resource. The used CPU time represents the CPU time used since \fBzs_open()\fR was called.
.sp
.LP
The \fBzs_resource_used_pct()\fR function returns the percentage of resource used by \fIuser\fR.
.sp
.LP
The \fBzs_resource_used_zone_uint64()\fR function returns the quantity of \fIresource\fR by \fIzone\fR.
.sp
.LP
The \fBzs_resource_used_zone_time()\fR function returns the quantity of \fIresource\fR time used by \fIzone\fR. This usage value is increasing from when \fBzs_open()\fR as first called. This function supports only the \fBZS_RESOURCE_CPU\fR resource.
.sp
.LP
The \fBzs_resource_used_zone_pct()\fR function returns the percent of \fIresource\fR used by \fIzone\fR.
.SH RETURN VALUES
.sp
.LP
See Description.
.SH ERRORS
.sp
.LP
If a \fBzs_resource_*()\fR function is called with an invalid resource or user code, the function will abort with \fBabort\fR(3C).
.SH EXAMPLES
.LP
\fBExample 1 \fRRetrieve physical memory.
.sp
.LP
The following example retrieves physical memory utilization both system-wide and for each zone.

.sp
.in +2
.nf
#include <zonestat.h>
\&...
extern zs_usage_t usage;        /* assume returned by zs_usage_read() */
\&...
zs_zone_t zone;
uint64_t total_memory;
uint64_t used_memory;
uint64_t zone_used_memory;

total_memory = zs_resource_total_uint64(usage, ZS_RESOURCE_RAM);
used_memory = zs_resource_used_uint64(usage, ZS_RESOURCE_RAM, ZS_USER_ALL);

for (zone = zs_zone_first(usage); zone != NULL;
    zone = zs_zone_next(usage, zone)) {

zone_used_memory = zs_resource_used_zone_uint64(zone, ZS_RESOURCE_RAM);
}
.fi
.in -2

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilityCommitted
_
MT-LevelSafe
.TE

.SH SEE ALSO
.sp
.LP
\fBzonestat\fR(1), \fBpooladm\fR(1M), \fBpsrset\fR(1M), \fBrcapadm\fR(1M), \fBswap\fR(1M), \fBzoneadm\fR(1M), \fBzonestatd\fR(1M), \fBabort\fR(3C), \fBlibpool\fR(3LIB), \fBlibzonestat\fR(3LIB), \fBzs_open\fR(3ZONESTAT), \fBzs_pset\fR(3ZONESTAT), \fBzs_property\fR(3ZONESTAT), \fBzs_pset_zone\fR(3ZONESTAT), \fBzs_usage\fR(3ZONESTAT), \fBzs_zone\fR(3ZONESTAT), \fBattributes\fR(5), \fBresource-controls \fR(5)