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 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 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.

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 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_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.

Upon successful completion, pool_conf_alloc() returns an initialized pool_conf_t pointer. Otherwise it returns NULL and pool_error(3POOL) returns the pool-specific error value.

Upon successful completion, pool_conf_close(), pool_conf_commit(), pool_conf_export(), pool_conf_open(), pool_conf_remove(), pool_conf_rollback(), and pool_conf_validate() return 0. Otherwise they return -1 and pool_error() returns the pool-specific error value.

The pool_conf_status() function returns either POF_INVALID or POF_VALID.

The pool_conf_alloc() function will fail if:

POE_SYSTEM

There is not enough memory available to allocate the configuration. Check errno for the specific system error code.

POE_INVALID_CONF

The configuration is invalid.

The pool_conf_close() function will fail if:

POE_BADPARAM

The supplied configuration's status is not POF_VALID.

POE_SYSTEM

The configuration's permanent store cannot be closed. Check errno for the specific system error code.

The pool_conf_commit() function will fail if:

POE_BADPARAM

The supplied configuration's status is not POF_VALID or the active flag is non-zero and the system could not be modified.

POE_SYSTEM

The permanent store could not be updated. Check errno for the specific system error code.

POE_INVALID_CONF

The configuration is not valid for this system.

POE_NOTSUP

The configuration was not opened for update.

POE_DATASTORE

The update of the permanent store has failed and the contents could be corrupted. Check for a .bak file at the datastore location if manual recovery is required.

The pool_conf_export() function will fail if:

POE_BADPARAM

The supplied configuration's status is not POF_VALID or the requested export format is not supported.

POE_DATASTORE

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.

The pool_conf_info() function will fail if:

POE_BADPARAM

The supplied configuration's status is not POF_VALID or flags is neither 0 nor 1.

POE_SYSTEM

There is not enough memory available to allocate the buffer used to build the information string. Check errno for the specific system error code.

POE_INVALID_CONF

The configuration is invalid.

The pool_conf_location() function will fail if:

POE_BADPARAM

The supplied configuration's status is not POF_VALID.

The pool_conf_open() function will fail if:

POE_BADPARAM

The supplied configuration's status is already POF_VALID.

POE_SYSTEM

There is not enough memory available to store the supplied location. Check errno for the specific system error code.

POE_INVALID_CONF

The configuration to be opened is at pool_dynamic_location(3POOL) and the configuration is not valid for this system.

The pool_conf_remove() function will fail if:

POE_BADPARAM

The supplied configuration's status is not POF_VALID.

POE_SYSTEM

The configuration's permanent storage could not be removed. Check errno for the specific system error code.

The pool_conf_rollback() function will fail if:

POE_BADPARAM

The supplied configuration's status is not POF_VALID.

POE_SYSTEM

The permanent store could not be accessed. Check errno for the specific system error code.

The pool_conf_validate() function will fail if:

POE_BADPARAM

The supplied configuration's status is not POF_VALID.

POE_INVALID_CONF

The configuration is invalid.

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

libpool(3LIB), pool_error(3POOL), attributes(5)