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

'\" te
.\" Copyright (c) 2003, 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_RESOURCE_CREATE 3POOL "Sep 23, 2003"
.SH NAME
pool_resource_create, pool_resource_destroy, pool_resource_info,
pool_query_resource_components, pool_resource_transfer, pool_resource_xtransfer
\- resource pool resource manipulation functions
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lpool\fR [ \fIlibrary\fR\&.\|.\|. ]
#include <pool.h>

\fBpool_resource_t *\fR\fBpool_resource_create\fR(\fBpool_conf_t *\fR\fIconf\fR,
     \fBconst char *\fR\fItype\fR, \fBconst char *\fR\fIname\fR);
.fi

.LP
.nf
\fBint\fR \fBpool_resource_destroy\fR(\fBpool_conf_t *\fR\fIconf\fR,
     \fBpool_resource_t *\fR\fIresource\fR);
.fi

.LP
.nf
\fBconst char *\fR\fBpool_resource_info\fR(\fBpool_conf_t *\fR\fIconf\fR
     \fBpool_resource_t *\fR\fIresource\fR, \fBint\fR \fIflags\fR);
.fi

.LP
.nf
\fBpool_component_t **\fR\fBpool_query_resource_components\fR(
     \fBpool_conf_t *\fR\fIconf\fR, \fBpool_resource_t *\fR\fIresource\fR,
     \fBuint_t *\fR\fInelem\fR, \fBpool_value_t **\fR\fIprops\fR);
.fi

.LP
.nf
\fBint\fR \fBpool_resource_transfer\fR(\fBpool_conf_t *\fR\fIconf\fR,
     \fBpool_resource_t *\fR\fIsource\fR, \fBpool_resource_t *\fR\fItarget\fR,
     \fBuint64_t\fR \fIsize\fR);
.fi

.LP
.nf
\fBint\fR \fBpool_resource_xtransfer\fR(\fBpool_conf_t *\fR\fIconf\fR,
     \fBpool_resource_t *\fR\fIsource\fR, \fBpool_resource_t *\fR\fItarget\fR,
     \fBpool_component_t **\fR\fIcomponents\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBpool_resource_create()\fR function creates and returns a new resource of
the given \fIname\fR and \fItype\fR in the provided configuration. If there is
already a resource of the given name, the operation will fail.
.sp
.LP
The \fBpool_resource_destroy()\fR function removes the specified \fIresource\fR
from its configuration file.
.sp
.LP
The \fBpool_resource_info()\fR function returns a string describing the given
\fIresource\fR. The string is allocated with \fBmalloc\fR(3C). The caller is
reponsible for freeing the returned string. If the \fIflags\fR argument is
non-zero, the string returned also describes the components (if any) contained
in the resource.
.sp
.LP
The \fBpool_query_resource_components()\fR function returns a null-terminated
array of the components (if any) that comprise the given resource.
.sp
.LP
The \fBpool_resource_transfer()\fR function transfers \fIsize\fR basic units
from the \fIsource\fR resource to the \fItarget\fR. Both resources must be of
the same type for the operation to succeed. Transferring component resources,
such as processors, is always performed as series of
\fBpool_resource_xtransfer()\fR operations, since discrete resources must be
identified for transfer.
.sp
.LP
The \fBpool_resource_xtransfer()\fR function transfers the specific
\fIcomponents\fR from the \fIsource\fR resource to the \fItarget\fR. Both
resources must be of the same type, and of a type that contains components
(such as processor sets). The \fIcomponents\fR argument is a null-terminated
list of \fBpool_component_t\fR.
.sp
.LP
The \fIconf\fR argument for each function refers to the target configuration to
which the operation applies.
.SH RETURN VALUES
.sp
.LP
Upon successful completion, \fBpool_resource_create()\fR returns a new
\fBpool_resource_t\fR with default properties initialized. Otherwise,
\fINULL\fR is returned and \fBpool_error\fR(3POOL) returns the pool-specific
error value.
.sp
.LP
Upon successful completion, \fBpool_resource_destroy()\fR returns 0. Otherwise,
-1 is returned and \fBpool_error()\fR returns the pool-specific error value.
.sp
.LP
Upon successful completion, \fBpool_resource_info()\fR returns a string
describing the given resource (and optionally its components). Otherwise,
\fINULL\fR is returned and \fBpool_error()\fR returns the pool-specific error
value.
.sp
.LP
 Upon successful completion, \fBpool_query_resource_components()\fR returns a
null-terminated array of \fBpool_component_t *\fR that match the provided
null-terminated property list and are contained in the given resource.
Otherwise, \fINULL\fR is returned and \fBpool_error()\fR returns the
pool-specific error value.
.sp
.LP
 Upon successful completion, \fBpool_resource_transfer()\fR and
\fBpool_resource_xtransfer()\fR return 0. Otherwise -1 is returned and
\fBpool_error()\fR returns the pool-specific error value.
.SH ERRORS
.sp
.LP
The \fBpool_resource_create()\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 \fIname\fR is in
use for this resource type.
.RE

.sp
.ne 2
.na
\fB\fBPOE_INVALID_CONF\fR\fR
.ad
.RS 20n
The resource element could not be created because the configuration would be
invalid.
.RE

.sp
.ne 2
.na
\fB\fBPOE_PUTPROP\fR\fR
.ad
.RS 20n
One of the supplied properties could not be set.
.RE

.sp
.ne 2
.na
\fB\fBPOE_SYSTEM\fR\fR
.ad
.RS 20n
 A system error has occurred. Check the system error code for more details.
.RE

.sp
.LP
The \fBpool_resource_destroy()\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_resource_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 the \fIflags\fR
paramter is neither 0 nor 1.
.RE

.sp
.ne 2
.na
\fB\fBPOE_INVALID_CONF\fR\fR
.ad
.RS 20n
The configuration is invalid.
.RE

.sp
.ne 2
.na
\fB\fBPOE_SYSTEM\fR\fR
.ad
.RS 20n
A system error has occurred. Check the system error code for more details.
.RE

.sp
.LP
The \fBpool_query_resource_components()\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

.sp
.ne 2
.na
\fB\fBPOE_SYSTEM\fR\fR
.ad
.RS 20n
A system error has occurred. Check the system error code for more details.
.RE

.sp
.LP
The \fBpool_resource_transfer()\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, the two resources
are not of the same type, or the transfer would cause either of the resources
to exceed their \fBmin\fR and \fBmax\fR properties.
.RE

.sp
.ne 2
.na
\fB\fBPOE_SYSTEM\fR\fR
.ad
.RS 16n
A system error has occurred. Check the system error code for more details.
.RE

.sp
.LP
The \fBpool_resource_xtransfer()\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, the two resources
are not of the same type, or the supplied resources do not belong to the
source.
.RE

.sp
.ne 2
.na
\fB\fBPOE_INVALID_CONF\fR\fR
.ad
.RS 20n
The transfer operation failed and the configuration may be invalid.
.RE

.sp
.ne 2
.na
\fB\fBPOE_SYSTEM\fR\fR
.ad
.RS 20n
A system error has occurred. Check the system error code for more details.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRCreate a new resource of type \fBpset\fR named \fBfoo\fR.
.sp
.in +2
.nf
#include <pool.h>
#include <stdio.h>

\&...

pool_conf_t *conf;
pool_resource_t *resource;
\&...

if ((resource = pool_resource_create(conf, "pset",
    "foo")) == NULL) {
    (void) fprintf(stderr, "Cannot create resource\\B{}n");
    ...
}
.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	Unstable
_
MT-Level	Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBlibpool\fR(3LIB), \fBpool_error\fR(3POOL), \fBattributes\fR(5)