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_GET_PROPERTY 3POOL "Sep 23, 2003" 7 .SH NAME 8 pool_get_property, pool_put_property, pool_rm_property, pool_walk_properties \- 9 resource pool element property manipulation 10 .SH SYNOPSIS 11 .LP 12 .nf 13 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lpool\fR [ \fIlibrary\fR\&.\|.\|. ] 14 #include <pool.h> 15 16 \fBpool_value_class_t\fR \fBpool_get_property\fR(\fBpool_conf_t *\fR\fIconf\fR, 17 \fBconst pool_elem_t *\fR\fIelem\fR, \fBconst char *\fR\fIname\fR, 18 \fBpool_value_t *\fR\fIproperty\fR); 19 .fi 20 21 .LP 22 .nf 23 \fBint\fR \fBpool_put_property\fR(\fBpool_conf_t *\fR\fIconf\fR, \fBpool_elem_t *\fR\fIelem\fR, 24 \fBconst char *\fR\fIname\fR, \fBconst pool_value_t *\fR\fIvalue\fR); 25 .fi 26 27 .LP 28 .nf 29 \fBint\fR \fBpool_rm_property\fR(\fBpool_conf_t *\fR\fIconf\fR, \fBpool_elem_t *\fR\fIelem\fR, 30 \fBconst char *\fR\fIname\fR); 31 .fi 32 33 .LP 34 .nf 35 \fBint\fR \fBpool_walk_properties\fR(\fBpool_conf_t *\fR\fIconf\fR, \fBpool_elem_t *\fR\fIelem\fR, 36 \fBvoid *\fR\fIarg\fR, \fBint (*\fR\fIcallback\fR)(\fBpool_conf_t *\fR, \fBpool_elem_t *\fR, 37 \fBconst char *\fR, \fBpool_value_t *\fR, \fBvoid *\fR)); 38 .fi 39 40 .SH DESCRIPTION 41 .sp 42 .LP 43 The various pool types are converted to the common pool element type 44 (\fBpool_elem_t\fR) before property manipulation. A \fBpool_value_t\fR is an 45 opaque type that contains a property value of one of the following types: 46 .sp 47 .ne 2 48 .na 49 \fB\fBPOC_UINT\fR\fR 50 .ad 51 .RS 14n 52 unsigned 64-bit integer 53 .RE 54 55 .sp 56 .ne 2 57 .na 58 \fB\fBPOC_INT\fR\fR 59 .ad 60 .RS 14n 61 signed 64-bit integer 62 .RE 63 64 .sp 65 .ne 2 66 .na 67 \fB\fBPOC_DOUBLE\fR\fR 68 .ad 69 .RS 14n 70 signed double-precision floating point value 71 .RE 72 73 .sp 74 .ne 2 75 .na 76 \fB\fBPOC_BOOL\fR\fR 77 .ad 78 .RS 14n 79 boolean value: 0 is false, non-zero is true 80 .RE 81 82 .sp 83 .ne 2 84 .na 85 \fB\fBPOC_STRING\fR\fR 86 .ad 87 .RS 14n 88 null-terminated string of characters 89 .RE 90 91 .sp 92 .LP 93 The \fIconf\fR argument for each function refers to the target configuration to 94 which the operation applies. 95 .sp 96 .LP 97 The \fBpool_get_property()\fR function attempts to retrieve the value of the 98 named property from the element. If the property is not found or an error 99 occurs, the value \fBPOC_INVAL\fR is returned to indicate error. Otherwise the 100 type of the value retrieved is returned. 101 .sp 102 .LP 103 The \fBpool_put_property()\fR function attempts to set the named property on 104 the element to the specified value. Attempting to set a property that does not 105 currently exist on the element will cause the property with the given name and 106 value to be created on the element and will not cause an error. An attempt to 107 overwrite an existing property with a new property of a different type is an 108 error. 109 .sp 110 .LP 111 The \fBpool_rm_property()\fR function attempts to remove the named property 112 from the element. If the property does not exist or is not removable, -1 is 113 returned and \fBpool_error\fR(3POOL) reporst an error of \fBPOE_PUTPROP\fR. 114 .sp 115 .LP 116 The \fBpool_walk_properties()\fR function invokes \fIcallback\fR on all 117 properties defined for the given element. The \fIcallback\fR is called with the 118 element itself, the name of the property, the value of the property, and the 119 caller-provided opaque argument. 120 .sp 121 .LP 122 A number of special properties are reserved for internal use and cannot be set 123 or removed. Attempting to do so will fail. These properties are documented on 124 the \fBlibpool\fR(3LIB) manual page. 125 .SH RETURN VALUES 126 .sp 127 .LP 128 Upon successful completion, \fBpool_get_property()\fR returns the type of the 129 property. Otherwise it returns \fBPOC_INVAL\fR and \fBpool_error()\fR returns 130 the pool-specific error value. 131 .sp 132 .LP 133 Upon successful completion, \fBpool_put_property()\fR, 134 \fBpool_rm_property()\fR, and \fBpool_walk_properties()\fR return 0. Otherwise 135 they return \(mi1 and \fBpool_error()\fR returns the pool-specific error value. 136 .SH ERRORS 137 .sp 138 .LP 139 The \fBpool_get_property()\fR function will fail if: 140 .sp 141 .ne 2 142 .na 143 \fB\fBPOE_BADPARAM\fR\fR 144 .ad 145 .RS 16n 146 The supplied configuration's status is not \fBPOF_VALID\fR, the supplied 147 \fIconf\fR does not contain the supplied \fIelem\fR, or the property is 148 restricted and cannot be accessed by the library. 149 .RE 150 151 .sp 152 .ne 2 153 .na 154 \fB\fBPOE_SYSTEM\fR\fR 155 .ad 156 .RS 16n 157 A system error has occurred. Check the system error code for more details. 158 .RE 159 160 .sp 161 .LP 162 The \fBpool_put_property()\fR function will fail if: 163 .sp 164 .ne 2 165 .na 166 \fB\fBPOE_BADPARAM\fR\fR 167 .ad 168 .RS 20n 169 The supplied configuration's status is not \fBPOF_VALID\fR, the supplied 170 \fIconf\fR does not contain the supplied \fIelem\fR, the property name is not 171 in the correct format, or the property already exists and the supplied type 172 does not match the existing type. 173 .RE 174 175 .sp 176 .ne 2 177 .na 178 \fB\fBPOE_SYSTEM\fR\fR 179 .ad 180 .RS 20n 181 A system error has occurred. Check the system error code for more details. 182 .RE 183 184 .sp 185 .ne 2 186 .na 187 \fB\fBPOE_PUTPROP\fR\fR 188 .ad 189 .RS 20n 190 The property name is reserved by \fBlibpool\fR and not available for use. 191 .RE 192 193 .sp 194 .ne 2 195 .na 196 \fB\fBPOE_INVALID_CONF\fR\fR 197 .ad 198 .RS 20n 199 The configuration is invalid. 200 .RE 201 202 .sp 203 .LP 204 The \fBpool_rm_property()\fR function will fail if: 205 .sp 206 .ne 2 207 .na 208 \fB\fBPOE_BADPARAM\fR\fR 209 .ad 210 .RS 16n 211 The supplied configuration's status is not \fBPOF_VALID\fR, the supplied 212 \fIconf\fR does not contain the supplied elem, or the property is reserved by 213 libpool and cannot be removed. 214 .RE 215 216 .sp 217 .ne 2 218 .na 219 \fB\fBPOE_SYSTEM\fR\fR 220 .ad 221 .RS 16n 222 A system error has occurred. Check the system error code for more details. 223 .RE 224 225 .sp 226 .ne 2 227 .na 228 \fB\fBPOE_PUTPROP\fR\fR 229 .ad 230 .RS 16n 231 The property name is reserved by \fBlibpool\fR and not available for use. 232 .RE 233 234 .sp 235 .LP 236 The \fBpool_walk_properties()\fR function will fail if: 237 .sp 238 .ne 2 239 .na 240 \fB\fBPOE_BADPARAM\fR\fR 241 .ad 242 .RS 16n 243 The supplied configuration's status is not \fBPOF_VALID\fR. 244 .RE 245 246 .sp 247 .ne 2 248 .na 249 \fB\fBPOE_SYSTEM\fR\fR 250 .ad 251 .RS 16n 252 A system error has occurred. Check the system error code for more details. 253 .RE 254 255 .SH ATTRIBUTES 256 .sp 257 .LP 258 See \fBattributes\fR(5) for descriptions of the following attributes: 259 .sp 260 261 .sp 262 .TS 263 box; 264 c | c 265 l | l . 266 ATTRIBUTE TYPE ATTRIBUTE VALUE 267 _ 268 CSI Enabled 269 _ 270 Interface Stability Unstable 271 _ 272 MT-Level Safe 273 .TE 274 275 .SH SEE ALSO 276 .sp 277 .LP 278 \fBlibpool\fR(3LIB), \fBpool_error\fR(3POOL), \fBattributes\fR(5)