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