Pool Configuration Manipulation Library Functions
poolconfalloc(3POL)
NAME
poolconfalloc, poolconfclose, poolconfcommit,
poolconfexport, poolconffree, poolconfinfo,
poolconflocation, poolconfopen, poolconfremove,
poolconfrollback, poolconfstatus, poolconfupdate,
poolconfvalidate - manipulate resource pool configurations
SYNOPSIS
cc [ flag... ] file... -lpool [ library... ]
#include
poolconft *poolconfalloc(void);
int poolconfclose(poolconft *conf);
int poolconfcommit(poolconft *conf, int active);
int poolconfexport(poolconft *conf, const char *location,
poolexportformatt format);
void poolconffree(poolconft *conf);
char *poolconfinfo(const poolconft *conf, int flags);
const char *poolconflocation(poolconft *conf);
int poolconfopen(poolconft *conf, const char *location,
int flags);
int poolconfremove(poolconft *conf);
int poolconfrollback(poolconft *conf);
poolconfstatet poolconfstatus(const poolconft *conf);
int poolconfupdate(const poolconft *conf, int *changed);
int poolconfvalidate(poolconft *conf,
poolvalidlevelt level);
SunOS 5.11 Last change: 29 Nov 2007 1
Pool Configuration Manipulation Library Functions
poolconfalloc(3POL)
DESCRIPTION
These functions enable the access and creation of configura-
tion files associated with the pools facility. Since the
pool configuration is an opaque type, an initial configura-
tion is obtained with poolconfalloc() and released with
poolconffree() when the configuration is no longer of
interest. The conf argument for each function refers to the
target configuration to which the operation applies.
The poolconfclose() function closes the given configura-
tion, releasing associated resources.
The poolconfcommit() function commits changes made to the
given poolconft to permanent storage. If the active flag
is non-zero, the state of the system will be configured to
match that described in the supplied poolconft. If confi-
guring the system fails, poolconfcommit() will attempt to
restore the system to its previous state.
The poolconfexport() function saves the given configura-
tion to the specified location. The only currently supported
value of format is POXNATIVE, which is the format native to
libpool, the output of which can be used as input to
poolconfopen().
The poolconfinfo() function returns a string describing
the entire configuration. The string is allocated with
malloc(3C). The caller is reponsible 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.
The poolconflocation() function returns the location
string provided to poolconfopen() for the given
poolconft.
The poolconfopen() function creates a poolconft given a
location at which the configuration is stored. The valid
flags are a bitmap of the following:
PORDONLY Open for reading only.
PORDWR Open read-write.
SunOS 5.11 Last change: 29 Nov 2007 2
Pool Configuration Manipulation Library Functions
poolconfalloc(3POL)
POCREAT Create a configuration at the given location if
it does not exist. If it does, truncate it.
PODISCO Perform `discovery'. This option only makes
sense when used in conjunction with POCREAT,
and causes the returned poolconft to contain
the resources and components currently active
on the system.
The use of this flag is deprecated. POCREAT
always performs discovery. If supplied, this
flag is ignored.
POUPDATE Use when opening the dynamic state file, which
is the configuration at
pooldynamiclocation(3POL), to ensure that
the contents of the dynamic state file are
updated to represent the current state of the
system.
The use of this flag is deprecated. The dynamic
state is always current and does not require
updating. If supplied, this flag is ignored.
A call to poolconfopen() with the pool dynamic location
and write permission will hang if the dynamic location has
already been opened for writing.
The poolconfremove() function removes the configuration's
permanent storage. If the configuration is still open, it is
first closed.
The poolconfrollback() function restores the configuration
state to that held in the configuration's permanent storage.
This will either be the state last successfully committed
(using poolconfcommit()) or the state when the configura-
tion was opened if there have been no successfully committed
changes since then.
The poolconfstatus() function returns the status of a con-
figuration, which can be one of the following values:
POFINVALID The configuration is not in a suitable state
for use.
SunOS 5.11 Last change: 29 Nov 2007 3
Pool Configuration Manipulation Library Functions
poolconfalloc(3POL)
POFVALID The configuration is in a suitable state for
use.
The poolconfupdate() function updates the library snapshot
of kernel state. If changed is non-null, it is updated to
identify which types of configuration elements changed dur-
ing the update. To check for change, treat the changed value
as a bitmap of possible element types.
A change is defined for the different element classes as
follows:
POUSYSTEM A property on the system element has been
created, modified, or removed.
POUPOL A property on a pool element has been created,
modified, or removed. A pool has changed a
resource association.
POUPSET A property on a pset element has been created,
modified, or removed. A pset's resource compo-
sition has changed.
POUCPU A property on a CPU element has been created,
modified, or removed.
The poolconfvalidate() function checks the validity of the
contents of the given configuration. The validation can be
at several (increasing) levels of strictness:
POVLOSE Performs basic internal syntax validation.
POVSTRICT Performs a more thorough syntax validation
and internal consistency checks.
POVRUNTIME 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 guaran-
tee a subsequent commit operation will be
successful; it is conservative in that a
SunOS 5.11 Last change: 29 Nov 2007 4
Pool Configuration Manipulation Library Functions
poolconfalloc(3POL)
failed validation indicates that a subsequent
commit operation on the current system will
always fail.
RETURN VALUES
Upon successful completion, poolconfalloc() returns an
initialized poolconft pointer. Otherwise it returns NUL
and poolerror(3POL) returns the pool-specific error value.
Upon successful completion, poolconfclose(),
poolconfcommit(), poolconfexport(), poolconfopen(),
poolconfremove(), poolconfrollback(),
poolconfupdate(), and poolconfvalidate() return 0. Oth-
erwise they return -1 and poolerror() returns the pool-
specific error value.
The poolconfstatus() function returns either POFINVALID
or POFVALID.
ERORS
The poolconfalloc() function will fail if:
POESYSTEM There is not enough memory available to
allocate the configuration. Check errno
for the specific system error code.
POEINVALIDCONF The configuration is invalid.
The poolconfclose() function will fail if:
POEBADPARAM The supplied configuration's status is not
POFVALID.
POESYSTEM The configuration's permanent store cannot
be closed. Check errno for the specific
system error code.
The poolconfcommit() function will fail if:
POEBADPARAM The supplied configuration's status is
not POFVALID or the active flag is
non-zero and the system could not be
SunOS 5.11 Last change: 29 Nov 2007 5
Pool Configuration Manipulation Library Functions
poolconfalloc(3POL)
modified.
POESYSTEM The permanent store could not be
updated. Check errno for the specific
system error code.
POEINVALIDCONF The configuration is not valid for this
system.
POEACES The configuration was not opened with
the correct permissions.
POEDATASTORE The update of the permanent store has
failed and the contents could be cor-
rupted. Check for a .bak file at the
datastore location if manual recovery is
required.
The poolconfexport() function will fail if:
POEBADPARAM The supplied configuration's status is not
POFVALID or the requested export format is
not supported.
POEDATASTORE The creation of the export file failed. A
file might have been created at the speci-
fied location but the contents of the file
might not be correct.
The poolconfinfo() function will fail if:
POEBADPARAM The supplied configuration's status is
not POFVALID or flags is neither 0 nor
1.
POESYSTEM There is not enough memory available to
allocate the buffer used to build the
information string. Check errno for the
specific system error code.
SunOS 5.11 Last change: 29 Nov 2007 6
Pool Configuration Manipulation Library Functions
poolconfalloc(3POL)
POEINVALIDCONF The configuration is invalid.
The poolconflocation() function will fail if:
POEBADPARAM The supplied configuration's status is not
POFVALID.
The poolconfopen() function will fail if:
POEBADPARAM The supplied configuration's status is
already POFVALID.
POESYSTEM There is not enough memory available to
store the supplied location. Check errno
for the specific system error code.
POEINVALIDCONF The configuration to be opened is at
pooldynamiclocation(3POL) and the
configuration is not valid for this sys-
tem.
The poolconfremove() function will fail if:
POEBADPARAM The supplied configuration's status is not
POFVALID.
POESYSTEM The configuration's permanent storage could
not be removed. Check errno for the specific
system error code.
The poolconfrollback() function will fail if:
POEBADPARAM The supplied configuration's status is not
POFVALID.
POESYSTEM The permanent store could not be accessed.
Check errno for the specific system error
code.
SunOS 5.11 Last change: 29 Nov 2007 7
Pool Configuration Manipulation Library Functions
poolconfalloc(3POL)
The poolconfupdate() function will fail if:
POEBADPARAM The supplied configuration's status is
not POFVALID or the configuration is
not the dynamic configuration.
POEDATASTORE The kernel snapshot cannot be correctly
unpacked.
POEINVALIDCONF The configuration contains uncommitted
transactions.
POESYSTEM A system error occurred during snapshot
retrieval and update.
The poolconfvalidate() function will fail if:
POEBADPARAM The supplied configuration's status is
not POFVALID.
POEINVALIDCONF The configuration is invalid.
EXAMPLES
Example 1 Create the configuration at the specified loca-
tion.
#include
#include
...
poolconft *poolconf;
poolconf = poolconfalloc();
char *inputlocation = "/tmp/poolconf.example";
if (poolconfopen(poolconf, inputlocation,
PORDONLY) < 0) {
fprintf(stderr, "Opening pool configuration %s
failed\n", inputlocation);
}
ATRIBUTES
SunOS 5.11 Last change: 29 Nov 2007 8
Pool Configuration Manipulation Library Functions
poolconfalloc(3POL)
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
CSI Enabled
Interface Stability Uncommitted
MT-Level Safe
SEE ALSO
libpool(3LIB), poolerror(3POL), attributes(5)
SunOS 5.11 Last change: 29 Nov 2007 9
Pool Configuration Manipulation Library Functions
poolconfalloc(3POL)
SunOS 5.11 Last change: 29 Nov 2007 10
|
