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