diff options
Diffstat (limited to 'usr/src/man')
| -rw-r--r-- | usr/src/man/man3lib/libpool.3lib | 542 | ||||
| -rw-r--r-- | usr/src/man/man3pool/pool_associate.3pool | 306 | ||||
| -rw-r--r-- | usr/src/man/man3pool/pool_component_info.3pool | 122 | ||||
| -rw-r--r-- | usr/src/man/man3pool/pool_component_to_elem.3pool | 86 | ||||
| -rw-r--r-- | usr/src/man/man3pool/pool_conf_alloc.3pool | 669 | ||||
| -rw-r--r-- | usr/src/man/man3pool/pool_dynamic_location.3pool | 206 | ||||
| -rw-r--r-- | usr/src/man/man3pool/pool_error.3pool | 176 | ||||
| -rw-r--r-- | usr/src/man/man3pool/pool_get_binding.3pool | 249 | ||||
| -rw-r--r-- | usr/src/man/man3pool/pool_get_pool.3pool | 203 | ||||
| -rw-r--r-- | usr/src/man/man3pool/pool_get_property.3pool | 278 | ||||
| -rw-r--r-- | usr/src/man/man3pool/pool_resource_create.3pool | 339 | ||||
| -rw-r--r-- | usr/src/man/man3pool/pool_value_alloc.3pool | 244 | ||||
| -rw-r--r-- | usr/src/man/man3pool/pool_walk_components.3pool | 115 |
13 files changed, 3535 insertions, 0 deletions
diff --git a/usr/src/man/man3lib/libpool.3lib b/usr/src/man/man3lib/libpool.3lib new file mode 100644 index 0000000..dda5251 --- /dev/null +++ b/usr/src/man/man3lib/libpool.3lib @@ -0,0 +1,542 @@ +'\" te +.\" Copyright (c) 2006, 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 LIBPOOL 3LIB "Dec 14, 2006" +.SH NAME +libpool \- pool configuration manipulation library +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ] +#include <\fBpool.h\fR> +.fi + +.SH DESCRIPTION +.sp +.LP +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 <\fBpool.h\fR> header provides type and function +declarations for all library services. +.sp +.LP +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 +\fBlibpool\fR library provides a C language API for accessing this +functionality, while \fBpooladm\fR(1M), \fBpoolbind\fR(1M), and +\fBpoolcfg\fR(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 +\fBpset\fR resources for processor sets. +.sp +.LP +When the pools facility is enabled on a system, the behavior of the following +functions is modified. +.sp + +.sp +.TS +c c +l l . +System Call Error Value +_ +\fBpset_assign\fR(pset !=\fBPS_QUERY\fR) \fBENOTSUP\fR +\fBpset_bind\fR(pset !=\fBPS_QUERY\fR) \fBENOTSUP\fR +\fBpset_create()\fR \fBENOTSUP\fR +\fBpset_destroy()\fR \fBENOTSUP\fR +\fBpset_setattr()\fR \fBENOTSUP\fR +.TE + +.sp +.LP +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 (\fBbool\fR), +signed (\fBint64\fR) and unsigned (\fBuint64\fR) integers, floating point +(\fBdouble\fR), and \fBstring\fR values. +.sp +.LP +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 \fBpoolcfg\fR utility, in which case an informative message is placed in +the \fBsystem.comment\fR property for that configuration. +.SS "System" +.sp + +.sp +.TS +c c c +l l l . +Property name Type Description +\fBsystem.allocate-method\fR \fBstring\fR T{ +Allocation method to use when this configuration is instantiated +T} +\fBsystem.bind-default\fR \fBbool\fR T{ +If specified pool not found, bind to pool with 'pool.default' property set to true +T} +\fBsystem.comment\fR \fBstring\fR User description of system +\fBsystem.name\fR \fBstring\fR User name for the configuration +\fBsystem.version\fR \fBint64\fR T{ +\fBlibpool\fR version required to manipulate this configuration +T} +\fBsystem.poold.log-level\fR \fBstring\fR \fBpoold\fR logging level +\fBsystem.poold.log-location\fR \fBstring\fR \fBpoold\fR logging location +\fBsystem.poold.history-file\fR \fBstring\fR \fBpoold\fR decision history location +\fBsystem.poold.monitor-interval\fR \fBuint64\fR \fBpoold\fR monitoring sample interval +\fBsystem.poold.objectives\fR \fBstring\fR \fBpoold\fR objectives for a system. +.TE + +.sp +.LP +The \fBsystem.allocate-method\fR, \fBsystem.bind-default\fR, +\fBsystem.comment\fR, \fBsystem.name\fR, \fBsystem.poold.log-level\fR, +\fBsystem.poold.log-location\fR, \fBsystem.poold.history-file\fR, +\fBsystem.poold.monitor-interval\fR, and \fBsystem.poold.objectives\fR +properties are writable; the \fBsystem.version\fR property is not. +.sp +.LP +The \fBsystem.allocate-method\fR 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 <\fBpool.h\fR> as \fBPOA_IMPORTANCE\fR and +\fBPOA_SURPLUS_TO_DEFAULT\fR. +.sp +.LP +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. +.sp +.LP +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. +.sp +.LP +The \fBsystem.bind-default\fR property defaults to true. This property +interacts with the \fBproject.pool\fR resource control to specify the binding +behavior for processes associated with a project. If \fBproject.pool\fR is not +specified, then this property has no effect. If \fBproject.pool\fR 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 +\fBsystem.bind-default\fR is true, then the project member is bound to the +default pool (identified as the pool for which \fBpool.default\fR 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. +.sp +.LP +The various \fBpoold\fR properties are used to configure the operation of +\fBpoold\fR(1M). +.sp +.LP +The \fBsystem.poold.log-level\fR property is used to specify the level of +detail provided in log messages. Valid values are: \fBALERT\fR, \fBCRIT\fR, +\fBERR\fR, \fBWARNING\fR, \fBNOTICE\fR, \fBINFO\fR, and \fBDEBUG\fR. +.sp +.LP +\fBALERT\fR provides the least level of detail, \fBDEBUG\fR the greatest. See +\fBsyslog\fR(3C) for more information about the meaning of these debug levels. +If this property is not specified, the default value \fBNOTICE\fR is used. +.sp +.LP +The \fBsystem.poold.log-location\fR property is used to specify the location of +the logfiles generated by \fBpoold\fR. The special value of "syslog" indicates +that logged messages should be written to \fBsyslog()\fR. If this property is +not specified, the default location \fB/var/log/pool\fR is used. +.sp +.LP +The \fBsystem.poold.history-file\fR specifies the location of the decision +history file which is used by \fBpoold\fR to improve the quality of its +decision making over time. If this property is not specified, the default +location \fB/var/adm/pool\fR is used. +.sp +.LP +The \fBsystem.poold.monitor-interval\fR property specifies the monitoring +interval (in milliseconds) to be used by \fBpoold\fR when sampling utilization +statistics. If this property is not specified, the default value of 15 seconds +is used. +.sp +.LP +The \fBsystem.poold.objectives\fR property specifies any system wide +objectives. An objectives property has the following syntax: +.sp +.in +2 +.nf +objectives = objective [; objective]* +objective = [n:] keyword [op] [value] +.fi +.in -2 + +.sp +.LP +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. +.sp +.LP +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. +.SS "Pools" +.sp + +.sp +.TS +c c c +l l l . +Property name Type Description +\fBpool.active\fR \fBbool\fR Mark this pool as active, if true. +\fBpool.comment\fR \fBstring\fR User description of pool. +\fBpool.default\fR \fBbool\fR T{ +Mark this pool as the default pool, if true; see system.bind-default property. +T} +\fBpool.importance\fR \fBint64\fR T{ +Relative importance of this pool; for possible resource dispute resolution. +T} +\fBpool.name\fR \fBstring\fR T{ +User name for pool; used by \fBsetproject\fR(3PROJECT) as value for 'project.pool' project attribute in \fBproject\fR(4) database. +T} +\fBpool.scheduler\fR \fBstring\fR T{ +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. +T} +\fBpool.sys_id\fR \fBint64\fR System-assigned pool ID. +\fBpool.temporary\fR \fBbool\fR T{ +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. +T} +.TE + +.sp +.LP +The \fBpool.default\fR, \fBpool.sys_id\fR, and \fBpool.temporary\fR properties +are not writable; all other listed properties are writable. +.sp +.LP +If pool.scheduler is specified, it must be set to the name of a valid +scheduling class for the system. See the \fB-c\fR option for \fBpriocntl\fR(1) +for a list of valid class names. +.SS "Processor Sets" +.sp + +.sp +.TS +c c c +l l l . +Property name Type Description +\fBpset.comment\fR \fBstring\fR User description of resource. +\fBpset.default\fR \fBbool\fR Marks default processor set. +\fBpset.load\fR \fBuint64\fR The load for this processor set. +\fBpset.max\fR \fBuint64\fR T{ +Maximum number of CPUs permitted in this processor set. +T} +\fBpset.min\fR \fBuint64\fR T{ +Minimum number of CPUs permitted in this processor set. +T} +\fBpset.name\fR \fBstring\fR User name for resource. +\fBpset.size\fR \fBuint64\fR T{ +Current number of CPUs in this processor set. +T} +\fBpset.sys_id\fR \fBint64\fR System-assigned processor set ID. +\fBpset.temporary\fR \fBbool\fR T{ +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. +T} +\fBpset.type\fR \fBstring\fR T{ +Names resource type; value for all processor sets is \fBpset\fR. +T} +\fBpset.units\fR \fBstring\fR T{ +Identifies meaning of size-related properties; value for all processor sets is \fBpopulation\fR. +T} +\fBpset.poold.objectives\fR \fBstring\fR T{ +Specifies the poold objectives for a pset. +T} +.TE + +.sp +.LP +The \fBpset.comment\fR, \fBpset.max\fR, \fBpset.min\fR, \fBpset.name\fR, and +\fBpset.poold.objectives\fR properties are writable; the \fBpset.default\fR, +\fBpset.load\fR, \fBpset.size\fR, \fBpset.sys_id\fR, \fBpset.temporary\fR, +\fBpset.type\fR, and \fBpset.units\fR properties are not. +.sp +.LP +The \fBpset.load\fR property represents the load on a processor set. The lowest +value for this property is 0. The value of \fBpset.load\fR increases in a +linear fashion with the load on the set, as measured by the number of jobs in +the system run queue. +.sp +.LP +The \fBpset.poold.objectives\fR property specifies an objective which is +specific to a particular \fBpset\fR. See the \fBsystem.poold.objectives\fR +entry for the specification of this property's syntax. +.sp +.LP +There are two types of objectives that can be set on a \fBpset\fR: +.sp +.ne 2 +.na +\fB\fBlocality\fR\fR +.ad +.RS 15n +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: +.sp +.ne 2 +.na +\fB\fBtight\fR\fR +.ad +.RS 9n +If set, configurations that maximize resource locality are favored. +.RE + +.sp +.ne 2 +.na +\fB\fBloose\fR\fR +.ad +.RS 9n +If set, configurations that minimize resource locality are favored. +.RE + +.sp +.ne 2 +.na +\fB\fBnone\fR\fR +.ad +.RS 9n +This is the default value for this objective. If set, configuration +favorability is uninfluenced by resource locality. +.RE + +.RE + +.sp +.ne 2 +.na +\fB\fButilization\fR\fR +.ad +.RS 15n +This objective favors configurations that allocate resources to partitions that +are failing to preserve the specified utilization objective. +.RE + +.sp +.LP +These objectives are specified in terms of an operator and a value. The +operators are +.sp +.ne 2 +.na +\fB\fB<\fR\fR +.ad +.RS 5n +The ``less than'' operator is used to indicate that the specified value should +be treated as a maximum target value. +.RE + +.sp +.ne 2 +.na +\fB\fB>\fR\fR +.ad +.RS 5n +The ``greater than'' operator is used to indicate that the specified value +should be treated as a minimum target value. +.RE + +.sp +.ne 2 +.na +\fB\fB~\fR\fR +.ad +.RS 5n +The ``about'' operator is used to indicate that the specified value should be +treated as a target value about which some fluctuation is acceptable. +.RE + +.sp +.LP +Only one objective of each type of operator can be set. For example, if the +\fB~\fR operator is set, the \fB<\fR and \fB>\fR operators cannot be set. It is +possible to set a \fB<\fR and a \fB>\fR operator together; the values will be +validated to ensure that they do not overlap. +.SS "Processors" +.sp + +.sp +.TS +c c c +l l l . +Property name Type Description +_ +\fBcpu.comment\fR \fBstring\fR User description of CPU. +\fBcpu.pinned\fR \fBbool\fR CPU pinned to this processor set. +\fBcpu.status\fR \fBint64\fR T{ +Processor status, on-line, offline or interrupts disabled. +T} +\fBcpu.sys_id\fR \fBint64\fR System-assigned processor ID. +.TE + +.sp +.LP +The \fBcpu.comment\fR, \fBcpu.pinned\fR, and \fBcpu.status\fR properties are +writeable. +.sp +.LP +The \fBcpu.status\fR property can be set only to the following values: +.sp +.ne 2 +.na +\fB\fBoff-line\fR\fR +.ad +.RS 12n +Set the CPU offline. +.RE + +.sp +.ne 2 +.na +\fB\fBon-line\fR\fR +.ad +.RS 12n +Set the CPU online. +.RE + +.sp +.ne 2 +.na +\fB\fBno-intr\fR\fR +.ad +.RS 12n +Disable interrupt processing on the CPU. +.RE + +.sp +.LP +These values are defined in <\fBsys/processor.h\fR> as the \fBPS_OFFLINE\fR, +\fBPS_ONLINE\fR, and \fBPS_NOINTR\fR macros. +.SH INTERFACES +.sp +.LP +The shared object \fBlibpool.so.1\fR provides the public interfaces defined +below. See \fBIntro\fR(3) for additional information on shared object +interfaces. +.sp + +.sp +.TS +l l +l l . +\fBpool_associate\fR \fBpool_component_info\fR +\fBpool_component_to_elem\fR \fBpool_conf_alloc\fR +\fBpool_conf_close\fR \fBpool_conf_commit\fR +\fBpool_conf_export\fR \fBpool_conf_free\fR +\fBpool_conf_info\fR \fBpool_conf_location\fR +\fBpool_conf_open\fR \fBpool_conf_remove\fR +\fBpool_conf_rollback\fR \fBpool_conf_status\fR +\fBpool_conf_to_elem\fR \fBpool_conf_update\fR +\fBpool_conf_validate\fR \fBpool_create\fR +\fBpool_destroy\fR \fBpool_dissociate\fR +\fBpool_dynamic_location\fR \fBpool_error\fR +\fBpool_get_binding\fR \fBpool_get_owning_resource\fR +\fBpool_get_pool\fR \fBpool_get_property\fR +\fBpool_get_resource\fR \fBpool_get_resource_binding\fR +\fBpool_get_status\fR \fBpool_info\fR +\fBpool_put_property\fR \fBpool_query_components\fR +\fBpool_query_pool_resources\fR \fBpool_query_pools\fR +\fBpool_query_resource_components\fR \fBpool_query_resources\fR +\fBpool_resource_create\fR \fBpool_resource_destroy\fR +\fBpool_resource_info\fR \fBpool_resource_to_elem\fR +\fBpool_resource_transfer\fR \fBpool_resource_type_list\fR +\fBpool_resource_xtransfer\fR \fBpool_rm_property\fR +\fBpool_set_binding\fR \fBpool_set_status\fR +\fBpool_static_location\fR \fBpool_strerror\fR +\fBpool_to_elem\fR \fBpool_value_alloc\fR +\fBpool_value_free\fR \fBpool_value_get_bool\fR +\fBpool_value_get_double\fR \fBpool_value_get_int64\fR +\fBpool_value_get_name\fR \fBpool_value_get_string\fR +\fBpool_value_get_type\fR \fBpool_value_get_uint64\fR +\fBpool_value_set_bool\fR \fBpool_value_set_double\fR +\fBpool_value_set_int64\fR \fBpool_value_set_name\fR +\fBpool_value_set_string\fR \fBpool_value_set_uint64\fR +\fBpool_version\fR \fBpool_walk_components\fR +\fBpool_walk_pools\fR \fBpool_walk_properties\fR +\fBpool_walk_resources\fR +.TE + +.SH FILES +.sp +.ne 2 +.na +\fB\fB/usr/lib/libpool.so.1\fR\fR +.ad +.RS 28n +shared object +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/64/libpool.so.1\fR\fR +.ad +.RS 28n +64-bit shared object +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +CSI Enabled +_ +Interface Stability Unstable +_ +MT-Level Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBIntro\fR(3), \fBpool_component_info\fR(3POOL), \fBpool_conf_open\fR(3POOL), +\fBpool_conf_to_elem\fR(3POOL), \fBpool_create\fR(3POOL), +\fBpool_error\fR(3POOL), \fBpool_get_binding\fR(3POOL), +\fBpool_get_property\fR(3POOL), \fBpool_get_resource\fR(3POOL), +\fBpool_resource_create\fR(3POOL), \fBpool_value_alloc\fR(3POOL), +\fBpool_walk_pools\fR(3POOL), \fBattributes\fR(5), \fBsmf\fR(5) +.SH NOTES +.sp +.LP +Functions in \fBlibpool\fR can be used to manipulate static configurations even +when the pools facility is not enabled. See \fBpooladm\fR(1M) and +\fBpool_set_status\fR(3POOL) for more information about enabling the pools +facility. The pools facility must be enabled, however, to modify the dynamic +configuration. +.sp +.LP +Since the Resource Pools facility is an \fBsmf\fR(5) service, it can also be +enabled and disabled using the standard Service Management Facility (SMF) +interfaces. diff --git a/usr/src/man/man3pool/pool_associate.3pool b/usr/src/man/man3pool/pool_associate.3pool new file mode 100644 index 0000000..4584697 --- /dev/null +++ b/usr/src/man/man3pool/pool_associate.3pool @@ -0,0 +1,306 @@ +'\" te +.\" Copyright (c) 2005, 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 POOL_ASSOCIATE 3POOL "Jul 18, 2005" +.SH NAME +pool_associate, pool_create, pool_destroy, pool_dissociate, pool_info, +pool_query_pool_resources \- resource pool manipulation functions +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lpool\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <pool.h> + +\fBint\fR \fBpool_associate\fR(\fBpool_conf_t *\fR\fIconf\fR, \fB pool_t *\fR\fIpool\fR, + \fBpool_resource_t *\fR\fIresource\fR); +.fi + +.LP +.nf +\fBpool_t *\fR\fBpool_create\fR(\fBpool_conf_t *\fR\fIconf\fR, \fBconst char *\fR\fIname\fR); +.fi + +.LP +.nf +\fBint\fR \fBpool_destroy\fR(\fBpool_conf_t *\fR\fIconf\fR, \fBpool_t *\fR\fIpool\fR); +.fi + +.LP +.nf +\fBint\fR \fBpool_dissociate\fR(\fBpool_conf_t *\fR\fIconf\fR, \fBpool_t *\fR\fIpool\fR, + \fBpool_resource_t *\fR\fIresource\fR); +.fi + +.LP +.nf +\fBconst char *\fR\fBpool_info\fR(\fBpool_conf_t *\fR\fIconf\fR, \fBpool_t *\fR\fIpool\fR, + \fBint\fR \fIflags\fR); +.fi + +.LP +.nf +\fBpool_resource_t **\fR\fBpool_query_pool_resources\fR(\fBpool_conf_t *\fR\fIconf\fR, + \fBpool_t *\fR\fIpool\fR, \fBuint_t *\fR\fInelem\fR, \fBpool_value_t **\fR\fIproperties\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions provide mechanisms for constructing and modifying pools entries +within a target pools configuration. The \fIconf\fR argument for each function +refers to the target configuration to which the operation applies. +.sp +.LP +The \fBpool_associate()\fR function associates the specified resource with +\fIpool\fR. A resource can be associated with multiple pools at the same time. +Any resource of this type that was formerly associated with this pool is no +longer associated with the pool. The new association replaces the earlier one. +.sp +.LP +The \fBpool_create()\fR function creates a new pool with the supplied name with +its default properties initialized, and associated with the default resource of +each type. +.sp +.LP +The \fBpool_destroy function()\fR destroys the given pool association. +Associated resources are not modified. +.sp +.LP +The \fBpool_dissociate()\fR function removes the association between the given +resource and pool. On successful completion, the pool is associated with the +default resource of the same type. +.sp +.LP +The \fBpool_info()\fR function returns a string describing the given pool. The +string is allocated with \fBmalloc\fR(3C). The caller is reponsible for freeing +the returned string. If the \fIflags\fR option is non-zero, the string returned +also describes the associated resources of the pool. +.sp +.LP +The \fBpool_query_pool_resources()\fR function returns a null-terminated array +of resources currently associated with the pool that match the given list of +properties. The return value must be freed by the caller. The \fInelem\fR +argument is set to be the length of the array returned. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBpool_create()\fR returns a new initialized pool. +Otherwise it returns \fINULL\fR and \fBpool_error\fR(3POOL) returns the +pool-specific error value. +.sp +.LP +Upon successful completion, \fBpool_associate()\fR, \fBpool_destroy()\fR, and +\fBpool_dissociate()\fR return 0. Otherwise, they return -1 and +\fBpool_error()\fR returns the pool-specific error value. +.sp +.LP +Upon successful completion, \fBpool_info()\fR returns a string describing the +given pool. Otherwise it returns \fINULL\fR and \fBpool_error()\fR returns the +pool-specific error value. +.sp +.LP +Upon successful completion, \fBpool_query_pool_resources()\fR returns a +null-terminated array of resources. Otherwise it returns \fINULL\fR and +\fBpool_error()\fR returns the pool-specific error value. +.SH ERRORS +.sp +.LP +The \fBpool_create()\fR function will fail if: +.sp +.ne 2 +.na +\fB\fBPOE_BADPARAM\fR\fR +.ad +.RS 20n +The supplied configuration's status is not \fBPOF_VALID\fR or \fIname\fR is +already in use. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_SYSTEM\fR\fR +.ad +.RS 20n +A system error has occurred. Check the system error code for more details. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_INVALID_CONF\fR\fR +.ad +.RS 20n +The pool element could not be created because the configuration would be +invalid. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_PUTPROP\fR\fR +.ad +.RS 20n +One of the supplied properties could not be set. +.RE + +.sp +.LP +The \fBpool_destroy()\fR function will fail if: +.sp +.ne 2 +.na +\fB\fBPOE_BADPARAM\fR\fR +.ad +.RS 16n +The supplied configuration's status is not \fBPOF_VALID\fR. +.RE + +.sp +.LP +The \fBpool_associate()\fR function will fail if: +.sp +.ne 2 +.na +\fB\fBPOE_BADPARAM\fR\fR +.ad +.RS 16n +The supplied configuration's status is not \fBPOF_VALID\fR or the parameters +are supplied from a different configuration. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_SYSTEM\fR\fR +.ad +.RS 16n +A system error has occurred. Check the system error code for more details. +.RE + +.sp +.LP +The \fBpool_disassociate()\fR function will fail if: +.sp +.ne 2 +.na +\fB\fBPOE_BADPARAM\fR\fR +.ad +.RS 20n +The supplied configuration's status is not \fBPOF_VALID\fR or the parameters +are supplied from a different configuration. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_INVALID_CONF\fR\fR +.ad +.RS 20n +No resources could be located for the supplied configuration or the supplied +configuration is not valid (for example, more than one default for a resource +type was found.) +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_SYSTEM\fR\fR +.ad +.RS 20n +A system error has occurred. Check the system error code for more details. +.RE + +.sp +.LP +The \fBpool_info()\fR function will fail if: +.sp +.ne 2 +.na +\fB\fBPOE_BADPARAM\fR\fR +.ad +.RS 20n +The supplied configuration's status is not \fBPOF_VALID\fR or the \fIflags\fR +paramter is neither 0 or 1. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_INVALID_CONF\fR\fR +.ad +.RS 20n +The configuration is invalid. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_SYSTEM\fR\fR +.ad +.RS 20n +A system error has occurred. Check the system error code for more details. +.RE + +.sp +.LP +The \fBpool_query_pool_resources()\fR function will fail if: +.sp +.ne 2 +.na +\fB\fBPOE_BADPARAM\fR\fR +.ad +.RS 20n +The supplied configuration's status is not \fBPOF_VALID\fR. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_INVALID_CONF\fR\fR +.ad +.RS 20n +The configuration is invalid. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_SYSTEM\fR\fR +.ad +.RS 20n +A system error has occurred. Check the system error code for more details. +.RE + +.SH USAGE +.sp +.LP +Pool names are unique across pools in a given configuration file. It is an +error to attempt to create a pool with a name that is currently used by another +pool within the same configuration. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +CSI Enabled +_ +Interface Stability Unstable +_ +MT-Level Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibpool\fR(3LIB), \fBpool_error\fR(3POOL), \fBattributes\fR(5) diff --git a/usr/src/man/man3pool/pool_component_info.3pool b/usr/src/man/man3pool/pool_component_info.3pool new file mode 100644 index 0000000..53e53f0 --- /dev/null +++ b/usr/src/man/man3pool/pool_component_info.3pool @@ -0,0 +1,122 @@ +'\" 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 POOL_COMPONENT_INFO 3POOL "Sep 23, 2003" +.SH NAME +pool_component_info, pool_get_owning_resource \- resource pool component +functions +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lpool\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <pool.h> + +\fBconst char *\fR\fBpool_component_info\fR(\fBpool_conf_t *\fR\fIconf\fR, + \fBpool_component_t *\fR\fIcomponent\fR, \fBint\fR \fIflags\fR); +.fi + +.LP +.nf +\fBpool_resource_t *\fR\fBpool_get_owning_resource\fR(\fBpool_conf_t *\fR\fIconf\fR, + \fBpool_component_t *\fR\fIcomponent\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +Certain resources, such as processor sets, are composed of resource components. +Informational and ownership attributes of resource components are made +available with the \fBpool_component_info()\fR and +\fBpool_get_owning_resource()\fR functions. The \fIconf\fR argument for each +function refers to the target configuration to which the operation applies. +.sp +.LP +The \fBpool_component_info()\fR function returns a string describing +\fIcomponent\fR. The string is allocated with \fBmalloc\fR(3C). The caller is +reponsible for freeing the returned string. The \fIflags\fR argument is +ignored. +.sp +.LP +The \fBpool_get_owning_resource()\fR function returns the resource currently +containing \fIcomponent\fR. Every component is contained by a resource. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBpool_component_info()\fR returns a string. +Otherwise it returns \fINULL\fR and \fBpool_error\fR(3POOL) returns the +pool-specific error value. +.sp +.LP +Upon successful completion, \fBpool_get_owning_resource()\fR returns the owning +resource. Otherwise it returns \fINULL\fR and \fBpool_error()\fR returns the +pool-specific error value. +.SH ERRORS +.sp +.LP +The \fBpool_component_info()\fR function will fail if: +.sp +.ne 2 +.na +\fB\fBPOE_BADPARAM\fR\fR +.ad +.RS 20n +The supplied configuration's status is not \fBPOF_VALID\fR or the \fIflags\fR +paramter is neither 0 or 1. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_INVALID_CONF\fR\fR +.ad +.RS 20n +The configuration is invalid. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_SYSTEM\fR\fR +.ad +.RS 20n +A system error has occurred. Check the system error code for more details. +.RE + +.sp +.LP +The \fBpool_get_owning_resource()\fR function will fail if: +.sp +.ne 2 +.na +\fB\fBPOE_BADPARAM\fR\fR +.ad +.RS 16n +The supplied configuration's status is not \fBPOF_VALID\fR. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +CSI Enabled +_ +Interface Stability Unstable +_ +MT-Level Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibpool\fR(3LIB), \fBpool_error\fR(3POOL), \fBattributes\fR(5) diff --git a/usr/src/man/man3pool/pool_component_to_elem.3pool b/usr/src/man/man3pool/pool_component_to_elem.3pool new file mode 100644 index 0000000..39bb56f --- /dev/null +++ b/usr/src/man/man3pool/pool_component_to_elem.3pool @@ -0,0 +1,86 @@ +'\" 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 POOL_COMPONENT_TO_ELEM 3POOL "Sep 23, 2003" +.SH NAME +pool_component_to_elem, pool_to_elem, pool_conf_to_elem, pool_resource_to_elem +\- resource pool element-related functions +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lpool\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <pool.h> + +\fBpool_elem_t *\fR\fBpool_component_to_elem\fR(\fBpool_conf_t *\fR\fIconf\fR, + \fBpool_component_t *\fR\fIcomponent\fR); +.fi + +.LP +.nf +\fBpool_elem_t *\fR\fBpool_conf_to_elem\fR(\fBpool_conf_t *\fR\fIconf\fR); +.fi + +.LP +.nf +\fBpool_elem_t *\fR\fBpool_resource_to_elem\fR(\fBpool_conf_t *\fR\fIconf\fR + \fBpool_resource_t *\fR\fIresource\fR); +.fi + +.LP +.nf +\fBpool_elem_t *\fR\fBpool_to_elem\fR(\fBpool_conf_t *\fR\fIconf\fR, \fBpool_t *\fR\fIpool\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +A pool element, as represented by a \fBpool_elem_t\fR, is a common abstraction +for any \fBlibpool\fR entity that contains properties. All such types can be +converted to the opaque \fBpool_elem_t\fR type using the appropriate conversion +functions prototyped above. The \fIconf\fR argument for each function refers to +the target configuration to which the operation applies. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, these functions return a \fBpool_elem_t\fR +corresponding to the argument passed in. Otherwise they return \fINULL\fR and +\fBpool_error\fR(3POOL) returns the pool-specific error value. +.SH ERRORS +.sp +.LP +These function will fail if: +.sp +.ne 2 +.na +\fB\fBPOE_BADPARAM\fR\fR +.ad +.RS 16n +The supplied configuration's status is not \fBPOF_VALID\fR. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +CSI Enabled +_ +Interface Stability Unstable +_ +MT-Level Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibpool\fR(3LIB), \fBpool_error\fR(3POOL), \fBattributes\fR(5) diff --git a/usr/src/man/man3pool/pool_conf_alloc.3pool b/usr/src/man/man3pool/pool_conf_alloc.3pool new file mode 100644 index 0000000..011584a --- /dev/null +++ b/usr/src/man/man3pool/pool_conf_alloc.3pool @@ -0,0 +1,669 @@ +'\" te +.\" Copyright (c) 2009, 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 POOL_CONF_ALLOC 3POOL "Aug 3, 2009" +.SH NAME +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_update, +pool_conf_validate \- manipulate resource pool configurations +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lpool\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <pool.h> + +\fBpool_conf_t *\fR\fBpool_conf_alloc\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBint\fR \fBpool_conf_close\fR(\fBpool_conf_t *\fR\fIconf\fR); +.fi + +.LP +.nf +\fBint\fR \fBpool_conf_commit\fR(\fBpool_conf_t *\fR\fIconf\fR, \fBint\fR \fIactive\fR); +.fi + +.LP +.nf +\fBint\fR \fBpool_conf_export\fR(\fBpool_conf_t *\fR\fIconf\fR, \fBconst char *\fR\fIlocation\fR, + \fBpool_export_format_t\fR \fIformat\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBpool_conf_free\fR(\fBpool_conf_t *\fR\fIconf\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBpool_conf_info\fR(\fBconst pool_conf_t *\fR\fIconf\fR, \fBint\fR \fIflags\fR); +.fi + +.LP +.nf +\fBconst char *\fR\fBpool_conf_location\fR(\fBpool_conf_t *\fR\fIconf\fR); +.fi + +.LP +.nf +\fBint\fR \fBpool_conf_open\fR(\fBpool_conf_t *\fR\fIconf\fR, \fBconst char *\fR\fIlocation\fR, + \fBint\fR \fIflags\fR); +.fi + +.LP +.nf +\fBint\fR \fBpool_conf_remove\fR(\fBpool_conf_t *\fR\fIconf\fR); +.fi + +.LP +.nf +\fBint\fR \fBpool_conf_rollback\fR(\fBpool_conf_t *\fR\fIconf\fR); +.fi + +.LP +.nf +\fBpool_conf_state_t\fR \fBpool_conf_status\fR(\fBconst pool_conf_t *\fR\fIconf\fR); +.fi + +.LP +.nf +\fBint\fR \fBpool_conf_update\fR(\fBconst pool_conf_t *\fR\fIconf\fR, \fBint *\fR\fIchanged\fR); +.fi + +.LP +.nf +\fBint\fR \fBpool_conf_validate\fR(\fBpool_conf_t *\fR\fIconf\fR, + \fBpool_valid_level_t\fR \fIlevel\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions enable the access and creation of configuration files +associated with the pools facility. Since the pool configuration is an opaque +type, an initial configuration is obtained with \fBpool_conf_alloc()\fR and +released with \fBpool_conf_free()\fR when the configuration is no longer of +interest. The \fIconf\fR argument for each function refers to the target +configuration to which the operation applies. +.sp +.LP +The \fBpool_conf_close()\fR function closes the given configuration, releasing +associated resources. +.sp +.LP +The \fBpool_conf_commit()\fR function commits changes made to the given +\fBpool_conf_t\fR to permanent storage. If the \fIactive\fR flag is non-zero, +the state of the system will be configured to match that described in the +supplied \fBpool_conf_t\fR. If configuring the system fails, +\fBpool_conf_commit()\fR will attempt to restore the system to its previous +state. +.sp +.LP +The \fBpool_conf_export()\fR function saves the given configuration to the +specified location. The only currently supported value of \fIformat\fR is +\fBPOX_NATIVE\fR, which is the format native to \fBlibpool\fR, the output of +which can be used as input to \fBpool_conf_open()\fR. +.sp +.LP +The \fBpool_conf_info()\fR function returns a string describing the entire +configuration. The string is allocated with \fBmalloc\fR(3C). The caller is +responsible for freeing the returned string. If the flags option is non-zero, +the string returned also describes the sub-elements (if any) contained in the +configuration. +.sp +.LP +The \fBpool_conf_location()\fR function returns the location string provided to +\fBpool_conf_open()\fR for the given \fBpool_conf_t\fR. +.sp +.LP +The \fBpool_conf_open()\fR function creates a \fBpool_conf_t\fR given a +location at which the configuration is stored. The valid flags are a bitmap of +the following: +.sp +.ne 2 +.na +\fB\fBPO_RDONLY\fR\fR +.ad +.RS 13n +Open for reading only. +.RE + +.sp +.ne 2 +.na +\fB\fBPO_RDWR\fR\fR +.ad +.RS 13n +Open read-write. +.RE + +.sp +.ne 2 +.na +\fB\fBPO_CREAT\fR\fR +.ad +.RS 13n +Create a configuration at the given location if it does not exist. If it does, +truncate it. +.RE + +.sp +.ne 2 +.na +\fB\fBPO_DISCO\fR\fR +.ad +.RS 13n +Perform `discovery'. This option only makes sense when used in conjunction with +\fBPO_CREAT\fR, and causes the returned \fBpool_conf_t\fR to contain the +resources and components currently active on the system. +.sp +The use of this flag is deprecated. \fBPO_CREAT\fR always performs discovery. +If supplied, this flag is ignored. +.RE + +.sp +.ne 2 +.na +\fB\fBPO_UPDATE\fR\fR +.ad +.RS 13n +Use when opening the dynamic state file, which is the configuration at +\fBpool_dynamic_location\fR(3POOL), to ensure that the contents of the dynamic +state file are updated to represent the current state of the system. +.sp +The use of this flag is deprecated. The dynamic state is always current and +does not require updating. If supplied, this flag is ignored. +.RE + +.sp +.LP +A call to \fBpool_conf_open()\fR with the pool dynamic location and write +permission will hang if the dynamic location has already been opened for +writing. +.sp +.LP +The \fBpool_conf_remove()\fR function removes the configuration's permanent +storage. If the configuration is still open, it is first closed. +.sp +.LP +The \fBpool_conf_rollback()\fR function restores the configuration state to +that held in the configuration's permanent storage. This will either be the +state last successfully committed (using \fBpool_conf_commit()\fR) or the state +when the configuration was opened if there have been no successfully committed +changes since then. +.sp +.LP +The \fBpool_conf_status()\fR function returns the status of a configuration, +which can be one of the following values: +.sp +.ne 2 +.na +\fB\fBPOF_INVALID\fR\fR +.ad +.RS 15n +The configuration is not in a suitable state for use. +.RE + +.sp +.ne 2 +.na +\fB\fBPOF_VALID\fR\fR +.ad +.RS 15n +The configuration is in a suitable state for use. +.RE + +.sp +.LP +The \fBpool_conf_update()\fR function updates the library snapshot of kernel +state. If \fIchanged\fR is non-null, it is updated to identify which types of +configuration elements changed during the update. To check for change, treat +the \fIchanged\fR value as a bitmap of possible element types. +.sp +.LP +A change is defined for the different element classes as follows: +.sp +.ne 2 +.na +\fB\fBPOU_SYSTEM\fR\fR +.ad +.RS 14n +A property on the system element has been created, modified, or removed. +.RE + +.sp +.ne 2 +.na +\fB\fBPOU_POOL\fR\fR +.ad +.RS 14n +A property on a pool element has been created, modified, or removed. A pool has +changed a resource association. +.RE + +.sp +.ne 2 +.na +\fB\fBPOU_PSET\fR\fR +.ad +.RS 14n +A property on a pset element has been created, modified, or removed. A pset's +resource composition has changed. +.RE + +.sp +.ne 2 +.na +\fB\fBPOU_CPU\fR\fR +.ad +.RS 14n +A property on a CPU element has been created, modified, or removed. +.RE + +.sp +.LP +The \fBpool_conf_validate()\fR function checks the validity of the contents of +the given configuration. The validation can be at several (increasing) levels +of strictness: +.sp +.ne 2 +.na +\fB\fBPOV_LOOSE\fR\fR +.ad +.RS 15n +Performs basic internal syntax validation. +.RE + +.sp +.ne 2 +.na +\fB\fBPOV_STRICT\fR\fR +.ad +.RS 15n +Performs a more thorough syntax validation and internal consistency checks. +.RE + +.sp +.ne 2 +.na +\fB\fBPOV_RUNTIME\fR\fR +.ad +.RS 15n +Performs an estimate of whether attempting to commit the given configuration on +the system would succeed or fail. It is optimistic in that a successful +validation does not guarantee a subsequent commit operation will be successful; +it is conservative in that a failed validation indicates that a subsequent +commit operation on the current system will always fail. +.RE + +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBpool_conf_alloc()\fR returns an initialized +\fBpool_conf_t\fR pointer. Otherwise it returns \fINULL\fR and +\fBpool_error\fR(3POOL) returns the pool-specific error value. +.sp +.LP +Upon successful completion, \fBpool_conf_close()\fR, \fBpool_conf_commit()\fR, +\fBpool_conf_export()\fR, \fBpool_conf_open()\fR, \fBpool_conf_remove()\fR, +\fBpool_conf_rollback()\fR, \fBpool_conf_update()\fR, and +\fBpool_conf_validate()\fR return 0. Otherwise they return -1 and +\fBpool_error()\fR returns the pool-specific error value. +.sp +.LP +The \fBpool_conf_status()\fR function returns either \fBPOF_INVALID\fR or +\fBPOF_VALID\fR. +.SH ERRORS +.sp +.LP +The \fBpool_conf_alloc()\fR function will fail if: +.sp +.ne 2 +.na +\fB\fBPOE_SYSTEM\fR\fR +.ad +.RS 20n +There is not enough memory available to allocate the configuration. Check +\fBerrno\fR for the specific system error code. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_INVALID_CONF\fR\fR +.ad +.RS 20n +The configuration is invalid. +.RE + +.sp +.LP +The \fBpool_conf_close()\fR function will fail if: +.sp +.ne 2 +.na +\fB\fBPOE_BADPARAM\fR\fR +.ad +.RS 16n +The supplied configuration's status is not \fBPOF_VALID\fR. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_SYSTEM\fR\fR +.ad +.RS 16n +The configuration's permanent store cannot be closed. Check \fBerrno\fR for +the specific system error code. +.RE + +.sp +.LP +The \fBpool_conf_commit()\fR function will fail if: +.sp +.ne 2 +.na +\fB\fBPOE_BADPARAM\fR\fR +.ad +.RS 20n +The supplied configuration's status is not \fBPOF_VALID\fR or the active flag +is non-zero and the system could not be modified. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_SYSTEM\fR\fR +.ad +.RS 20n +The permanent store could not be updated. Check \fBerrno\fR for the specific +system error code. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_INVALID_CONF\fR\fR +.ad +.RS 20n +The configuration is not valid for this system. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_ACCESS\fR\fR +.ad +.RS 20n +The configuration was not opened with the correct permissions. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_DATASTORE\fR\fR +.ad +.RS 20n +The update of the permanent store has failed and the contents could be +corrupted. Check for a \fB\&.bak\fR file at the datastore location if manual +recovery is required. +.RE + +.sp +.LP +The \fBpool_conf_export()\fR function will fail if: +.sp +.ne 2 +.na +\fB\fBPOE_BADPARAM\fR\fR +.ad +.RS 17n +The supplied configuration's status is not \fBPOF_VALID\fR or the requested +export format is not supported. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_DATASTORE\fR\fR +.ad +.RS 17n +The creation of the export file failed. A file might have been created at the +specified location but the contents of the file might not be correct. +.RE + +.sp +.LP +The \fBpool_conf_info()\fR function will fail if: +.sp +.ne 2 +.na +\fB\fBPOE_BADPARAM\fR\fR +.ad +.RS 20n +The supplied configuration's status is not \fBPOF_VALID\fR or \fIflags\fR is +neither 0 nor 1. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_SYSTEM\fR\fR +.ad +.RS 20n +There is not enough memory available to allocate the buffer used to build the +information string. Check \fBerrno\fR for the specific system error code. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_INVALID_CONF\fR\fR +.ad +.RS 20n +The configuration is invalid. +.RE + +.sp +.LP +The \fBpool_conf_location()\fR function will fail if: +.sp +.ne 2 +.na +\fB\fBPOE_BADPARAM\fR\fR +.ad +.RS 16n +The supplied configuration's status is not \fBPOF_VALID\fR. +.RE + +.sp +.LP +The \fBpool_conf_open()\fR function will fail if: +.sp +.ne 2 +.na +\fB\fBPOE_BADPARAM\fR\fR +.ad +.RS 20n +The supplied configuration's status is already \fBPOF_VALID\fR. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_SYSTEM\fR\fR +.ad +.RS 20n +There is not enough memory available to store the supplied location, or the +pools facility is not active. Check \fBerrno\fR for the specific system error +code. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_INVALID_CONF\fR\fR +.ad +.RS 20n +The configuration to be opened is at \fBpool_dynamic_location\fR(3POOL) and the +configuration is not valid for this system. +.RE + +.sp +.LP +The \fBpool_conf_remove()\fR function will fail if: +.sp +.ne 2 +.na +\fB\fBPOE_BADPARAM\fR\fR +.ad +.RS 16n +The supplied configuration's status is not \fBPOF_VALID\fR. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_SYSTEM\fR\fR +.ad +.RS 16n +The configuration's permanent storage could not be removed. Check \fBerrno\fR +for the specific system error code. +.RE + +.sp +.LP +The \fBpool_conf_rollback()\fR function will fail if: +.sp +.ne 2 +.na +\fB\fBPOE_BADPARAM\fR\fR +.ad +.RS 16n +The supplied configuration's status is not \fBPOF_VALID\fR. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_SYSTEM\fR\fR +.ad +.RS 16n +The permanent store could not be accessed. Check \fBerrno\fR for the specific +system error code. +.RE + +.sp +.LP +The \fBpool_conf_update()\fR function will fail if: +.sp +.ne 2 +.na +\fB\fBPOE_BADPARAM\fR\fR +.ad +.RS 20n +The supplied configuration's status is not \fBPOF_VALID\fR or the configuration +is not the dynamic configuration. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_DATASTORE\fR\fR +.ad +.RS 20n +The kernel snapshot cannot be correctly unpacked. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_INVALID_CONF\fR\fR +.ad +.RS 20n +The configuration contains uncommitted transactions. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_SYSTEM\fR\fR +.ad +.RS 20n +A system error occurred during snapshot retrieval and update. +.RE + +.sp +.LP +The \fBpool_conf_validate()\fR function will fail if: +.sp +.ne 2 +.na +\fB\fBPOE_BADPARAM\fR\fR +.ad +.RS 20n +The supplied configuration's status is not \fBPOF_VALID\fR. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_INVALID_CONF\fR\fR +.ad +.RS 20n +The configuration is invalid. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRCreate the configuration at the specified location. +.sp +.in +2 +.nf +#include <pool.h> +#include <stdio.h> + +\&... + +pool_conf_t *pool_conf; +pool_conf = pool_conf_alloc(); +char *input_location = "/tmp/poolconf.example"; + +if (pool_conf_open(pool_conf, input_location, + PO_RDONLY) < 0) { + fprintf(stderr, "Opening pool configuration %s + failed\en", input_location); +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +CSI Enabled +_ +Interface Stability Uncommitted +_ +MT-Level Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibpool\fR(3LIB), \fBpool_error\fR(3POOL), \fBattributes\fR(5) diff --git a/usr/src/man/man3pool/pool_dynamic_location.3pool b/usr/src/man/man3pool/pool_dynamic_location.3pool new file mode 100644 index 0000000..99dc2e0 --- /dev/null +++ b/usr/src/man/man3pool/pool_dynamic_location.3pool @@ -0,0 +1,206 @@ +'\" 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 POOL_DYNAMIC_LOCATION 3POOL "Sep 23, 2003" +.SH NAME +pool_dynamic_location, pool_static_location, pool_version, pool_get_status, +pool_set_status, pool_resource_type_list \- resource pool framework functions +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lpool\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <pool.h> + +\fBconst char *\fR\fBpool_dynamic_location\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBconst char *\fR\fBpool_static_location\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBuint_t\fR \fBpool_version\fR(\fBuint_t\fR \fIver\fR); +.fi + +.LP +.nf +\fBint\fR \fBpool_get_status\fR(\fBint *\fR\fIstate\fR); +.fi + +.LP +.nf +\fBint\fR \fBpool_set_status\fR(\fBint\fR \fIstate\fR); +.fi + +.LP +.nf +\fBint\fR \fBpool_resource_type_list\fR(\fBconst char **\fR\fIreslist\fR, + \fBuint_t *\fR\fInumres\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpool_dynamic_location()\fR function returns the location used by the +pools framework to store the dynamic configuration. +.sp +.LP +The \fBpool_static_location()\fR function returns the location used by the +pools framework to store the default configuration used for pools framework +instantiation. +.sp +.LP +The \fBpool_version()\fR function can be used to inquire about the version +number of the library by specifying \fBPOOL_VER_NONE\fR. The current (most +capable) version is \fBPOOL_VER_CURRENT\fR. The user can set the version used +by the library by specifying the required version number. If this is not +possible, the version returned will be \fBPOOL_VER_NONE\fR. +.sp +.LP +The \fBpool_get_status()\fR function retrieves the current state of the pools +facility. If state is non-null, then on successful completion the state of the +pools facility is stored in the location pointed to by state. +.sp +.LP +The \fBpool_set_status()\fR function modifies the current state of the pools +facility. On successful completion the state of the pools facility is changed +to match the value supplied in state. Only two values are valid for state, +\fBPOOL_DISABLED\fR and \fBPOOL_ENABLED\fR, both of which are defined in +<\fBpool.h\fR>. +.sp +.LP +The \fBpool_resource_type_list()\fR function enumerates the resource types +supported by the pools framework on this platform. If \fInumres\fR and +\fIreslist\fR are both non-null, \fIreslist\fR points to a buffer where a list +of resource types in the system is to be stored, and \fInumres\fR points to the +maximum number of resource types the buffer can hold. On successful completion, +the list of resource types up to the maximum buffer size is stored in the +buffer pointed to by \fIreslist\fR. +.SH RETURN VALUES +.sp +.LP +The \fBpool_dynamic_location()\fR function returns the location used by the +pools framework to store the dynamic configuration. +.sp +.LP +The \fBpool_static_location()\fR function returns the location used by the +pools framework to store the default configuration used for pools framework +instantiation. +.sp +.LP +The \fBpool_version()\fR function returns the version number of the library or +\fBPOOL_VER_NONE\fR. +.sp +.LP +Upon successful completion, \fBpool_get_status()\fR, \fBpool_set_status()\fR, +and \fBpool_resource_type_list()\fR all return 0. Otherwise, \(mi1 is returned +and \fBpool_error\fR(3POOL) returns the pool specific error. +.SH ERRORS +.sp +.LP +No errors are defined for \fBpool_dynamic_location()\fR, +\fBpool_static_location()\fR, and \fBpool_version()\fR. +.sp +.LP +The \fBpool_get_status()\fR function will fail if: +.sp +.ne 2 +.na +\fB\fBPOE_SYSTEM\fR\fR +.ad +.RS 14n +A system error occurred when accessing the kernel pool state. +.RE + +.sp +.LP +The \fBpool_set_status()\fR function will fail if: +.sp +.ne 2 +.na +\fB\fBPOE_SYSTEM\fR\fR +.ad +.RS 14n +A system error occurred when modifying the kernel pool state. +.RE + +.sp +.LP +The \fBpool_resource_type_list()\fR function will fail if: +.sp +.ne 2 +.na +\fB\fBPOE_BADPARAM\fR\fR +.ad +.RS 16n +The \fInumres\fR parameter was \fINULL\fR. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRGet the static location used by the pools framework. +.sp +.in +2 +.nf +#include sys/types.h> +#include <unistd.h> +#include <pool.h> + +\&... + +const char *location = pool_dynamic_location(); + +\&... + + (void) fprintf(stderr, "pool dynamic location is %s\en", + location); +.fi +.in -2 + +.LP +\fBExample 2 \fREnable the pools facility. +.sp +.in +2 +.nf +#include <stdio.h> +#include <pool.h> + +\&... + + if (pool_set_status(POOL_ENABLED) != 0) { + (void) fprintf(stderr, "pools could not be enabled %s\en", + pool_strerror(pool_error())); + exit(2); + } +\&... +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +CSI Enabled +_ +Interface Stability Unstable +_ +MT-Level Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibpool\fR(3LIB), \fBpool_error\fR(3POOL), \fBattributes\fR(5) diff --git a/usr/src/man/man3pool/pool_error.3pool b/usr/src/man/man3pool/pool_error.3pool new file mode 100644 index 0000000..a5c1f36 --- /dev/null +++ b/usr/src/man/man3pool/pool_error.3pool @@ -0,0 +1,176 @@ +'\" 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 POOL_ERROR 3POOL "Sep 23, 2003" +.SH NAME +pool_error, pool_strerror \- error interface to resource pools library +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lpool\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <pool.h> + +\fBint\fR \fBpool_error\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBconst char *\fR\fBpool_strerror\fR(\fBint\fR \fIperr\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpool_error()\fR function returns the error value of the last failure +recorded by the invocation of one of the functions of the resource pool +configuration library, \fBlibpool\fR. +.sp +.LP +The \fBpool_strerror()\fR function returns a descriptive null-terminated string +for each of the valid pool error codes. +.sp +.LP +The following error codes can be returned by \fBpool_error()\fR: +.SH RETURN VALUES +.sp +.LP +The \fBpool_error()\fR function returns the current pool error value for the +calling thread from among the following: +.sp +.ne 2 +.na +\fB\fBPOE_ACCESS\fR\fR +.ad +.RS 22n +The operation could not be performed because the configuration was not opened +with the correct opening permissions. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_BADPARAM\fR\fR +.ad +.RS 22n +A bad parameter was supplied. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_BAD_PROP_TYPE\fR\fR +.ad +.RS 22n +An incorrect property type was submitted or encountered during the pool +operation. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_DATASTORE\fR\fR +.ad +.RS 22n +An error occurred within permanent storage. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_INVALID_CONF\fR\fR +.ad +.RS 22n +The pool configuration presented for the operation is invalid. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_INVALID_SEARCH\fR\fR +.ad +.RS 22n +A query whose outcome set was empty was attempted. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_NOTSUP\fR\fR +.ad +.RS 22n +An unsupported operation was attempted. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_PUTPROP\fR\fR +.ad +.RS 22n +An attempt to write a read-only property was made. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_OK\fR\fR +.ad +.RS 22n +The previous pool operation succeeded. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_SYSTEM\fR\fR +.ad +.RS 22n +An underlying system call or library function failed; \fBerrno\fR(3C) is +preserved where possible. +.RE + +.sp +.LP +The \fBpool_strerror()\fR function returns a pointer to the string +corresponding to the requested error value. If the error value has no +corresponding string, \(mi1 is returned and \fBerrno\fR is set to indicate the +error. +.SH ERRORS +.sp +.LP +The \fBpool_strerror()\fR function will fail if: +.sp +.ne 2 +.na +\fB\fBESRCH\fR\fR +.ad +.RS 9n +The specified error value is not defined by the pools error facility. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +CSI Enabled +_ +Interface Stability Unstable +_ +MT-Level Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBerrno\fR(3C), \fBlibpool\fR(3LIB), pool_error(3POOL), \fBattributes\fR(5) diff --git a/usr/src/man/man3pool/pool_get_binding.3pool b/usr/src/man/man3pool/pool_get_binding.3pool new file mode 100644 index 0000000..b1cae5d --- /dev/null +++ b/usr/src/man/man3pool/pool_get_binding.3pool @@ -0,0 +1,249 @@ +'\" te +.\" Copyright (c) 2007, 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 POOL_GET_BINDING 3POOL "Mar 27, 2007" +.SH NAME +pool_get_binding, pool_set_binding, pool_get_resource_binding \- set and query +process to resource pool bindings +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lpool\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <pool.h> + +\fBchar *\fR\fBpool_get_binding\fR(\fBpid_t\fR \fIpid\fR); +.fi + +.LP +.nf +\fBint\fR \fBpool_set_binding\fR(\fBconst char *\fR\fIpool\fR, \fBidtype_t\fR \fIidtype\fR, + \fBid_t\fR \fIid\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBpool_get_resource_binding\fR(\fBconst char *\fR\fItype\fR, \fBpid_t\fR \fIpid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpool_get_binding()\fR function returns the name of the pool on the +running system that contains the set of resources to which the given process is +bound. If no such pool exists on the system or the search returns more than one +pool (since the set of resources is referred to by more than one pool), +\fINULL\fR is returned and the pool error value is set to +\fBPOE_INVALID_SEARCH\fR. +.sp +.LP +It is possible that one of the resources to which the given process is bound is +not associated with a pool. This could occur if a processor set was created +with one of the \fBpset_()\fR functions and the process was then bound to that +set. It could also occur if the process was bound to a resource set not +currently associated with a pool, since resources can exist that are not +associated with a pool. +.sp +.LP +The \fBpool_set_binding()\fR function binds the processes matching \fIidtype\fR +and \fIid\fR to the resources associated with \fIpool\fR on the running system. +This function requires the privilege required by the underlying resource types +referenced by the pool; generally, this requirement is equivalent to requiring +superuser privilege. +.sp +.LP +The \fIidtype\fR parameter can be of the following types: +.sp +.ne 2 +.na +\fB\fBP_PID\fR\fR +.ad +.RS 12n +The \fIid\fR parameter is a pid. +.RE + +.sp +.ne 2 +.na +\fB\fBP_TASKID\fR\fR +.ad +.RS 12n +The \fIid\fR parameter is a taskid. +.RE + +.sp +.ne 2 +.na +\fB\fBP_PROJID\fR\fR +.ad +.RS 12n +The \fIid\fR parameter is a project ID. All currently running processes +belonging to the given project will be bound to the pool's resources. +.RE + +.sp +.LP +The \fBpool_get_resource_binding()\fR function returns the name of the resource +of the supplied type to which the supplied process is bound. +.sp +.LP +The application must explicity free the memory allocated for the return values +for \fBpool_get_binding()\fR and \fBpool_get_resource_binding()\fR. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBpool_get_binding()\fR returns the name of the +pool to which the process is bound. Otherwise it returns \fINULL\fR and +\fBpool_error\fR(3POOL) returns the pool-specific error value. +.sp +.LP +Upon successful completion, \fBpool_set_binding()\fR returns \fBPO_SUCCESS\fR. +Otherwise, it returns \fBPO_FAIL\fR and \fBpool_error()\fR returns the +pool-specific error value. +.sp +.LP +Upon successful completion, \fBpool_get_resource_binding()\fR returns the name +of the resource of the specified type to which the process is bound. Otherwise +it returns \fINULL\fR and \fBpool_error()\fR returns the pool-specific error +value. +.SH ERRORS +.sp +.LP +The \fBpool_get_binding()\fR function will fail if: +.sp +.ne 2 +.na +\fB\fBPOE_INVALID_CONF\fR\fR +.ad +.RS 22n +The configuration is invalid. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_INVALID_SEARCH\fR\fR +.ad +.RS 22n +It is not possible to determine the binding for this target due to the +overlapping nature of the pools configured for this system, or the pool could +not be located. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_SYSTEM\fR\fR +.ad +.RS 22n +A system error has occurred. Check the system error code for more details. +.RE + +.sp +.LP +The \fBpool_set_binding()\fR function will fail if: +.sp +.ne 2 +.na +\fB\fBPOE_INVALID_SEARCH\fR\fR +.ad +.RS 22n +The pool could not be found. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_INVALID_CONF\fR\fR +.ad +.RS 22n +The configuration is invalid. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_SYSTEM\fR\fR +.ad +.RS 22n +A system error has occurred. Check the system error code for more details. +.RE + +.sp +.LP +The \fBpool_get_resource_binding()\fR function will fail if: +.sp +.ne 2 +.na +\fB\fBPOE_INVALID_CONF\fR\fR +.ad +.RS 22n +The configuration is invalid. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_INVALID_SEARCH\fR\fR +.ad +.RS 22n +The target is not bound to a resource of the specified type. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_SYSTEM\fR\fR +.ad +.RS 22n +A system error has occurred. Check the system error code for more details. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRBind the current process to the pool named "target". +.sp +.in +2 +.nf +#include <sys/types.h> +#include <pool.h> +#include <unistd.h> + +\&... + +id_t pid = getpid(); + +\&... + +if (pool_set_binding("target", P_PID, pid) == PO_FAIL) \{ + (void) fprintf(stderr, "pool binding failed (\\%d)\\B{}n", + pool_error()); +\} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +CSI Enabled +_ +Interface Stability Unstable +_ +MT-Level Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibpool\fR(3LIB), \fBpool_error\fR(3POOL), \fBattributes\fR(5) diff --git a/usr/src/man/man3pool/pool_get_pool.3pool b/usr/src/man/man3pool/pool_get_pool.3pool new file mode 100644 index 0000000..591a40f --- /dev/null +++ b/usr/src/man/man3pool/pool_get_pool.3pool @@ -0,0 +1,203 @@ +'\" te +.\" Copyright (c) 2005, 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 POOL_GET_POOL 3POOL "Jul 18, 2005" +.SH NAME +pool_get_pool, pool_get_resource, pool_query_components, pool_query_pools, +pool_query_resources \- retrieve resource pool configuration elements +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR]\&.\|.\|. \fIfile\fR\&.\|.\|. \fB-lpool\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <pool.h> + +\fBpool_t *\fR\fBpool_get_pool\fR(\fBpool_conf_t *\fR\fIconf\fR, \fBconst char *\fR\fIname\fR); +.fi + +.LP +.nf +\fBpool_resource_t *\fR\fBpool_get_resource\fR(\fBpool_conf_t *\fR\fIconf\fR + \fBconst char *\fR\fItype\fR, \fBconst char *\fR\fIname\fR); +.fi + +.LP +.nf +\fBpool_component_t **\fR\fBpool_query_components\fR(\fBpool_conf_t *\fR\fIconf\fR, + \fBuint_t *\fR\fInelem\fR, \fBpool_value_t **\fR\fIprops\fR); +.fi + +.LP +.nf +\fBpool_t **\fR\fBpool_query_pools\fR(\fBpool_conf_t *\fR\fIconf\fR, \fBuint_t *\fR\fInelem\fR, + \fBpool_value_t **\fR\fIprops\fR); +.fi + +.LP +.nf +\fBpool_component_t **\fR\fBpool_query_resources\fR(\fBpool_conf_t *\fR\fIconf\fR, + \fBuint_t *\fR\fInelem\fR, \fBpool_value_t **\fR\fIprops\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions provide a means for querying the contents of the specified +configuration. The \fIconf\fR argument for each function refers to the target +configuration to which the operation applies. +.sp +.LP +The \fBpool_get_pool()\fR function returns the pool with the given name from +the provided configuration. +.sp +.LP +The \fBpool_get_resource()\fR function returns the resource with the given name +and type from the provided configuration. +.sp +.LP +The \fBpool_query_components()\fR function retrieves all resource components +that match the given list of properties. If the list of properties is +\fINULL\fR, all components are returned. The number of elements returned is +stored in the location pointed to by \fInelem\fR. The value returned by +\fBpool_query_components()\fR is allocated with \fBmalloc\fR(3C) and must be +explicitly freed. +.sp +.LP +The \fBpool_query_pools()\fR function behaves similarly to +\fBpool_query_components()\fR and returns the list of pools that match the +given list of properties. The value returned must be freed by the caller. +.sp +.LP +The \fBpool_query_resources()\fR function similarly returns the list of +resources that match the given list of properties. The return value must be +freed by the caller. +.SH RETURN VALUES +.sp +.LP +The \fBpool_get_pool()\fR and \fBpool_get_resource()\fR functions return the +matching pool and resource, respectively. Otherwise, they return \fINULL\fR and +\fBpool_error\fR(3POOL) returns the pool-specific error value. +.sp +.LP +The \fBpool_query_components()\fR, \fBpool_query_pools()\fR, and +\fBpool_query_resources()\fR functions return a null-terminated array of +components, pools, and resources, respectively. If the query was unsuccessful +or there were no matches, \fINULL\fR is returned and \fBpool_error()\fR returns +the pool-specific error value. +.SH ERRORS +.sp +.LP +The \fBpool_get_pool()\fR will fail if: +.sp +.ne 2 +.na +\fB\fBPOE_BADPARAM\fR\fR +.ad +.RS 16n +The supplied configuration's status is not \fBPOF_VALID\fR. +.RE + +.sp +.LP +The \fBpool_get_resource()\fR will fail if: +.sp +.ne 2 +.na +\fB\fBPOE_BADPARAM\fR\fR +.ad +.RS 16n +The supplied configuration's status is not \fBPOF_VALID\fR. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_SYSTEM\fR\fR +.ad +.RS 16n +There is not enough memory available to allocate working buffers. Check +\fBerrno\fR for the specific system error code. +.RE + +.sp +.LP +The \fBpool_query_components()\fR, \fBpool_query_pools()\fR, and +\fBpool_query_resources()\fR will fail if: +.sp +.ne 2 +.na +\fB\fBPOE_BADPARAM\fR\fR +.ad +.RS 20n +The supplied configuration's status is not \fBPOF_VALID\fR. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_INVALID_CONF\fR\fR +.ad +.RS 20n +The query generated results that were not of the correct type. The +configuration is invalid. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_SYSTEM\fR\fR +.ad +.RS 20n +There is not enough memory available to allocate working buffers. Check +\fBerrno\fR for the specific system error code. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRRetrieve the pool named "foo" from a given configuration. +.sp +.in +2 +.nf +#include <pool.h> +#include <stdio.h> + +\&... + +pool_conf_t *conf; +pool_t *pool; + +\&... + +if ((pool = pool_get_pool(conf, "foo")) == NULL) { + (void) fprintf(stderr, "Cannot retrieve pool named + 'foo'\\B{}n"); + ... +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +CSI Enabled +_ +Interface Stability Unstable +_ +MT-Level Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibpool\fR(3LIB), \fBpool_error\fR(3POOL), \fBattributes\fR(5) diff --git a/usr/src/man/man3pool/pool_get_property.3pool b/usr/src/man/man3pool/pool_get_property.3pool new file mode 100644 index 0000000..410c40d --- /dev/null +++ b/usr/src/man/man3pool/pool_get_property.3pool @@ -0,0 +1,278 @@ +'\" 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 POOL_GET_PROPERTY 3POOL "Sep 23, 2003" +.SH NAME +pool_get_property, pool_put_property, pool_rm_property, pool_walk_properties \- +resource pool element property manipulation +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lpool\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <pool.h> + +\fBpool_value_class_t\fR \fBpool_get_property\fR(\fBpool_conf_t *\fR\fIconf\fR, + \fBconst pool_elem_t *\fR\fIelem\fR, \fBconst char *\fR\fIname\fR, + \fBpool_value_t *\fR\fIproperty\fR); +.fi + +.LP +.nf +\fBint\fR \fBpool_put_property\fR(\fBpool_conf_t *\fR\fIconf\fR, \fBpool_elem_t *\fR\fIelem\fR, + \fBconst char *\fR\fIname\fR, \fBconst pool_value_t *\fR\fIvalue\fR); +.fi + +.LP +.nf +\fBint\fR \fBpool_rm_property\fR(\fBpool_conf_t *\fR\fIconf\fR, \fBpool_elem_t *\fR\fIelem\fR, + \fBconst char *\fR\fIname\fR); +.fi + +.LP +.nf +\fBint\fR \fBpool_walk_properties\fR(\fBpool_conf_t *\fR\fIconf\fR, \fBpool_elem_t *\fR\fIelem\fR, + \fBvoid *\fR\fIarg\fR, \fBint (*\fR\fIcallback\fR)(\fBpool_conf_t *\fR, \fBpool_elem_t *\fR, + \fBconst char *\fR, \fBpool_value_t *\fR, \fBvoid *\fR)); +.fi + +.SH DESCRIPTION +.sp +.LP +The various pool types are converted to the common pool element type +(\fBpool_elem_t\fR) before property manipulation. A \fBpool_value_t\fR is an +opaque type that contains a property value of one of the following types: +.sp +.ne 2 +.na +\fB\fBPOC_UINT\fR\fR +.ad +.RS 14n +unsigned 64-bit integer +.RE + +.sp +.ne 2 +.na +\fB\fBPOC_INT\fR\fR +.ad +.RS 14n +signed 64-bit integer +.RE + +.sp +.ne 2 +.na +\fB\fBPOC_DOUBLE\fR\fR +.ad +.RS 14n +signed double-precision floating point value +.RE + +.sp +.ne 2 +.na +\fB\fBPOC_BOOL\fR\fR +.ad +.RS 14n +boolean value: 0 is false, non-zero is true +.RE + +.sp +.ne 2 +.na +\fB\fBPOC_STRING\fR\fR +.ad +.RS 14n +null-terminated string of characters +.RE + +.sp +.LP +The \fIconf\fR argument for each function refers to the target configuration to +which the operation applies. +.sp +.LP +The \fBpool_get_property()\fR function attempts to retrieve the value of the +named property from the element. If the property is not found or an error +occurs, the value \fBPOC_INVAL\fR is returned to indicate error. Otherwise the +type of the value retrieved is returned. +.sp +.LP +The \fBpool_put_property()\fR function attempts to set the named property on +the element to the specified value. Attempting to set a property that does not +currently exist on the element will cause the property with the given name and +value to be created on the element and will not cause an error. An attempt to +overwrite an existing property with a new property of a different type is an +error. +.sp +.LP +The \fBpool_rm_property()\fR function attempts to remove the named property +from the element. If the property does not exist or is not removable, -1 is +returned and \fBpool_error\fR(3POOL) reporst an error of \fBPOE_PUTPROP\fR. +.sp +.LP +The \fBpool_walk_properties()\fR function invokes \fIcallback\fR on all +properties defined for the given element. The \fIcallback\fR is called with the +element itself, the name of the property, the value of the property, and the +caller-provided opaque argument. +.sp +.LP +A number of special properties are reserved for internal use and cannot be set +or removed. Attempting to do so will fail. These properties are documented on +the \fBlibpool\fR(3LIB) manual page. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBpool_get_property()\fR returns the type of the +property. Otherwise it returns \fBPOC_INVAL\fR and \fBpool_error()\fR returns +the pool-specific error value. +.sp +.LP +Upon successful completion, \fBpool_put_property()\fR, +\fBpool_rm_property()\fR, and \fBpool_walk_properties()\fR return 0. Otherwise +they return \(mi1 and \fBpool_error()\fR returns the pool-specific error value. +.SH ERRORS +.sp +.LP +The \fBpool_get_property()\fR function will fail if: +.sp +.ne 2 +.na +\fB\fBPOE_BADPARAM\fR\fR +.ad +.RS 16n +The supplied configuration's status is not \fBPOF_VALID\fR, the supplied +\fIconf\fR does not contain the supplied \fIelem\fR, or the property is +restricted and cannot be accessed by the library. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_SYSTEM\fR\fR +.ad +.RS 16n +A system error has occurred. Check the system error code for more details. +.RE + +.sp +.LP +The \fBpool_put_property()\fR function will fail if: +.sp +.ne 2 +.na +\fB\fBPOE_BADPARAM\fR\fR +.ad +.RS 20n +The supplied configuration's status is not \fBPOF_VALID\fR, the supplied +\fIconf\fR does not contain the supplied \fIelem\fR, the property name is not +in the correct format, or the property already exists and the supplied type +does not match the existing type. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_SYSTEM\fR\fR +.ad +.RS 20n +A system error has occurred. Check the system error code for more details. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_PUTPROP\fR\fR +.ad +.RS 20n +The property name is reserved by \fBlibpool\fR and not available for use. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_INVALID_CONF\fR\fR +.ad +.RS 20n +The configuration is invalid. +.RE + +.sp +.LP +The \fBpool_rm_property()\fR function will fail if: +.sp +.ne 2 +.na +\fB\fBPOE_BADPARAM\fR\fR +.ad +.RS 16n +The supplied configuration's status is not \fBPOF_VALID\fR, the supplied +\fIconf\fR does not contain the supplied elem, or the property is reserved by +libpool and cannot be removed. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_SYSTEM\fR\fR +.ad +.RS 16n +A system error has occurred. Check the system error code for more details. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_PUTPROP\fR\fR +.ad +.RS 16n +The property name is reserved by \fBlibpool\fR and not available for use. +.RE + +.sp +.LP +The \fBpool_walk_properties()\fR function will fail if: +.sp +.ne 2 +.na +\fB\fBPOE_BADPARAM\fR\fR +.ad +.RS 16n +The supplied configuration's status is not \fBPOF_VALID\fR. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_SYSTEM\fR\fR +.ad +.RS 16n +A system error has occurred. Check the system error code for more details. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +CSI Enabled +_ +Interface Stability Unstable +_ +MT-Level Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibpool\fR(3LIB), \fBpool_error\fR(3POOL), \fBattributes\fR(5) diff --git a/usr/src/man/man3pool/pool_resource_create.3pool b/usr/src/man/man3pool/pool_resource_create.3pool new file mode 100644 index 0000000..62813a0 --- /dev/null +++ b/usr/src/man/man3pool/pool_resource_create.3pool @@ -0,0 +1,339 @@ +'\" 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 POOL_RESOURCE_CREATE 3POOL "Sep 23, 2003" +.SH NAME +pool_resource_create, pool_resource_destroy, pool_resource_info, +pool_query_resource_components, pool_resource_transfer, pool_resource_xtransfer +\- resource pool resource manipulation functions +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lpool\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <pool.h> + +\fBpool_resource_t *\fR\fBpool_resource_create\fR(\fBpool_conf_t *\fR\fIconf\fR, + \fBconst char *\fR\fItype\fR, \fBconst char *\fR\fIname\fR); +.fi + +.LP +.nf +\fBint\fR \fBpool_resource_destroy\fR(\fBpool_conf_t *\fR\fIconf\fR, + \fBpool_resource_t *\fR\fIresource\fR); +.fi + +.LP +.nf +\fBconst char *\fR\fBpool_resource_info\fR(\fBpool_conf_t *\fR\fIconf\fR + \fBpool_resource_t *\fR\fIresource\fR, \fBint\fR \fIflags\fR); +.fi + +.LP +.nf +\fBpool_component_t **\fR\fBpool_query_resource_components\fR( + \fBpool_conf_t *\fR\fIconf\fR, \fBpool_resource_t *\fR\fIresource\fR, + \fBuint_t *\fR\fInelem\fR, \fBpool_value_t **\fR\fIprops\fR); +.fi + +.LP +.nf +\fBint\fR \fBpool_resource_transfer\fR(\fBpool_conf_t *\fR\fIconf\fR, + \fBpool_resource_t *\fR\fIsource\fR, \fBpool_resource_t *\fR\fItarget\fR, + \fBuint64_t\fR \fIsize\fR); +.fi + +.LP +.nf +\fBint\fR \fBpool_resource_xtransfer\fR(\fBpool_conf_t *\fR\fIconf\fR, + \fBpool_resource_t *\fR\fIsource\fR, \fBpool_resource_t *\fR\fItarget\fR, + \fBpool_component_t **\fR\fIcomponents\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpool_resource_create()\fR function creates and returns a new resource of +the given \fIname\fR and \fItype\fR in the provided configuration. If there is +already a resource of the given name, the operation will fail. +.sp +.LP +The \fBpool_resource_destroy()\fR function removes the specified \fIresource\fR +from its configuration file. +.sp +.LP +The \fBpool_resource_info()\fR function returns a string describing the given +\fIresource\fR. The string is allocated with \fBmalloc\fR(3C). The caller is +reponsible for freeing the returned string. If the \fIflags\fR argument is +non-zero, the string returned also describes the components (if any) contained +in the resource. +.sp +.LP +The \fBpool_query_resource_components()\fR function returns a null-terminated +array of the components (if any) that comprise the given resource. +.sp +.LP +The \fBpool_resource_transfer()\fR function transfers \fIsize\fR basic units +from the \fIsource\fR resource to the \fItarget\fR. Both resources must be of +the same type for the operation to succeed. Transferring component resources, +such as processors, is always performed as series of +\fBpool_resource_xtransfer()\fR operations, since discrete resources must be +identified for transfer. +.sp +.LP +The \fBpool_resource_xtransfer()\fR function transfers the specific +\fIcomponents\fR from the \fIsource\fR resource to the \fItarget\fR. Both +resources must be of the same type, and of a type that contains components +(such as processor sets). The \fIcomponents\fR argument is a null-terminated +list of \fBpool_component_t\fR. +.sp +.LP +The \fIconf\fR argument for each function refers to the target configuration to +which the operation applies. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBpool_resource_create()\fR returns a new +\fBpool_resource_t\fR with default properties initialized. Otherwise, +\fINULL\fR is returned and \fBpool_error\fR(3POOL) returns the pool-specific +error value. +.sp +.LP +Upon successful completion, \fBpool_resource_destroy()\fR returns 0. Otherwise, +-1 is returned and \fBpool_error()\fR returns the pool-specific error value. +.sp +.LP +Upon successful completion, \fBpool_resource_info()\fR returns a string +describing the given resource (and optionally its components). Otherwise, +\fINULL\fR is returned and \fBpool_error()\fR returns the pool-specific error +value. +.sp +.LP + Upon successful completion, \fBpool_query_resource_components()\fR returns a +null-terminated array of \fBpool_component_t *\fR that match the provided +null-terminated property list and are contained in the given resource. +Otherwise, \fINULL\fR is returned and \fBpool_error()\fR returns the +pool-specific error value. +.sp +.LP + Upon successful completion, \fBpool_resource_transfer()\fR and +\fBpool_resource_xtransfer()\fR return 0. Otherwise -1 is returned and +\fBpool_error()\fR returns the pool-specific error value. +.SH ERRORS +.sp +.LP +The \fBpool_resource_create()\fR function will fail if: +.sp +.ne 2 +.na +\fB\fBPOE_BADPARAM\fR\fR +.ad +.RS 20n +The supplied configuration's status is not \fBPOF_VALID\fR or \fIname\fR is in +use for this resource type. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_INVALID_CONF\fR\fR +.ad +.RS 20n +The resource element could not be created because the configuration would be +invalid. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_PUTPROP\fR\fR +.ad +.RS 20n +One of the supplied properties could not be set. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_SYSTEM\fR\fR +.ad +.RS 20n + A system error has occurred. Check the system error code for more details. +.RE + +.sp +.LP +The \fBpool_resource_destroy()\fR function will fail if: +.sp +.ne 2 +.na +\fB\fBPOE_BADPARAM\fR\fR +.ad +.RS 16n +The supplied configuration's status is not \fBPOF_VALID\fR. +.RE + +.sp +.LP +The \fBpool_resource_info()\fR function will fail if: +.sp +.ne 2 +.na +\fB\fBPOE_BADPARAM\fR\fR +.ad +.RS 20n +The supplied configuration's status is not \fBPOF_VALID\fR or the \fIflags\fR +paramter is neither 0 nor 1. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_INVALID_CONF\fR\fR +.ad +.RS 20n +The configuration is invalid. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_SYSTEM\fR\fR +.ad +.RS 20n +A system error has occurred. Check the system error code for more details. +.RE + +.sp +.LP +The \fBpool_query_resource_components()\fR function will fail if: +.sp +.ne 2 +.na +\fB\fBPOE_BADPARAM\fR\fR +.ad +.RS 20n +The supplied configuration's status is not \fBPOF_VALID\fR. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_INVALID_CONF\fR\fR +.ad +.RS 20n +The configuration is invalid. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_SYSTEM\fR\fR +.ad +.RS 20n +A system error has occurred. Check the system error code for more details. +.RE + +.sp +.LP +The \fBpool_resource_transfer()\fR function will fail if: +.sp +.ne 2 +.na +\fB\fBPOE_BADPARAM\fR\fR +.ad +.RS 16n +The supplied configuration's status is not \fBPOF_VALID\fR, the two resources +are not of the same type, or the transfer would cause either of the resources +to exceed their \fBmin\fR and \fBmax\fR properties. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_SYSTEM\fR\fR +.ad +.RS 16n +A system error has occurred. Check the system error code for more details. +.RE + +.sp +.LP +The \fBpool_resource_xtransfer()\fR function will fail if: +.sp +.ne 2 +.na +\fB\fBPOE_BADPARAM\fR\fR +.ad +.RS 20n +The supplied configuration's status is not \fBPOF_VALID\fR, the two resources +are not of the same type, or the supplied resources do not belong to the +source. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_INVALID_CONF\fR\fR +.ad +.RS 20n +The transfer operation failed and the configuration may be invalid. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_SYSTEM\fR\fR +.ad +.RS 20n +A system error has occurred. Check the system error code for more details. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRCreate a new resource of type \fBpset\fR named \fBfoo\fR. +.sp +.in +2 +.nf +#include <pool.h> +#include <stdio.h> + +\&... + +pool_conf_t *conf; +pool_resource_t *resource; +\&... + +if ((resource = pool_resource_create(conf, "pset", + "foo")) == NULL) { + (void) fprintf(stderr, "Cannot create resource\\B{}n"); + ... +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +CSI Enabled +_ +Interface Stability Unstable +_ +MT-Level Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibpool\fR(3LIB), \fBpool_error\fR(3POOL), \fBattributes\fR(5) diff --git a/usr/src/man/man3pool/pool_value_alloc.3pool b/usr/src/man/man3pool/pool_value_alloc.3pool new file mode 100644 index 0000000..8fba812 --- /dev/null +++ b/usr/src/man/man3pool/pool_value_alloc.3pool @@ -0,0 +1,244 @@ +'\" 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 POOL_VALUE_ALLOC 3POOL "Sep 23, 2003" +.SH NAME +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 \- resource pool property value +manipulation functions +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lpool\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <pool.h> + +\fBpool_value_t *\fR\fBpool_value_alloc\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBpool_value_free\fR(\fBpool_value_t *\fR\fIvalue\fR); +.fi + +.LP +.nf +\fBpool_value_class_t\fR \fBpool_value_get_type\fR( + \fBconst pool_value_t *\fR\fIvalue\fR); +.fi + +.LP +.nf +\fBint\fR \fBpool_value_get_bool\fR(\fBconst pool_value_t *\fR\fIvalue\fR, + \fBuchar_t *\fR\fIbool\fR); +.fi + +.LP +.nf +\fBint\fR \fBpool_value_get_double\fR(\fBconst pool_value_t *\fR\fIvalue\fR, + \fBdouble *\fR\fId\fR); +.fi + +.LP +.nf +\fBint\fR \fBpool_value_get_int64\fR(\fBconst pool_value_t *\fR\fIvalue\fR, + \fBint64_t *\fR\fIi64\fR); +.fi + +.LP +.nf +\fBint\fR \fBpool_value_get_string\fR(\fBconst pool_value_t *\fR\fIvalue\fR, + \fBconst char **\fR\fIstrp\fR); +.fi + +.LP +.nf +\fBint\fR \fBpool_value_get_uint64\fR(\fBconst pool_value_t *\fR\fIvalue\fR, + \fBuint64_t *\fR\fIui64\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBpool_value_set_bool\fR(\fBconst pool_value_t *\fR\fIvalue\fR, + \fBuchar_t\fR \fIbool\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBpool_value_set_double\fR(\fBconst pool_value_t *\fR\fIvalue\fR, + \fBdouble\fR \fId\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBpool_value_set_int64\fR(\fBconst pool_value_t *\fR\fIvalue\fR, + \fBint64_t\fR \fIi64\fR); +.fi + +.LP +.nf +\fBint\fR \fBpool_value_set_string\fR(\fBconst pool_value_t *\fR\fIvalue\fR, + \fBconst char *\fR\fIstrp\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBpool_value_set_uint64\fR(\fBconst pool_value_t *\fR\fIvalue\fR, + \fBuint64_t\fR \fIui64\fR); +.fi + +.LP +.nf +\fBconst char *\fR\fBpool_value_get_name\fR(\fBconst pool_value_t *\fR\fIvalue\fR); +.fi + +.LP +.nf +\fBint\fR \fBpool_value_set_name\fR(\fBconst pool_value_t *\fR\fIvalue\fR, + \fBconst char *\fR\fIname\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +A \fBpool_value_t\fR is an opaque type representing the typed value portion of +a pool property. For a list of the types supported by a \fBpool_value_t\fR, see +\fBpool_get_property\fR(3POOL). +.sp +.LP +The \fBpool_value_alloc()\fR function allocates and returns an opaque container +for a pool property value. The \fBpool_value_free()\fR function must be called +explicitly for allocated property values. +.sp +.LP +The \fBpool_value_get_bool()\fR, \fBpool_value_get_double()\fR, +\fBpool_value_get_int64()\fR, \fBpool_value_get_string()\fR, and +\fBpool_value_get_uint64()\fR functions retrieve the value contained in the +\fBpool_value_t\fR pointed to by \fIvalue\fR to the location pointed to by the +second argument. If the type of the value does not match that expected by the +function, an error value is returned. The string retrieved by +\fBpool_value_get_string()\fR is freed by the library when the value is +overwritten or \fBpool_value_free()\fR is called on the pool property value. +.sp +.LP +The \fBpool_value_get_type()\fR function returns the type of the data contained +by a \fBpool_value_t\fR. If the value is unused then a type of \fBPOC_INVAL\fR +is returned. +.sp +.LP +The \fBpool_value_set_bool()\fR, \fBpool_value_set_double()\fR, +\fBpool_value_set_int64()\fR, \fBpool_value_set_string()\fR, and +\fBpool_value_set_uint64()\fR functions set the value and type of the property +value to the provided values. The \fBpool_value_set_string()\fR function copies +the string passed in and returns -1 if the memory allocation fails. +.sp +.LP +Property values can optionally have names. These names are used to describe +properties as name=value pairs in the various query functions (see +\fBpool_query_resources\fR(3POOL)). A copy of the string passed to +\fBpool_value_set_name()\fR is made by the library, and the value returned by +\fBpool_value_get_name()\fR is freed when the \fBpool_value_t\fR is deallocated +or overwritten. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBpool_value_alloc()\fR returns a pool property +value with type initialized to \fBPVC_INVAL\fR. Otherwise, \fINULL\fR is +returned and \fBpool_error()\fR returns the pool-specific error value. +.sp +.LP +Upon successful completion, \fBpool_value_get_type()\fR returns the type +contained in the property value passed in as an argument. Otherwise, +\fBPOC_INVAL\fR is returned and \fBpool_error()\fR returns the pool-specific +error value. +.sp +.LP +Upon successful completion, \fBpool_value_get_bool()\fR, +\fBpool_value_get_double()\fR, \fBpool_value_get_int64()\fR, +\fBpool_value_get_string()\fR, and \fBpool_value_get_uint64()\fR return 0. +Otherwise -1 is returned and \fBpool_error\fR(3POOL) returns the pool-specific +error value. +.sp +.LP +Upon successful completion, \fBpool_value_set_string()\fR and +\fBpool_value_set_name()\fR return 0. If the memory allocation failed, -1 is +returned and \fBpool_error()\fR returns the pool-specific error value. +.SH ERRORS +.sp +.LP +The \fBpool_value_alloc()\fR function will fail if: +.sp +.ne 2 +.na +\fB\fBPOE_SYSTEM\fR\fR +.ad +.RS 14n +A system error has occurred. Check the system error code for more details. +.RE + +.sp +.LP +The \fBpool_value_get_bool()\fR, \fBpool_value_get_double()\fR, +\fBpool_value_get_int64()\fR, \fBpool_value_get_string()\fR, and +\fBpool_value_get_uint64()\fR functions will fail if: +.sp +.ne 2 +.na +\fB\fBPOE_BADPARAM\fR\fR +.ad +.RS 16n +The supplied \fIvalue\fR does not match the type of the requested operation. +.RE + +.sp +.LP +The \fBpool_value_set_string()\fR function will fail if: +.sp +.ne 2 +.na +\fB\fBPOE_SYSTEM\fR\fR +.ad +.RS 14n +A system error has occurred. Check the system error code for more details. +.RE + +.sp +.LP +The \fBpool_value_set_name()\fR function will fail if: +.sp +.ne 2 +.na +\fB\fBPOE_SYSTEM\fR\fR +.ad +.RS 14n +A system error has occurred. Check the system error code for more details. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +CSI Enabled +_ +Interface Stability Unstable +_ +MT-Level Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibpool\fR(3LIB), \fBpool_error\fR(3POOL), \fBattributes\fR(5) diff --git a/usr/src/man/man3pool/pool_walk_components.3pool b/usr/src/man/man3pool/pool_walk_components.3pool new file mode 100644 index 0000000..27d8387 --- /dev/null +++ b/usr/src/man/man3pool/pool_walk_components.3pool @@ -0,0 +1,115 @@ +'\" te +.\" Copyright (c) 2005, 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 POOL_WALK_COMPONENTS 3POOL "Jul 18, 2005" +.SH NAME +pool_walk_components, pool_walk_pools, pool_walk_resources \- walk objects +within resource pool configurations +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lpool\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <pool.h> + +\fBint\fR \fBpool_walk_components\fR(\fBpool_conf_t *\fR\fIconf\fR, + \fBpool_resource_t *\fR\fIresource\fR, \fBvoid *\fR\fIarg\fR, + \fBint (*\fR\fIcallback\fR)(\fBpool_conf_t *\fR, \fBpool_resource_t *\fR, \fBvoid *\fR)); +.fi + +.LP +.nf +\fBint\fR \fBpool_walk_pools\fR(\fBpool_conf_t *\fR\fIconf\fR, \fBvoid *\fR\fIarg\fR, + \fBint (*\fR\fIcallback\fR)(\fBpool_conf_t *\fR, \fBpool_component_t *\fR, \fBvoid *\fR)); +.fi + +.LP +.nf +\fBint\fR \fBpool_walk_resources\fR(\fBpool_conf_t *\fR\fIconf\fR, \fBpool_t *\fR\fIpool\fR, + \fBvoid *\fR\fIarg\fR, \fBint (*\fR\fIcallback\fR)(\fBpool_conf_t *\fR, + \fBpool_component_t *\fR, \fBvoid *\fR)); +.fi + +.SH DESCRIPTION +.sp +.LP +The walker functions provided with \fBlibpool\fR(3LIB) visit each associated +entity of the given type, and call the caller-provided \fIcallback\fR function +with a user-provided additional opaque argument. There is no implied order of +visiting nodes in the walk. If the \fIcallback\fR function returns a non-zero +value at any of the nodes, the walk is terminated, and an error value of -1 +returned. The \fIconf\fR argument for each function refers to the target +configuration to which the operation applies. +.sp +.LP +The \fBpool_walk_components()\fR function invokes \fIcallback\fR on all +components contained in the resource. +.sp +.LP +The \fBpool_walk_pools()\fR function invokes \fIcallback\fR on all pools +defined in the configuration. +.sp +.LP +The \fBpool_walk_resources()\fR function invokes \fIcallback\fR function on all +resources associated with \fIpool\fR. +.SH RETURN VALUES +.sp +.LP +Upon successful completion of the walk, these functions return 0. Otherwise -1 +is returned and \fBpool_error\fR(3POOL) returns the pool-specific error value. +.SH ERRORS +.sp +.LP +These functions will fail if: +.sp +.ne 2 +.na +\fB\fBPOE_BADPARAM\fR\fR +.ad +.RS 20n +The supplied configuration's status is not \fBPOF_VALID\fR. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_INVALID_CONF\fR\fR +.ad +.RS 20n +The configuration is invalid. +.RE + +.sp +.ne 2 +.na +\fB\fBPOE_SYSTEM\fR\fR +.ad +.RS 20n +A system error has occurred. Check the system error code for more details. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +CSI Enabled +_ +Interface Stability Unstable +_ +MT-Level Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibpool\fR(3LIB), \fBpool_error\fR(3POOL), \fBattributes\fR(5) |