1 POOL_GET_PROPERTY(3POOL) Pool Configuration Manipulation Library Functions 2 3 4 5 NAME 6 pool_get_property, pool_put_property, pool_rm_property, 7 pool_walk_properties - resource pool element property manipulation 8 9 SYNOPSIS 10 cc [ flag... ] file... -lpool [ library... ] 11 #include <pool.h> 12 13 pool_value_class_t pool_get_property(pool_conf_t *conf, 14 const pool_elem_t *elem, const char *name, 15 pool_value_t *property); 16 17 18 int pool_put_property(pool_conf_t *conf, pool_elem_t *elem, 19 const char *name, const pool_value_t *value); 20 21 22 int pool_rm_property(pool_conf_t *conf, pool_elem_t *elem, 23 const char *name); 24 25 26 int pool_walk_properties(pool_conf_t *conf, pool_elem_t *elem, 27 void *arg, int (*callback)(pool_conf_t *, pool_elem_t *, 28 const char *, pool_value_t *, void *)); 29 30 31 DESCRIPTION 32 The various pool types are converted to the common pool element type 33 (pool_elem_t) before property manipulation. A pool_value_t is an opaque 34 type that contains a property value of one of the following types: 35 36 POC_UINT 37 unsigned 64-bit integer 38 39 40 POC_INT 41 signed 64-bit integer 42 43 44 POC_DOUBLE 45 signed double-precision floating point value 46 47 48 POC_BOOL 49 boolean value: 0 is false, non-zero is true 50 51 52 POC_STRING 53 null-terminated string of characters 54 55 56 57 The conf argument for each function refers to the target configuration 58 to which the operation applies. 59 60 61 The pool_get_property() function attempts to retrieve the value of the 62 named property from the element. If the property is not found or an 63 error occurs, the value POC_INVAL is returned to indicate error. 64 Otherwise the type of the value retrieved is returned. 65 66 67 The pool_put_property() function attempts to set the named property on 68 the element to the specified value. Attempting to set a property that 69 does not currently exist on the element will cause the property with 70 the given name and value to be created on the element and will not 71 cause an error. An attempt to overwrite an existing property with a new 72 property of a different type is an error. 73 74 75 The pool_rm_property() function attempts to remove the named property 76 from the element. If the property does not exist or is not removable, 77 -1 is returned and pool_error(3POOL) reports an error of POE_PUTPROP. 78 79 80 The pool_walk_properties() function invokes callback on all properties 81 defined for the given element. The callback is called with the element 82 itself, the name of the property, the value of the property, and the 83 caller-provided opaque argument. 84 85 86 A number of special properties are reserved for internal use and cannot 87 be set or removed. Attempting to do so will fail. These properties are 88 documented on the libpool(3LIB) manual page. 89 90 RETURN VALUES 91 Upon successful completion, pool_get_property() returns the type of the 92 property. Otherwise it returns POC_INVAL and pool_error() returns the 93 pool-specific error value. 94 95 96 Upon successful completion, pool_put_property(), pool_rm_property(), 97 and pool_walk_properties() return 0. Otherwise they return -1 and 98 pool_error() returns the pool-specific error value. 99 100 ERRORS 101 The pool_get_property() function will fail if: 102 103 POE_BADPARAM 104 The supplied configuration's status is not POF_VALID, 105 the supplied conf does not contain the supplied elem, 106 or the property is restricted and cannot be accessed by 107 the library. 108 109 110 POE_SYSTEM 111 A system error has occurred. Check the system error 112 code for more details. 113 114 115 116 The pool_put_property() function will fail if: 117 118 POE_BADPARAM 119 The supplied configuration's status is not 120 POF_VALID, the supplied conf does not contain the 121 supplied elem, the property name is not in the 122 correct format, or the property already exists and 123 the supplied type does not match the existing type. 124 125 126 POE_SYSTEM 127 A system error has occurred. Check the system error 128 code for more details. 129 130 131 POE_PUTPROP 132 The property name is reserved by libpool and not 133 available for use. 134 135 136 POE_INVALID_CONF 137 The configuration is invalid. 138 139 140 141 The pool_rm_property() function will fail if: 142 143 POE_BADPARAM 144 The supplied configuration's status is not POF_VALID, 145 the supplied conf does not contain the supplied elem, 146 or the property is reserved by libpool and cannot be 147 removed. 148 149 150 POE_SYSTEM 151 A system error has occurred. Check the system error 152 code for more details. 153 154 155 POE_PUTPROP 156 The property name is reserved by libpool and not 157 available for use. 158 159 160 161 The pool_walk_properties() function will fail if: 162 163 POE_BADPARAM 164 The supplied configuration's status is not POF_VALID. 165 166 167 POE_SYSTEM 168 A system error has occurred. Check the system error 169 code for more details. 170 171 172 ATTRIBUTES 173 See attributes(5) for descriptions of the following attributes: 174 175 176 177 178 +--------------------+-----------------+ 179 | ATTRIBUTE TYPE | ATTRIBUTE VALUE | 180 +--------------------+-----------------+ 181 |CSI | Enabled | 182 +--------------------+-----------------+ 183 |Interface Stability | Unstable | 184 +--------------------+-----------------+ 185 |MT-Level | Safe | 186 +--------------------+-----------------+ 187 188 SEE ALSO 189 libpool(3LIB), pool_error(3POOL), attributes(5) 190 191 192 193 May 16, 2020 POOL_GET_PROPERTY(3POOL)