share/man/man3pool/pool_dynamic_location.3pool

   1 '\" te
   2 .\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH POOL_DYNAMIC_LOCATION 3POOL "Sep 23, 2003"
   7 .SH NAME
   8 pool_dynamic_location, pool_static_location, pool_version, pool_get_status,
   9 pool_set_status, pool_resource_type_list \- resource pool framework functions
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lpool\fR [ \fIlibrary\fR\&.\|.\|. ]
  14 #include <pool.h>
  15
  16 \fBconst char *\fR\fBpool_dynamic_location\fR(\fBvoid\fR);
  17 .fi
  18
  19 .LP
  20 .nf
  21 \fBconst char *\fR\fBpool_static_location\fR(\fBvoid\fR);
  22 .fi
  23
  24 .LP
  25 .nf
  26 \fBuint_t\fR \fBpool_version\fR(\fBuint_t\fR \fIver\fR);
  27 .fi
  28
  29 .LP
  30 .nf
  31 \fBint\fR \fBpool_get_status\fR(\fBint *\fR\fIstate\fR);
  32 .fi
  33
  34 .LP
  35 .nf
  36 \fBint\fR \fBpool_set_status\fR(\fBint\fR \fIstate\fR);
  37 .fi
  38
  39 .LP
  40 .nf
  41 \fBint\fR \fBpool_resource_type_list\fR(\fBconst char **\fR\fIreslist\fR,
  42      \fBuint_t *\fR\fInumres\fR);
  43 .fi
  44
  45 .SH DESCRIPTION
  46 .sp
  47 .LP
  48 The \fBpool_dynamic_location()\fR function returns the location used by the
  49 pools framework to store the dynamic configuration.
  50 .sp
  51 .LP
  52 The \fBpool_static_location()\fR function returns the location used by the
  53 pools framework to store the default configuration used for pools framework
  54 instantiation.
  55 .sp
  56 .LP
  57 The \fBpool_version()\fR function can be used to inquire about the version
  58 number of the library by specifying \fBPOOL_VER_NONE\fR. The current (most
  59 capable) version is \fBPOOL_VER_CURRENT\fR. The user can set the version used
  60 by the library by specifying the required version number. If this is not
  61 possible, the version returned will be \fBPOOL_VER_NONE\fR.
  62 .sp
  63 .LP
  64 The \fBpool_get_status()\fR function retrieves the current state of the pools
  65 facility. If state is non-null, then on successful completion the state of the
  66 pools facility is stored in the location pointed to by state.
  67 .sp
  68 .LP
  69 The \fBpool_set_status()\fR function modifies the current state of the pools
  70 facility. On successful completion the state of the pools facility is changed
  71 to match the value supplied in state. Only two values are valid for state,
  72 \fBPOOL_DISABLED\fR and \fBPOOL_ENABLED\fR, both of which are defined in
  73 <\fBpool.h\fR>.
  74 .sp
  75 .LP
  76 The \fBpool_resource_type_list()\fR function enumerates the resource types
  77 supported by the pools framework on this platform. If \fInumres\fR and
  78 \fIreslist\fR are both non-null, \fIreslist\fR points to a buffer where a list
  79 of resource types in the system is to be stored, and \fInumres\fR points to the
  80 maximum number of resource types the buffer can hold. On successful completion,
  81 the list of resource types up to the maximum buffer size is stored in the
  82 buffer pointed to by \fIreslist\fR.
  83 .SH RETURN VALUES
  84 .sp
  85 .LP
  86 The \fBpool_dynamic_location()\fR function returns the location used by the
  87 pools framework to store the dynamic configuration.
  88 .sp
  89 .LP
  90 The \fBpool_static_location()\fR function returns the location used by the
  91 pools framework to store the default configuration used for pools framework
  92 instantiation.
  93 .sp
  94 .LP
  95 The \fBpool_version()\fR function returns the version number of the library or
  96 \fBPOOL_VER_NONE\fR.
  97 .sp
  98 .LP
  99 Upon successful completion, \fBpool_get_status()\fR, \fBpool_set_status()\fR,
 100 and \fBpool_resource_type_list()\fR all return 0. Otherwise, \(mi1 is returned
 101 and \fBpool_error\fR(3POOL) returns the pool specific error.
 102 .SH ERRORS
 103 .sp
 104 .LP
 105 No errors are defined for \fBpool_dynamic_location()\fR,
 106 \fBpool_static_location()\fR, and \fBpool_version()\fR.
 107 .sp
 108 .LP
 109 The \fBpool_get_status()\fR function will fail if:
 110 .sp
 111 .ne 2
 112 .na
 113 \fB\fBPOE_SYSTEM\fR\fR
 114 .ad
 115 .RS 14n
 116 A system error occurred when accessing the kernel pool state.
 117 .RE
 118
 119 .sp
 120 .LP
 121 The \fBpool_set_status()\fR function will fail if:
 122 .sp
 123 .ne 2
 124 .na
 125 \fB\fBPOE_SYSTEM\fR\fR
 126 .ad
 127 .RS 14n
 128 A system error occurred when modifying the kernel pool state.
 129 .RE
 130
 131 .sp
 132 .LP
 133 The \fBpool_resource_type_list()\fR function will fail if:
 134 .sp
 135 .ne 2
 136 .na
 137 \fB\fBPOE_BADPARAM\fR\fR
 138 .ad
 139 .RS 16n
 140 The \fInumres\fR parameter was \fINULL\fR.
 141 .RE
 142
 143 .SH EXAMPLES
 144 .LP
 145 \fBExample 1 \fRGet the static location used by the pools framework.
 146 .sp
 147 .in +2
 148 .nf
 149 #include sys/types.h>
 150 #include <unistd.h>
 151 #include <pool.h>
 152
 153 \&...
 154
 155 const char *location = pool_dynamic_location();
 156
 157 \&...
 158
 159     (void) fprintf(stderr, "pool dynamic location is %s\en",
 160            location);
 161 .fi
 162 .in -2
 163
 164 .LP
 165 \fBExample 2 \fREnable the pools facility.
 166 .sp
 167 .in +2
 168 .nf
 169 #include <stdio.h>
 170 #include <pool.h>
 171
 172 \&...
 173
 174    if (pool_set_status(POOL_ENABLED) != 0) {
 175       (void) fprintf(stderr, "pools could not be enabled %s\en",
 176              pool_strerror(pool_error()));
 177              exit(2);
 178    }
 179 \&...
 180 .fi
 181 .in -2
 182
 183 .SH ATTRIBUTES
 184 .sp
 185 .LP
 186 See \fBattributes\fR(5) for descriptions of the following attributes:
 187 .sp
 188
 189 .sp
 190 .TS
 191 box;
 192 c | c
 193 l | l .
 194 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 195 _
 196 CSI     Enabled
 197 _
 198 Interface Stability     Unstable
 199 _
 200 MT-Level        Safe
 201 .TE
 202
 203 .SH SEE ALSO
 204 .sp
 205 .LP
 206 \fBlibpool\fR(3LIB), \fBpool_error\fR(3POOL), \fBattributes\fR(5)