'\" te
.\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved.
.TH pool_dynamic_location 3POOL "23 Sep 2003" "SunOS 5.11" "Pool Configuration Manipulation Library Functions"
.SH NAME
pool_dynamic_location, pool_static_location, pool_version, pool_get_status, pool_set_status, pool_resource_type_list \- resource pool framework functions
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lpool\fR [ \fIlibrary\fR\&.\|.\|. ] 
#include <pool.h>

\fBconst char *\fR\fBpool_dynamic_location\fR(\fBvoid\fR);
.fi

.LP
.nf
\fBconst char *\fR\fBpool_static_location\fR(\fBvoid\fR);
.fi

.LP
.nf
\fBuint_t\fR \fBpool_version\fR(\fBuint_t\fR \fIver\fR);
.fi

.LP
.nf
\fBint\fR \fBpool_get_status\fR(\fBint *\fR\fIstate\fR);
.fi

.LP
.nf
\fBint\fR \fBpool_set_status\fR(\fBint\fR \fIstate\fR);
.fi

.LP
.nf
\fBint\fR \fBpool_resource_type_list\fR(\fBconst char **\fR\fIreslist\fR,
     \fBuint_t *\fR\fInumres\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBpool_dynamic_location()\fR function returns the location used by the pools framework to store the dynamic configuration.
.sp
.LP
The \fBpool_static_location()\fR function returns the location used by the pools framework to store the default configuration used for pools framework instantiation.
.sp
.LP
The \fBpool_version()\fR function can be used to inquire about the version number of the library by specifying \fBPOOL_VER_NONE\fR. The current (most capable) version is \fBPOOL_VER_CURRENT\fR. The user can set the version used by the library by specifying the required version number. If this is not possible, the version returned will be \fBPOOL_VER_NONE\fR.
.sp
.LP
The \fBpool_get_status()\fR function retrieves the current state of the pools facility. If state is non-null, then on successful completion the state of the pools facility is stored in the location pointed to by state.
.sp
.LP
The \fBpool_set_status()\fR function modifies the current state of the pools facility. On successful completion the state of the pools facility is changed to match the value supplied in state. Only two values are valid for state, \fBPOOL_DISABLED\fR and \fBPOOL_ENABLED\fR, both of which are defined in <\fBpool.h\fR>.
.sp
.LP
The \fBpool_resource_type_list()\fR function enumerates the resource types supported by the pools framework on this platform. If \fInumres\fR and \fIreslist\fR are both non-null, \fIreslist\fR points to a buffer where a list of resource types in the system is to be stored, and \fInumres\fR points to the maximum number of resource types the buffer can hold. On successful completion, the list of resource types up to the maximum buffer size is stored in the buffer pointed to by \fIreslist\fR.
.SH RETURN VALUES
.sp
.LP
The \fBpool_dynamic_location()\fR function returns the location used by the pools framework to store the dynamic configuration.
.sp
.LP
The \fBpool_static_location()\fR function returns the location used by the pools framework to store the default configuration used for pools framework instantiation.
.sp
.LP
The \fBpool_version()\fR function returns the version number of the library or \fBPOOL_VER_NONE\fR.
.sp
.LP
Upon successful completion, \fBpool_get_status()\fR, \fBpool_set_status()\fR, and \fBpool_resource_type_list()\fR all return 0. Otherwise, \(mi1 is returned and \fBpool_error\fR(3POOL) returns the pool specific error.
.SH ERRORS
.sp
.LP
No errors are defined for \fBpool_dynamic_location()\fR, \fBpool_static_location()\fR, and \fBpool_version()\fR.
.sp
.LP
The \fBpool_get_status()\fR function will fail if:
.sp
.ne 2
.mk
.na
\fB\fBPOE_SYSTEM\fR\fR
.ad
.RS 14n
.rt  
A system error occurred when accessing the kernel pool state.
.RE

.sp
.LP
The \fBpool_set_status()\fR function will fail if:
.sp
.ne 2
.mk
.na
\fB\fBPOE_SYSTEM\fR\fR
.ad
.RS 14n
.rt  
A system error occurred when modifying the kernel pool state.
.RE

.sp
.LP
The \fBpool_resource_type_list()\fR function will fail if:
.sp
.ne 2
.mk
.na
\fB\fBPOE_BADPARAM\fR\fR
.ad
.RS 16n
.rt  
The \fInumres\fR parameter was \fINULL\fR.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRGet the static location used by the pools framework.
.sp
.in +2
.nf
#include sys/types.h>
#include <unistd.h>
#include <pool.h>
 
\&...
 
const char *location = pool_dynamic_location();
 
\&...
 
    (void) fprintf(stderr, "pool dynamic location is %s\en", 
           location);           
.fi
.in -2

.LP
\fBExample 2 \fREnable the pools facility.
.sp
.in +2
.nf
#include <stdio.h>
#include <pool.h>
 
\&...
 
   if (pool_set_status(POOL_ENABLED) != 0) {
      (void) fprintf(stderr, "pools could not be enabled %s\en",
             pool_strerror(pool_error()));
             exit(2);
   }
\&...
.fi
.in -2

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
CSIEnabled
_
Interface StabilityUncommitted
_
MT-LevelSafe
.TE

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