path: root/usr/src/man/man3pool/pool_conf_alloc.3pool

'\" 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)