'\" te
.\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
.\"  See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with
.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH POOLSTAT 8 "Jun 16, 2009"
.SH NAME
poolstat \- report active pool statistics
.SH SYNOPSIS
.LP
.nf
\fBpoolstat\fR [\fB-p\fR \fIpool-list\fR] [\fB-r\fR \fIrset-list\fR] [\fB-T\fR u | d ] [\fIinterval\fR [\fIcount\fR]]
.fi

.LP
.nf
\fBpoolstat\fR [\fB-p\fR \fIpool-list\fR] [\fB-o\fR \fIformat\fR \fB-r\fR \fIrset-list\fR]
     [\fB-T\fR u | d ] [\fIinterval\fR [\fIcount\fR]]
.fi

.SH DESCRIPTION
.sp
.LP
The \fBpoolstat\fR utility iteratively examines all active pools on the system.
It reports statistics based on the selected output mode. \fBpoolstat\fR
provides options to examine only specified pools and report resource
set-specific statistics.
.sp
.LP
Without options, \fBpoolstat\fR examines all pools, reports basic statistics
for their resource sets, and exits.
.SS "DISPLAY FORMATS"
.sp
.LP
In default output format, \fBpoolstat\fR outputs a header line and a line for
each pool. The line begins with the pool ID and its name, followed by a column
of statistical data for the processor set attached to the pool.
.sp
.LP
The columns are defined as follows:
.sp
.ne 2
.na
\fB\fBid\fR\fR
.ad
.RS 8n
Pool ID.
.RE

.sp
.ne 2
.na
\fB\fBpool\fR\fR
.ad
.RS 8n
Pool name.
.RE

.sp
.ne 2
.na
\fB\fBrid\fR\fR
.ad
.RS 8n
Resource set id.
.RE

.sp
.ne 2
.na
\fB\fBrset\fR\fR
.ad
.RS 8n
Resource set name.
.RE

.sp
.ne 2
.na
\fB\fBtype\fR\fR
.ad
.RS 8n
Resource set type.
.RE

.sp
.ne 2
.na
\fB\fBmin\fR\fR
.ad
.RS 8n
Minimum resource set size.
.RE

.sp
.ne 2
.na
\fB\fBmax\fR\fR
.ad
.RS 8n
Maximum resource set size.
.RE

.sp
.ne 2
.na
\fB\fBsize\fR\fR
.ad
.RS 8n
Current resource set size.
.RE

.sp
.ne 2
.na
\fB\fBused\fR\fR
.ad
.RS 8n
The measure of how much of the resource set is currently is use. This is
calculated as the percentage utilization of the resource set multiplied by its
size. If resource set has been reconfigured during last sampling interval, this
value might be not reported (\fB-\fR).
.RE

.sp
.ne 2
.na
\fB\fBload\fR\fR
.ad
.RS 8n
The absolute representation of the load that is put on the resource set. For
the definition of this property see \fBlibpool\fR(3LIB).
.RE

.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.na
\fB\fB-o\fR \fIformat\fR\fR
.ad
.RS 16n
Report statistics according to the format specification given in format. See
\fBDISPLAY FORMATS\fR.
.sp
The \fB-o\fR option accepts lists as arguments. Items in a list can be either
separated by commas or enclosed in quotes and separated by commas or spaces.
.sp
You can specify multiple \fB-o\fR options. The format specification is
interpreted as the whitespace separated concatenation of all the format option
arguments.
.sp
The \fB-o\fR option must be used in conjunction with the \fB-r\fR option.
.RE

.sp
.ne 2
.na
\fB\fB-p\fR \fIpool-list\fR\fR
.ad
.RS 16n
Report only pools whose names are in the given list. If the -r option is also
used, this option selects only resource sets which belong to pools in the given
list. Statistics for pools or resource sets are reported in the same order in
which pool names are listed on the pool-list. Pool can be specified by name or
by ID.
.sp
The \fB-p\fR option accepts lists as arguments. Items in a \fIpool-list\fR can
only be separated by spaces.
.RE

.sp
.ne 2
.na
\fB\fB-r\fR \fIrset-list\fR\fR
.ad
.RS 16n
Report resource set statistics. If the \fIrset-list\fR argument is "\fBall\fR",
then all possible resource set types are selected.
.sp
The \fB-r\fR option accepts lists as arguments. Items in a list can be either
separated by commas or enclosed in quotes and separated by commas or spaces.
.sp
The following resource set types are supported:
.sp
.ne 2
.na
\fB\fBall\fR\fR
.ad
.RS 8n
All resource set types
.RE

.sp
.ne 2
.na
\fB\fBpset\fR\fR
.ad
.RS 8n
Processor set
.RE

.RE

.sp
.ne 2
.na
\fB\fB-T\fR \fBu\fR | \fBd\fR\fR
.ad
.RS 16n
Display a time stamp.
.sp
Specify \fBu\fR for a printed representation of the internal representation of
time. See \fBtime\fR(2). Specify \fBd\fR for standard date format. See
\fBdate\fR(1).
.RE

.SH OPERANDS
.sp
.LP
The following operands are supported:
.sp
.ne 2
.na
\fB\fIcount\fR\fR
.ad
.RS 12n
The number of times that the statistics are repeated. By default, poolstat
reports statistics only once.
.sp
If neither interval nor count are specified, statistics are reported once. If
interval is specified and count is not, statistics are reported indefinitely.
.RE

.sp
.ne 2
.na
\fB\fIinterval\fR\fR
.ad
.RS 12n
The sampling interval in seconds.
.sp
If neither interval nor count are specified, statistics are reported once. If
interval is specified and count is not, statistics are reported indefinitely.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRUsing \fBpoolstat\fR
.sp
.LP
The following example shows the default output from the \fBpoolstat\fR utility:

.sp
.in +2
.nf
% poolstat
                         pset
  id pool           size used load
   0 pool_default      4  3.6  6.2
   1 pool_admin        4  3.3  8.4
.fi
.in -2
.sp

.LP
\fBExample 2 \fRReporting Resource Set Statistics
.sp
.LP
The following example reports resource set statistics.

.sp
.in +2
.nf

% poolstat -r pset
  id pool           type rid rset          min  max size used load
  0 pool_default    pset  -1 pset_default    1  65K    2  1.2  8.3
  1 pool_admin      pset   1 pset_admin      1    1    1  0.4  5.2
  2 pool_other      pset  -1 pset_default    1  65K    2  1.2  8.3
.fi
.in -2
.sp

.sp
.LP
Resource sets attached to multiple pools, as \fBpset_default\fR in the example
above, are listed multiple times, once for each pool.

.LP
\fBExample 3 \fRRestricting the Output to the List of Pools
.sp
.LP
The following example restricts the output to the list of pools

.sp
.in +2
.nf
% poolstat -p pool_default
                     pset
 id pool         size used load
 0 pool_default    8  5.3 10.3

% poolstat -p 'pool_admin pool_default'
                       pset
  id pool         size used load
  1 pool_admin      6  4.3  5.3
  0 pool_default    2  1.9  2.0

% poolstat -r all -p 'pool_admin pool_default'
  id pool            type rid rset          min  max size used load
  1 pool_admin      pset   1 pset_admin      1    1    1  0.9  2.3
  2 pool_default    pset  -1 pset_default    1  65K    2  2.0  2.0
.fi
.in -2
.sp

.LP
\fBExample 4 \fRCustomizing Output
.sp
.LP
The following example customizes output:

.sp
.in +2
.nf
% poolstat -r -o pool,rset,size,load
  pool            rset          size load
  pool_default    pset_default     4  4.5
  pool_admin      pset_admin       4  2.1
.fi
.in -2
.sp

.SH EXIT STATUS
.sp
.LP
The following exit values are returned:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 5n
Successful completion.
.RE

.sp
.ne 2
.na
\fB\fB1\fR\fR
.ad
.RS 5n
An error occurred.
.RE

.sp
.ne 2
.na
\fB\fB2\fR\fR
.ad
.RS 5n
Invalid command line options were specified.
.RE

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

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Stability	Evolving
.TE

.SH SEE ALSO
.sp
.LP
.BR libpool (3LIB),
.BR attributes (7)
.sp
.LP
\fI\fR
.SH NOTES
.sp
.LP
The system ids associated with resources can change after the system reboots or
the resource configuration is altered.