share/man/man3pool/pool_get_property.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_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)