JavaScript is required to for searching.
Skip Navigation Links
Exit Print View
man pages section 3: Library Interfaces and Headers     Oracle Solaris 11 Information Library
search filter icon
search icon

Document Information

Preface

Introduction

Library Interfaces and Headers

acct(3HEAD)

acct.h(3HEAD)

aio(3HEAD)

aio.h(3HEAD)

ar(3HEAD)

archives(3HEAD)

archives.h(3HEAD)

ar.h(3HEAD)

assert(3HEAD)

assert.h(3HEAD)

complex(3HEAD)

complex.h(3HEAD)

cpio(3HEAD)

cpio.h(3HEAD)

dirent(3HEAD)

dirent.h(3HEAD)

errno(3HEAD)

errno.h(3HEAD)

fcntl(3HEAD)

fcntl.h(3HEAD)

fenv(3HEAD)

fenv.h(3HEAD)

float(3HEAD)

float.h(3HEAD)

floatingpoint(3HEAD)

floatingpoint.h(3HEAD)

fmtmsg(3HEAD)

fmtmsg.h(3HEAD)

fnmatch(3HEAD)

fnmatch.h(3HEAD)

ftw(3HEAD)

ftw.h(3HEAD)

glob(3HEAD)

glob.h(3HEAD)

grp(3HEAD)

grp.h(3HEAD)

iconv(3HEAD)

iconv.h(3HEAD)

if(3HEAD)

if.h(3HEAD)

in(3HEAD)

inet(3HEAD)

inet.h(3HEAD)

in.h(3HEAD)

inttypes(3HEAD)

inttypes.h(3HEAD)

ipc(3HEAD)

ipc.h(3HEAD)

iso646(3HEAD)

iso646.h(3HEAD)

langinfo(3HEAD)

langinfo.h(3HEAD)

lib300(3LIB)

lib300s(3LIB)

lib4014(3LIB)

lib450(3LIB)

libadm(3LIB)

libaio(3LIB)

libauto_ef(3LIB)

libbsdmalloc(3LIB)

libc(3LIB)

libc_db(3LIB)

libcfgadm(3LIB)

libcommputil(3LIB)

libcontract(3LIB)

libcpc(3LIB)

libcrypt(3LIB)

libcurses(3LIB)

libdat(3LIB)

libdevid(3LIB)

libdevinfo(3LIB)

libdl(3LIB)

libdlpi(3LIB)

libdns_sd(3LIB)

libdoor(3LIB)

libdtrace(3LIB)

libefi(3LIB)

libelf(3LIB)

libexacct(3LIB)

libfcoe(3LIB)

libfmevent(3LIB)

libform(3LIB)

libfstyp(3LIB)

libgen(3HEAD)

libgen(3LIB)

libgen.h(3HEAD)

libgss(3LIB)

libhbaapi(3LIB)

libidnkit(3LIB)

libilb(3LIB)

libintl(3HEAD)

libintl(3LIB)

libintl.h(3HEAD)

libiscsit(3LIB)

libkmf(3LIB)

libkrb5(3LIB)

libkstat(3LIB)

libkvm(3LIB)

libl(3LIB)

liblayout(3LIB)

liblgrp(3LIB)

libm(3LIB)

libmail(3LIB)

libmalloc(3LIB)

libmapmalloc(3LIB)

libmd(3LIB)

libmd5(3LIB)

libmenu(3LIB)

libmlib(3LIB)

libmlib_mt(3LIB)

libmp(3LIB)

libMPAPI(3LIB)

libmpapi(3LIB)

libmtmalloc(3LIB)

libmvec(3LIB)

libnsl(3LIB)

libnvpair(3LIB)

libpam(3LIB)

libpanel(3LIB)

libpapi(3LIB)

libpctx(3LIB)

libpicl(3LIB)

libpicltree(3LIB)

libpkcs11(3LIB)

libplot(3LIB)

libpool(3LIB)

libposix4(3LIB)

libproject(3LIB)

libpthread(3LIB)

libreparse(3LIB)

libresolv(3LIB)

librpcsvc(3LIB)

librt(3LIB)

librtld_db(3LIB)

libsasl(3LIB)

libscf(3LIB)

libsctp(3LIB)

libsec(3LIB)

libsecdb(3LIB)

libsendfile(3LIB)

libsip(3LIB)

libslp(3LIB)

libSMHBAAPI(3LIB)

libsmhbaapi(3LIB)

libsocket(3LIB)

libsrpt(3LIB)

libssagent(3LIB)

libssasnmp(3LIB)

libstmf(3LIB)

libsys(3LIB)

libsysevent(3LIB)

libtecla(3LIB)

libtermcap(3LIB)

libtermlib(3LIB)

libthread(3LIB)

libtsalarm(3LIB)

libtsnet(3LIB)

libtsol(3LIB)

libumem(3LIB)

libusb(3LIB)

libuuid(3LIB)

libv12n(3LIB)

libvolmgt(3LIB)

libvt0(3LIB)

libw(3LIB)

libwsreg(3LIB)

libxnet(3LIB)

libXtsol(3LIB)

libxtsol(3LIB)

liby(3LIB)

libzonestat(3LIB)

limits(3HEAD)

limits.h(3HEAD)

locale(3HEAD)

locale.h(3HEAD)

math(3HEAD)

math.h(3HEAD)

mman(3HEAD)

mman.h(3HEAD)

monetary(3HEAD)

monetary.h(3HEAD)

mqueue(3HEAD)

mqueue.h(3HEAD)

msg(3HEAD)

msg.h(3HEAD)

ndbm(3HEAD)

ndbm.h(3HEAD)

netdb(3HEAD)

netdb.h(3HEAD)

nl_types(3HEAD)

nl_types.h(3HEAD)

paths(3HEAD)

paths.h(3HEAD)

poll(3HEAD)

poll.h(3HEAD)

pthread(3HEAD)

pthread.h(3HEAD)

pwd(3HEAD)

pwd.h(3HEAD)

regex(3HEAD)

regex.h(3HEAD)

resource(3HEAD)

resource.h(3HEAD)

sched(3HEAD)

sched.h(3HEAD)

search(3HEAD)

search.h(3HEAD)

select(3HEAD)

select.h(3HEAD)

sem(3HEAD)

semaphore(3HEAD)

semaphore.h(3HEAD)

sem.h(3HEAD)

setjmp(3HEAD)

setjmp.h(3HEAD)

shm(3HEAD)

shm.h(3HEAD)

siginfo(3HEAD)

siginfo.h(3HEAD)

signal(3HEAD)

signal.h(3HEAD)

SMHBA_GetAdapterAttributes(3LIB)

SMHBA_GetAdapterPortAttributes(3LIB)

SMHBA_GetBindingCapability(3LIB)

SMHBA_GetBindingSupport(3LIB)

SMHBA_GetDiscoveredPortAttributes(3LIB)

SMHBA_GetFCPhyAttributes(3LIB)

SMHBA_GetLUNStatistics(3LIB)

SMHBA_GetNumberofPorts(3LIB)

SMHBA_GetPersistentBinding(3LIB)

SMHBA_GetPhyStatistics(3LIB)

SMHBA_GetPortAttributesByWWN(3LIB)

SMHBA_GetPortType(3LIB)

SMHBA_GetProtocolStatistics(3LIB)

SMHBA_GetSASPhyAttributes(3LIB)

SMHBA_GetTargetMapping(3LIB)

SMHBA_GetVendorLibraryAttributes(3LIB)

SMHBA_GetVersion(3LIB)

SMHBA_GetWrapperLibraryAttributes(3LIB)

SMHBA_RegisterForAdapterAddEvents(3LIB)

SMHBA_RegisterForAdapterEvents(3LIB)

SMHBA_RegisterForAdapterPhyStatEvents(3LIB)

SMHBA_RegisterForAdapterPortEvents(3LIB)

SMHBA_RegisterForAdapterPortStatEvents(3LIB)

SMHBA_RegisterForTargetEvents(3LIB)

SMHBA_RegisterLibrary(3LIB)

SMHBA_RemoveAllPersistentBindings(3LIB)

SMHBA_RemovePersistentBinding(3LIB)

SMHBA_ScsiInquiry(3LIB)

SMHBA_ScsiReadCapacity(3LIB)

SMHBA_ScsiReportLuns(3LIB)

SMHBA_SendECHO(3LIB)

SMHBA_SendSMPPassThru(3LIB)

SMHBA_SendTEST(3LIB)

SMHBA_SetBindingSupport(3LIB)

SMHBA_SetPersistentBinding(3LIB)

socket(3HEAD)

socket.h(3HEAD)

spawn(3HEAD)

spawn.h(3HEAD)

stat(3HEAD)

stat.h(3HEAD)

statvfs(3HEAD)

statvfs.h(3HEAD)

stdbool(3HEAD)

stdbool.h(3HEAD)

stddef(3HEAD)

stddef.h(3HEAD)

stdint(3HEAD)

stdint.h(3HEAD)

stdio(3HEAD)

stdio.h(3HEAD)

stdlib(3HEAD)

stdlib.h(3HEAD)

string(3HEAD)

string.h(3HEAD)

strings(3HEAD)

strings.h(3HEAD)

stropts(3HEAD)

stropts.h(3HEAD)

syslog(3HEAD)

syslog.h(3HEAD)

tar(3HEAD)

tar.h(3HEAD)

tcp(3HEAD)

tcp.h(3HEAD)

termios(3HEAD)

termios.h(3HEAD)

tgmath(3HEAD)

tgmath.h(3HEAD)

time(3HEAD)

timeb(3HEAD)

timeb.h(3HEAD)

time.h(3HEAD)

times(3HEAD)

times.h(3HEAD)

types32(3HEAD)

types32.h(3HEAD)

types(3HEAD)

types.h(3HEAD)

ucontext(3HEAD)

ucontext.h(3HEAD)

uio(3HEAD)

uio.h(3HEAD)

ulimit(3HEAD)

ulimit.h(3HEAD)

un(3HEAD)

un.h(3HEAD)

unistd(3HEAD)

unistd.h(3HEAD)

utime(3HEAD)

utime.h(3HEAD)

utmpx(3HEAD)

utmpx.h(3HEAD)

utsname(3HEAD)

utsname.h(3HEAD)

values(3HEAD)

values.h(3HEAD)

wait(3HEAD)

wait.h(3HEAD)

wchar(3HEAD)

wchar.h(3HEAD)

wctype(3HEAD)

wctype.h(3HEAD)

wordexp(3HEAD)

wordexp.h(3HEAD)

libpool

- pool configuration manipulation library

Synopsis

cc [ flag... ] file... [ library... ] 
#include <pool.h>

Description

The functions in this library define the interface for reading and writing resource pools configuration files, as well as that for commiting an existing configuration to becoming the running OS configuration (with respect to partitioning subsystems). The <pool.h> header provides type and function declarations for all library services.

The resource pools facility brings together process-bindable resources into a common abstraction called a pool. Processor sets and other entities can be configured, grouped, and labelled in a persistent fashion such that workload components can be associated with a subset of a system's total resources. The libpool library provides a C language API for accessing this functionality, while pooladm(1M), poolbind(1M), and poolcfg(1M) make this facility available through command invocations from a shell. Each of those manual pages describes aspects of the pools facility; this page describes the properties available to the various entities managed within the pools facility. These entities include the system, pools, and the pset resources for processor sets.

When the pools facility is enabled on a system, the behavior of the following functions is modified.

System Call
Error Value
pset_assign(pset !=PS_QUERY)
ENOTSUP
pset_bind(pset !=PS_QUERY)
ENOTSUP
pset_create()
ENOTSUP
pset_destroy()
ENOTSUP
pset_setattr()
ENOTSUP

Each active entity within the resource pools framework can have an arbitrary collection of named, typed properties associated with it. Properties supported by the pools framework are listed, with descriptions, under each entity below. In general, resource properties can be one of five types: boolean (bool), signed (int64) and unsigned (uint64) integers, floating point (double), and string values.

All entities and resources support a string property for commenting purposes; this property is available for use by management applications to record descriptions and other administrator oriented data. The comment field is not used by the default pools commands, except when a configuration is initiated by the poolcfg utility, in which case an informative message is placed in the system.comment property for that configuration.

System

Property name
Type
Description
system.allocate-method
string
Allocation method to use when this configuration is instantiated
system.bind-default
bool
If specified pool not found, bind to pool with 'pool.default' property set to true
system.comment
string
User description of system
system.name
string
User name for the configuration
system.version
int64
libpool version required to manipulate this configuration
system.poold.log-level
string
poold logging level
system.poold.log-location
string
poold logging location
system.poold.history-file
string
poold decision history location
system.poold.monitor-interval
uint64
poold monitoring sample interval
system.poold.objectives
string
poold objectives for a system.

The system.allocate-method, system.bind-default, system.comment, system.name, system.poold.log-level, system.poold.log-location, system.poold.history-file, system.poold.monitor-interval, and system.poold.objectives properties are writable; the system.version property is not.

The system.allocate-method property accepts only two values, “importance based” and “surplus to default”. The default value for this property is “importance based”. The property is optional and if it is not present the library will allocate resources as though it were present and had the default value. These strings are defined in <pool.h> as POA_IMPORTANCE and POA_SURPLUS_TO_DEFAULT.

If “importance based” allocation is defined, then during a commit the library will allocate resources to pools using an algorithm that observes minimum and maximum constraints for resources but favors those resources with greater importance.

If “surplus to default” is defined, then during a commit the library will allocate minimum resources to all resource sets apart from default which will receive any surplus.

The system.bind-default property defaults to true. This property interacts with the project.pool resource control to specify the binding behavior for processes associated with a project. If project.pool is not specified, then this property has no effect. If project.pool is specified and the specified pool exists, this property has no effect. If the specified pool does not exist, perhaps because of a reconfiguration, then this property controls the binding behavior for the project member. If system.bind-default is true, then the project member is bound to the default pool (identified as the pool for which pool.default is true); otherise the project member is refused access to the system. Care should be taken with the pools configuration if this property is set to false, so as to avoid denying users access to the system.

The various poold properties are used to configure the operation of poold(1M).

The system.poold.log-level property is used to specify the level of detail provided in log messages. Valid values are: ALERT, CRIT, ERR, WARNING, NOTICE, INFO, and DEBUG.

ALERT provides the least level of detail, DEBUG the greatest. See syslog(3C) for more information about the meaning of these debug levels. If this property is not specified, the default value NOTICE is used.

The system.poold.log-location property is used to specify the location of the logfiles generated by poold. The special value of “syslog” indicates that logged messages should be written to syslog(). If this property is not specified, the default location /var/log/pool is used.

The system.poold.history-file specifies the location of the decision history file which is used by poold to improve the quality of its decision making over time. If this property is not specified, the default location /var/adm/pool is used.

The system.poold.monitor-interval property specifies the monitoring interval (in milliseconds) to be used by poold when sampling utilization statistics. If this property is not specified, the default value of 15 seconds is used.

The system.poold.objectives property specifies any system wide objectives. An objectives property has the following syntax:

objectives = objective [; objective]*
objective = [n:] keyword [op] [value]

All objectives are prefixed with an optional importance. The importance acts as a multiplier for the objective and thus increases the significance of its contribution to the objective function evaluation. If no importance is specified, the default value is 1.

The “wt-load” objective is the only objective to which a system element can be set. This objective favors configurations that match resource allocations to resource utilization. A resource set that uses more resources will be given more resources when this objective is active. An administrator should use this objective when he is relatively satisfied with the constraints established using the minimum and maximum properties and would like the DRP to manipulate resources freely within those constraints.

Pools

Property name
Type
Description
pool.active
bool
Mark this pool as active, if true.
pool.comment
string
User description of pool.
pool.default
bool
Mark this pool as the default pool, if true; see system.bind-default property.
pool.importance
int64
Relative importance of this pool; for possible resource dispute resolution.
pool.name
string
User name for pool; used by setproject(3PROJECT) as value for 'project.pool' project attribute in project(4) database.
pool.scheduler
string
Scheduler class to which consumers of this pool will be bound. This property is optional and if not specified, the scheduler bindings for consumers of this pool are not affected.
pool.sys_id
int64
System-assigned pool ID.
pool.temporary
bool
Mark this pool as a temporary resource; if true, this pool can exist only in the dynamic configuration and cannot be committed to a configuration file.

The pool.default, pool.sys_id, and pool.temporary properties are not writable; all other listed properties are writable.

If pool.scheduler is specified, it must be set to the name of a valid scheduling class for the system. See the -c option for priocntl(1) for a list of valid class names.

Processor Sets

Property name
Type
Description
pset.comment
string
User description of resource.
pset.default
bool
Marks default processor set.
pset.load
uint64
The load for this processor set.
pset.max
uint64
Maximum number of CPUs permitted in this processor set.
pset.min
uint64
Minimum number of CPUs permitted in this processor set.
pset.name
string
User name for resource.
pset.size
uint64
Current number of CPUs in this processor set.
pset.sys_id
int64
System-assigned processor set ID.
pset.temporary
bool
Mark this processor set as a temporary resource; if true, this processor set can exist only in the dynamic configuration and cannot be committed to a configuration file.
pset.type
string
Names resource type; value for all processor sets is pset.
pset.units
string
Identifies meaning of size-related properties; value for all processor sets is population.
pset.poold.objectives
string
Specifies the poold objectives for a pset.

The pset.comment, pset.max, pset.min, pset.name, and pset.poold.objectives properties are writable; the pset.default, pset.load, pset.size, pset.sys_id, pset.temporary, pset.type, and pset.units properties are not.

The pset.load property represents the load on a processor set. The lowest value for this property is 0. The value of pset.load increases in a linear fashion with the load on the set, as measured by the number of jobs in the system run queue.

The pset.poold.objectives property specifies an objective which is specific to a particular pset. See the system.poold.objectives entry for the specification of this property's syntax.

There are two types of objectives that can be set on a pset:

locality

This objective influences the impact that locality, as measured by lgroup data, has upon the chosen configuration. This objective can take one of three values:

tight

If set, configurations that maximize resource locality are favored.

loose

If set, configurations that minimize resource locality are favored.

none

This is the default value for this objective. If set, configuration favorability is uninfluenced by resource locality.

utilization

This objective favors configurations that allocate resources to partitions that are failing to preserve the specified utilization objective.

These objectives are specified in terms of an operator and a value. The operators are

<

The ``less than'' operator is used to indicate that the specified value should be treated as a maximum target value.

>

The ``greater than'' operator is used to indicate that the specified value should be treated as a minimum target value.

~

The ``about'' operator is used to indicate that the specified value should be treated as a target value about which some fluctuation is acceptable.

Only one objective of each type of operator can be set. For example, if the ~ operator is set, the < and > operators cannot be set. It is possible to set a < and a > operator together; the values will be validated to ensure that they do not overlap.

Processors

Property name
Type
Description
cpu.comment
string
User description of CPU.
cpu.pinned
bool
CPU pinned to this processor set.
cpu.status
int64
Processor status, on-line, offline or interrupts disabled.
cpu.sys_id
int64
System-assigned processor ID.

The cpu.comment, cpu.pinned, and cpu.status properties are writeable.

The cpu.status property can be set only to the following values:

off-line

Set the CPU offline.

on-line

Set the CPU online.

no-intr

Disable interrupt processing on the CPU.

These values are defined in <sys/processor.h> as the PS_OFFLINE, PS_ONLINE, and PS_NOINTR macros.

INTERFACES

The shared object libpool.so.1 provides the public interfaces defined below. See Intro(3) for additional information on shared object interfaces.

pool_associate
pool_component_info
pool_component_to_elem
pool_conf_alloc
pool_conf_close
pool_conf_commit
pool_conf_export
pool_conf_free
pool_conf_info
pool_conf_location
pool_conf_open
pool_conf_remove
pool_conf_rollback
pool_conf_status
pool_conf_to_elem
pool_conf_update
pool_conf_validate
pool_create
pool_destroy
pool_dissociate
pool_dynamic_location
pool_error
pool_get_binding
pool_get_owning_resource
pool_get_pool
pool_get_property
pool_get_resource
pool_get_resource_binding
pool_get_status
pool_info
pool_is_readonly_property
pool_put_property
pool_query_components
pool_query_pool_resources
pool_query_pools
pool_query_resource_components
pool_query_resources
pool_resource_create
pool_resource_destroy
pool_resource_info
pool_resource_to_elem
pool_resource_transfer
pool_resource_type_list
pool_resource_xtransfer
pool_rm_property
pool_set_binding
pool_set_status
pool_static_location
pool_strerror
pool_to_elem
pool_value_alloc
pool_value_free
pool_value_get_bool
pool_value_get_double
pool_value_get_int64
pool_value_get_name
pool_value_get_string
pool_value_get_type
pool_value_get_uint64
pool_value_set_bool
pool_value_set_double
pool_value_set_int64
pool_value_set_name
pool_value_set_string
pool_value_set_uint64
pool_version
pool_walk_components
pool_walk_pools
pool_walk_properties
pool_walk_resources

Files

/usr/lib/libpool.so.1

shared object

/usr/lib/64/libpool.so.1

64-bit shared object

Attributes

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

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Availability
system/resource-mgmt/resource-pools
CSI
Enabled
Interface Stability
Uncommitted
MT-Level
Safe

See Also

Intro(3), pool_component_info(3POOL), pool_conf_open(3POOL), pool_conf_to_elem(3POOL), pool_create(3POOL), pool_error(3POOL), pool_get_binding(3POOL), pool_get_property(3POOL), pool_get_resource(3POOL), pool_resource_create(3POOL), pool_value_alloc(3POOL), pool_walk_pools(3POOL), attributes(5), smf(5)

Notes

Functions in libpool can be used to manipulate static configurations even when the pools facility is not enabled. See pooladm(1M) and pool_set_status(3POOL) for more information about enabling the pools facility. The pools facility must be enabled, however, to modify the dynamic configuration.

Since the Resource Pools facility is an smf(5) service, it can also be enabled and disabled using the standard Service Management Facility (SMF) interfaces.