Description

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 pool_conf_alloc() and released with pool_conf_free() 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 pool_conf_close() function closes the given configuration, releasing associated resources.

The pool_conf_commit() function commits changes made to the given pool_conf_t 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 pool_conf_t. If
configuring the system fails, pool_conf_commit() will attempt to restore the system to
its previous state.

The pool_conf_export() function saves the given configuration to the specified location. The
only currently supported value of format is POX_NATIVE, which is the format
native to libpool, the output of which can be used as input to
pool_conf_open().

The pool_conf_info() function returns a string describing the entire configuration. The
string is allocated with malloc(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.

The pool_conf_location() function returns the location string provided to pool_conf_open() for the
given pool_conf_t.

The pool_conf_open() function creates a pool_conf_t given a location at which the
configuration is stored. The valid flags are a bitmap of the following:

PO_RDONLY

Open for reading only.

PO_RDWR

Open read-write.

PO_CREAT

Create a configuration at the given location if it does not exist. If it does, truncate it.

PO_DISCO

Perform `discovery'. This option only makes sense when used in conjunction with PO_CREAT, and causes the returned pool_conf_t to contain the resources and components currently active on the system.

The use of this flag is deprecated. PO_CREAT always performs discovery. If supplied, this flag is ignored.

PO_UPDATE

Use when opening the dynamic state file, which is the configuration at pool_dynamic_location(3POOL), 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 pool_conf_open() with the pool dynamic location and write permission
will hang if the dynamic location has already been opened for writing.

The pool_conf_remove() function removes the configuration's permanent storage. If the configuration is
still open, it is first closed.

The pool_conf_rollback() function restores the configuration state to that held in the
configuration's permanent storage. This will either be the state last successfully committed
(using pool_conf_commit()) or the state when the configuration was opened if there have
been no successfully committed changes since then.

The pool_conf_status() function returns the status of a configuration, which can be
one of the following values:

POF_INVALID

The configuration is not in a suitable state for use.

POF_VALID

The configuration is in a suitable state for use.

The pool_conf_update() function updates the library snapshot of kernel state. If changed
is non-null, it is updated to identify which types of configuration elements
changed during 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:

POU_SYSTEM

A property on the system element has been created, modified, or removed.

POU_POOL

A property on a pool element has been created, modified, or removed. A pool has changed a resource association.

POU_PSET

A property on a pset element has been created, modified, or removed. A pset's resource composition has changed.

POU_CPU

A property on a CPU element has been created, modified, or removed.

The pool_conf_validate() function checks the validity of the contents of the given
configuration. The validation can be at several (increasing) levels of strictness:

POV_LOOSE

Performs basic internal syntax validation.

POV_STRICT

Performs a more thorough syntax validation and internal consistency checks.

POV_RUNTIME

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.