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
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
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)
|
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
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
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)
|