| blob | 011584af79bfda9808a422f20e7b9f55754be0f2 |
1 '\" te
2 .\" Copyright (c) 2009, 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. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
4 .\" 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
5 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH POOL_CONF_ALLOC 3POOL "Aug 3, 2009"
7 .SH NAME
8 pool_conf_alloc, pool_conf_close, pool_conf_commit, pool_conf_export,
9 pool_conf_free, pool_conf_info, pool_conf_location, pool_conf_open,
10 pool_conf_remove, pool_conf_rollback, pool_conf_status, pool_conf_update,
11 pool_conf_validate \- manipulate resource pool configurations
12 .SH SYNOPSIS
13 .LP
14 .nf
15 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lpool\fR [ \fIlibrary\fR\&.\|.\|. ]
16 #include <pool.h>
18 \fBpool_conf_t *\fR\fBpool_conf_alloc\fR(\fBvoid\fR);
19 .fi
21 .LP
22 .nf
23 \fBint\fR \fBpool_conf_close\fR(\fBpool_conf_t *\fR\fIconf\fR);
24 .fi
26 .LP
27 .nf
28 \fBint\fR \fBpool_conf_commit\fR(\fBpool_conf_t *\fR\fIconf\fR, \fBint\fR \fIactive\fR);
29 .fi
31 .LP
32 .nf
33 \fBint\fR \fBpool_conf_export\fR(\fBpool_conf_t *\fR\fIconf\fR, \fBconst char *\fR\fIlocation\fR,
34 \fBpool_export_format_t\fR \fIformat\fR);
35 .fi
37 .LP
38 .nf
39 \fBvoid\fR \fBpool_conf_free\fR(\fBpool_conf_t *\fR\fIconf\fR);
40 .fi
42 .LP
43 .nf
44 \fBchar *\fR\fBpool_conf_info\fR(\fBconst pool_conf_t *\fR\fIconf\fR, \fBint\fR \fIflags\fR);
45 .fi
47 .LP
48 .nf
49 \fBconst char *\fR\fBpool_conf_location\fR(\fBpool_conf_t *\fR\fIconf\fR);
50 .fi
52 .LP
53 .nf
54 \fBint\fR \fBpool_conf_open\fR(\fBpool_conf_t *\fR\fIconf\fR, \fBconst char *\fR\fIlocation\fR,
55 \fBint\fR \fIflags\fR);
56 .fi
58 .LP
59 .nf
60 \fBint\fR \fBpool_conf_remove\fR(\fBpool_conf_t *\fR\fIconf\fR);
61 .fi
63 .LP
64 .nf
65 \fBint\fR \fBpool_conf_rollback\fR(\fBpool_conf_t *\fR\fIconf\fR);
66 .fi
68 .LP
69 .nf
70 \fBpool_conf_state_t\fR \fBpool_conf_status\fR(\fBconst pool_conf_t *\fR\fIconf\fR);
71 .fi
73 .LP
74 .nf
75 \fBint\fR \fBpool_conf_update\fR(\fBconst pool_conf_t *\fR\fIconf\fR, \fBint *\fR\fIchanged\fR);
76 .fi
78 .LP
79 .nf
80 \fBint\fR \fBpool_conf_validate\fR(\fBpool_conf_t *\fR\fIconf\fR,
81 \fBpool_valid_level_t\fR \fIlevel\fR);
82 .fi
84 .SH DESCRIPTION
85 .sp
86 .LP
87 These functions enable the access and creation of configuration files
88 associated with the pools facility. Since the pool configuration is an opaque
89 type, an initial configuration is obtained with \fBpool_conf_alloc()\fR and
90 released with \fBpool_conf_free()\fR when the configuration is no longer of
91 interest. The \fIconf\fR argument for each function refers to the target
92 configuration to which the operation applies.
93 .sp
94 .LP
95 The \fBpool_conf_close()\fR function closes the given configuration, releasing
96 associated resources.
97 .sp
98 .LP
99 The \fBpool_conf_commit()\fR function commits changes made to the given
100 \fBpool_conf_t\fR to permanent storage. If the \fIactive\fR flag is non-zero,
101 the state of the system will be configured to match that described in the
102 supplied \fBpool_conf_t\fR. If configuring the system fails,
103 \fBpool_conf_commit()\fR will attempt to restore the system to its previous
104 state.
105 .sp
106 .LP
107 The \fBpool_conf_export()\fR function saves the given configuration to the
108 specified location. The only currently supported value of \fIformat\fR is
109 \fBPOX_NATIVE\fR, which is the format native to \fBlibpool\fR, the output of
110 which can be used as input to \fBpool_conf_open()\fR.
111 .sp
112 .LP
113 The \fBpool_conf_info()\fR function returns a string describing the entire
114 configuration. The string is allocated with \fBmalloc\fR(3C). The caller is
115 responsible for freeing the returned string. If the flags option is non-zero,
116 the string returned also describes the sub-elements (if any) contained in the
117 configuration.
118 .sp
119 .LP
120 The \fBpool_conf_location()\fR function returns the location string provided to
121 \fBpool_conf_open()\fR for the given \fBpool_conf_t\fR.
122 .sp
123 .LP
124 The \fBpool_conf_open()\fR function creates a \fBpool_conf_t\fR given a
125 location at which the configuration is stored. The valid flags are a bitmap of
126 the following:
127 .sp
128 .ne 2
129 .na
130 \fB\fBPO_RDONLY\fR\fR
131 .ad
132 .RS 13n
133 Open for reading only.
134 .RE
136 .sp
137 .ne 2
138 .na
139 \fB\fBPO_RDWR\fR\fR
140 .ad
141 .RS 13n
142 Open read-write.
143 .RE
145 .sp
146 .ne 2
147 .na
148 \fB\fBPO_CREAT\fR\fR
149 .ad
150 .RS 13n
151 Create a configuration at the given location if it does not exist. If it does,
152 truncate it.
153 .RE
155 .sp
156 .ne 2
157 .na
158 \fB\fBPO_DISCO\fR\fR
159 .ad
160 .RS 13n
161 Perform `discovery'. This option only makes sense when used in conjunction with
162 \fBPO_CREAT\fR, and causes the returned \fBpool_conf_t\fR to contain the
163 resources and components currently active on the system.
164 .sp
165 The use of this flag is deprecated. \fBPO_CREAT\fR always performs discovery.
166 If supplied, this flag is ignored.
167 .RE
169 .sp
170 .ne 2
171 .na
172 \fB\fBPO_UPDATE\fR\fR
173 .ad
174 .RS 13n
175 Use when opening the dynamic state file, which is the configuration at
176 \fBpool_dynamic_location\fR(3POOL), to ensure that the contents of the dynamic
177 state file are updated to represent the current state of the system.
178 .sp
179 The use of this flag is deprecated. The dynamic state is always current and
180 does not require updating. If supplied, this flag is ignored.
181 .RE
183 .sp
184 .LP
185 A call to \fBpool_conf_open()\fR with the pool dynamic location and write
186 permission will hang if the dynamic location has already been opened for
187 writing.
188 .sp
189 .LP
190 The \fBpool_conf_remove()\fR function removes the configuration's permanent
191 storage. If the configuration is still open, it is first closed.
192 .sp
193 .LP
194 The \fBpool_conf_rollback()\fR function restores the configuration state to
195 that held in the configuration's permanent storage. This will either be the
196 state last successfully committed (using \fBpool_conf_commit()\fR) or the state
197 when the configuration was opened if there have been no successfully committed
198 changes since then.
199 .sp
200 .LP
201 The \fBpool_conf_status()\fR function returns the status of a configuration,
202 which can be one of the following values:
203 .sp
204 .ne 2
205 .na
206 \fB\fBPOF_INVALID\fR\fR
207 .ad
208 .RS 15n
209 The configuration is not in a suitable state for use.
210 .RE
212 .sp
213 .ne 2
214 .na
215 \fB\fBPOF_VALID\fR\fR
216 .ad
217 .RS 15n
218 The configuration is in a suitable state for use.
219 .RE
221 .sp
222 .LP
223 The \fBpool_conf_update()\fR function updates the library snapshot of kernel
224 state. If \fIchanged\fR is non-null, it is updated to identify which types of
225 configuration elements changed during the update. To check for change, treat
226 the \fIchanged\fR value as a bitmap of possible element types.
227 .sp
228 .LP
229 A change is defined for the different element classes as follows:
230 .sp
231 .ne 2
232 .na
233 \fB\fBPOU_SYSTEM\fR\fR
234 .ad
235 .RS 14n
236 A property on the system element has been created, modified, or removed.
237 .RE
239 .sp
240 .ne 2
241 .na
242 \fB\fBPOU_POOL\fR\fR
243 .ad
244 .RS 14n
245 A property on a pool element has been created, modified, or removed. A pool has
246 changed a resource association.
247 .RE
249 .sp
250 .ne 2
251 .na
252 \fB\fBPOU_PSET\fR\fR
253 .ad
254 .RS 14n
255 A property on a pset element has been created, modified, or removed. A pset's
256 resource composition has changed.
257 .RE
259 .sp
260 .ne 2
261 .na
262 \fB\fBPOU_CPU\fR\fR
263 .ad
264 .RS 14n
265 A property on a CPU element has been created, modified, or removed.
266 .RE
268 .sp
269 .LP
270 The \fBpool_conf_validate()\fR function checks the validity of the contents of
271 the given configuration. The validation can be at several (increasing) levels
272 of strictness:
273 .sp
274 .ne 2
275 .na
276 \fB\fBPOV_LOOSE\fR\fR
277 .ad
278 .RS 15n
279 Performs basic internal syntax validation.
280 .RE
282 .sp
283 .ne 2
284 .na
285 \fB\fBPOV_STRICT\fR\fR
286 .ad
287 .RS 15n
288 Performs a more thorough syntax validation and internal consistency checks.
289 .RE
291 .sp
292 .ne 2
293 .na
294 \fB\fBPOV_RUNTIME\fR\fR
295 .ad
296 .RS 15n
297 Performs an estimate of whether attempting to commit the given configuration on
298 the system would succeed or fail. It is optimistic in that a successful
299 validation does not guarantee a subsequent commit operation will be successful;
300 it is conservative in that a failed validation indicates that a subsequent
301 commit operation on the current system will always fail.
302 .RE
304 .SH RETURN VALUES
305 .sp
306 .LP
307 Upon successful completion, \fBpool_conf_alloc()\fR returns an initialized
308 \fBpool_conf_t\fR pointer. Otherwise it returns \fINULL\fR and
309 \fBpool_error\fR(3POOL) returns the pool-specific error value.
310 .sp
311 .LP
312 Upon successful completion, \fBpool_conf_close()\fR, \fBpool_conf_commit()\fR,
313 \fBpool_conf_export()\fR, \fBpool_conf_open()\fR, \fBpool_conf_remove()\fR,
314 \fBpool_conf_rollback()\fR, \fBpool_conf_update()\fR, and
315 \fBpool_conf_validate()\fR return 0. Otherwise they return -1 and
316 \fBpool_error()\fR returns the pool-specific error value.
317 .sp
318 .LP
319 The \fBpool_conf_status()\fR function returns either \fBPOF_INVALID\fR or
320 \fBPOF_VALID\fR.
321 .SH ERRORS
322 .sp
323 .LP
324 The \fBpool_conf_alloc()\fR function will fail if:
325 .sp
326 .ne 2
327 .na
328 \fB\fBPOE_SYSTEM\fR\fR
329 .ad
330 .RS 20n
331 There is not enough memory available to allocate the configuration. Check
332 \fBerrno\fR for the specific system error code.
333 .RE
335 .sp
336 .ne 2
337 .na
338 \fB\fBPOE_INVALID_CONF\fR\fR
339 .ad
340 .RS 20n
341 The configuration is invalid.
342 .RE
344 .sp
345 .LP
346 The \fBpool_conf_close()\fR function will fail if:
347 .sp
348 .ne 2
349 .na
350 \fB\fBPOE_BADPARAM\fR\fR
351 .ad
352 .RS 16n
353 The supplied configuration's status is not \fBPOF_VALID\fR.
354 .RE
356 .sp
357 .ne 2
358 .na
359 \fB\fBPOE_SYSTEM\fR\fR
360 .ad
361 .RS 16n
362 The configuration's permanent store cannot be closed. Check \fBerrno\fR for
363 the specific system error code.
364 .RE
366 .sp
367 .LP
368 The \fBpool_conf_commit()\fR function will fail if:
369 .sp
370 .ne 2
371 .na
372 \fB\fBPOE_BADPARAM\fR\fR
373 .ad
374 .RS 20n
375 The supplied configuration's status is not \fBPOF_VALID\fR or the active flag
376 is non-zero and the system could not be modified.
377 .RE
379 .sp
380 .ne 2
381 .na
382 \fB\fBPOE_SYSTEM\fR\fR
383 .ad
384 .RS 20n
385 The permanent store could not be updated. Check \fBerrno\fR for the specific
386 system error code.
387 .RE
389 .sp
390 .ne 2
391 .na
392 \fB\fBPOE_INVALID_CONF\fR\fR
393 .ad
394 .RS 20n
395 The configuration is not valid for this system.
396 .RE
398 .sp
399 .ne 2
400 .na
401 \fB\fBPOE_ACCESS\fR\fR
402 .ad
403 .RS 20n
404 The configuration was not opened with the correct permissions.
405 .RE
407 .sp
408 .ne 2
409 .na
410 \fB\fBPOE_DATASTORE\fR\fR
411 .ad
412 .RS 20n
413 The update of the permanent store has failed and the contents could be
414 corrupted. Check for a \fB\&.bak\fR file at the datastore location if manual
415 recovery is required.
416 .RE
418 .sp
419 .LP
420 The \fBpool_conf_export()\fR function will fail if:
421 .sp
422 .ne 2
423 .na
424 \fB\fBPOE_BADPARAM\fR\fR
425 .ad
426 .RS 17n
427 The supplied configuration's status is not \fBPOF_VALID\fR or the requested
428 export format is not supported.
429 .RE
431 .sp
432 .ne 2
433 .na
434 \fB\fBPOE_DATASTORE\fR\fR
435 .ad
436 .RS 17n
437 The creation of the export file failed. A file might have been created at the
438 specified location but the contents of the file might not be correct.
439 .RE
441 .sp
442 .LP
443 The \fBpool_conf_info()\fR function will fail if:
444 .sp
445 .ne 2
446 .na
447 \fB\fBPOE_BADPARAM\fR\fR
448 .ad
449 .RS 20n
450 The supplied configuration's status is not \fBPOF_VALID\fR or \fIflags\fR is
451 neither 0 nor 1.
452 .RE
454 .sp
455 .ne 2
456 .na
457 \fB\fBPOE_SYSTEM\fR\fR
458 .ad
459 .RS 20n
460 There is not enough memory available to allocate the buffer used to build the
461 information string. Check \fBerrno\fR for the specific system error code.
462 .RE
464 .sp
465 .ne 2
466 .na
467 \fB\fBPOE_INVALID_CONF\fR\fR
468 .ad
469 .RS 20n
470 The configuration is invalid.
471 .RE
473 .sp
474 .LP
475 The \fBpool_conf_location()\fR function will fail if:
476 .sp
477 .ne 2
478 .na
479 \fB\fBPOE_BADPARAM\fR\fR
480 .ad
481 .RS 16n
482 The supplied configuration's status is not \fBPOF_VALID\fR.
483 .RE
485 .sp
486 .LP
487 The \fBpool_conf_open()\fR function will fail if:
488 .sp
489 .ne 2
490 .na
491 \fB\fBPOE_BADPARAM\fR\fR
492 .ad
493 .RS 20n
494 The supplied configuration's status is already \fBPOF_VALID\fR.
495 .RE
497 .sp
498 .ne 2
499 .na
500 \fB\fBPOE_SYSTEM\fR\fR
501 .ad
502 .RS 20n
503 There is not enough memory available to store the supplied location, or the
504 pools facility is not active. Check \fBerrno\fR for the specific system error
505 code.
506 .RE
508 .sp
509 .ne 2
510 .na
511 \fB\fBPOE_INVALID_CONF\fR\fR
512 .ad
513 .RS 20n
514 The configuration to be opened is at \fBpool_dynamic_location\fR(3POOL) and the
515 configuration is not valid for this system.
516 .RE
518 .sp
519 .LP
520 The \fBpool_conf_remove()\fR function will fail if:
521 .sp
522 .ne 2
523 .na
524 \fB\fBPOE_BADPARAM\fR\fR
525 .ad
526 .RS 16n
527 The supplied configuration's status is not \fBPOF_VALID\fR.
528 .RE
530 .sp
531 .ne 2
532 .na
533 \fB\fBPOE_SYSTEM\fR\fR
534 .ad
535 .RS 16n
536 The configuration's permanent storage could not be removed. Check \fBerrno\fR
537 for the specific system error code.
538 .RE
540 .sp
541 .LP
542 The \fBpool_conf_rollback()\fR function will fail if:
543 .sp
544 .ne 2
545 .na
546 \fB\fBPOE_BADPARAM\fR\fR
547 .ad
548 .RS 16n
549 The supplied configuration's status is not \fBPOF_VALID\fR.
550 .RE
552 .sp
553 .ne 2
554 .na
555 \fB\fBPOE_SYSTEM\fR\fR
556 .ad
557 .RS 16n
558 The permanent store could not be accessed. Check \fBerrno\fR for the specific
559 system error code.
560 .RE
562 .sp
563 .LP
564 The \fBpool_conf_update()\fR function will fail if:
565 .sp
566 .ne 2
567 .na
568 \fB\fBPOE_BADPARAM\fR\fR
569 .ad
570 .RS 20n
571 The supplied configuration's status is not \fBPOF_VALID\fR or the configuration
572 is not the dynamic configuration.
573 .RE
575 .sp
576 .ne 2
577 .na
578 \fB\fBPOE_DATASTORE\fR\fR
579 .ad
580 .RS 20n
581 The kernel snapshot cannot be correctly unpacked.
582 .RE
584 .sp
585 .ne 2
586 .na
587 \fB\fBPOE_INVALID_CONF\fR\fR
588 .ad
589 .RS 20n
590 The configuration contains uncommitted transactions.
591 .RE
593 .sp
594 .ne 2
595 .na
596 \fB\fBPOE_SYSTEM\fR\fR
597 .ad
598 .RS 20n
599 A system error occurred during snapshot retrieval and update.
600 .RE
602 .sp
603 .LP
604 The \fBpool_conf_validate()\fR function will fail if:
605 .sp
606 .ne 2
607 .na
608 \fB\fBPOE_BADPARAM\fR\fR
609 .ad
610 .RS 20n
611 The supplied configuration's status is not \fBPOF_VALID\fR.
612 .RE
614 .sp
615 .ne 2
616 .na
617 \fB\fBPOE_INVALID_CONF\fR\fR
618 .ad
619 .RS 20n
620 The configuration is invalid.
621 .RE
623 .SH EXAMPLES
624 .LP
625 \fBExample 1 \fRCreate the configuration at the specified location.
626 .sp
627 .in +2
628 .nf
629 #include <pool.h>
630 #include <stdio.h>
632 \&...
634 pool_conf_t *pool_conf;
635 pool_conf = pool_conf_alloc();
636 char *input_location = "/tmp/poolconf.example";
638 if (pool_conf_open(pool_conf, input_location,
639 PO_RDONLY) < 0) {
640 fprintf(stderr, "Opening pool configuration %s
641 failed\en", input_location);
642 }
643 .fi
644 .in -2
646 .SH ATTRIBUTES
647 .sp
648 .LP
649 See \fBattributes\fR(5) for descriptions of the following attributes:
650 .sp
652 .sp
653 .TS
654 box;
655 c | c
656 l | l .
657 ATTRIBUTE TYPE ATTRIBUTE VALUE
658 _
659 CSI Enabled
660 _
661 Interface Stability Uncommitted
662 _
663 MT-Level Safe
664 .TE
666 .SH SEE ALSO
667 .sp
668 .LP
669 \fBlibpool\fR(3LIB), \fBpool_error\fR(3POOL), \fBattributes\fR(5)