Sun Microsystems, Inc.
spacerspacer
spacer   www.sun.com docs.sun.com | | |  
spacer
black dot
   
A   B   C   D   E   F   G   H   I   J   K   L   M   N   O   P   Q   R   S   T   U   V   W   X   Y   Z
    
 
Pool Configuration Manipulation Library Functionspool_conf_alloc(3POOL)


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_validate - manipulate resource pool configurations

SYNOPSIS

 
cc [ flag... ] file... -lpool [ library ... ] 
#include <pool.h>
pool_conf_t *pool_conf_alloc(void);
 int pool_conf_close(pool_conf_t *conf);
 int pool_conf_commit(pool_conf_t *conf, int active);
 int pool_conf_export(pool_conf_t *conf, const char *location, pool_export_format_t format);
 void pool_conf_free(pool_conf_t *conf);
 char *pool_conf_info(const pool_conf_t *conf, int flags);
 const char *pool_conf_location(pool_conf_t *conf);
 int pool_conf_open(pool_conf_t *conf, const char *location, int flags);
 int pool_conf_remove(pool_conf_t *conf);
 int pool_conf_rollback(pool_conf_t *conf);
 pool_conf_state_t pool_conf_status(const pool_conf_t *conf);
 int pool_conf_validate(pool_conf_t *conf, pool_valid_level_t level);

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

RETURN VALUES

 

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.

ERRORS

 

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.

EXAMPLES

 Example 1. Create the configuration at the specified location.
 
 
#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, `Config make from %s failed\B{}n', input_location);
}

ATTRIBUTES

 

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

ATTRIBUTE TYPEATTRIBUTE VALUE
CSIEnabled
Interface StabilityUnstable
MT-LevelUnsafe

SEE ALSO

 

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


SunOS 5.9Go To TopLast Changed 20 Dec 2001

 
      
      
Copyright 2002 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.