pool_conf_commit(3pool)

1pool_conf_alloc(P3oPoOlOLC)onfiguration Manipulation Library Fupnocotli_ocnosnf_alloc(3POOL)
2
3
4

NAME

6       pool_conf_alloc,  pool_conf_close,  pool_conf_commit, pool_conf_export,
7       pool_conf_free,  pool_conf_info,  pool_conf_location,   pool_conf_open,
8       pool_conf_remove,         pool_conf_rollback,         pool_conf_status,
9       pool_conf_update, pool_conf_validate - manipulate resource pool config‐
10       urations
11

SYNOPSIS

13       cc [ flag... ] file... -lpool [ library... ]
14       #include <pool.h>
15
16       pool_conf_t *pool_conf_alloc(void);
17
18
19       int pool_conf_close(pool_conf_t *conf);
20
21
22       int pool_conf_commit(pool_conf_t *conf, int active);
23
24
25       int pool_conf_export(pool_conf_t *conf, const char *location,
26            pool_export_format_t format);
27
28
29       void pool_conf_free(pool_conf_t *conf);
30
31
32       char *pool_conf_info(const pool_conf_t *conf, int flags);
33
34
35       const char *pool_conf_location(pool_conf_t *conf);
36
37
38       int pool_conf_open(pool_conf_t *conf, const char *location,
39            int flags);
40
41
42       int pool_conf_remove(pool_conf_t *conf);
43
44
45       int pool_conf_rollback(pool_conf_t *conf);
46
47
48       pool_conf_state_t pool_conf_status(const pool_conf_t *conf);
49
50
51       int pool_conf_update(const pool_conf_t *conf, int *changed);
52
53
54       int pool_conf_validate(pool_conf_t *conf,
55            pool_valid_level_t level);
56
57

DESCRIPTION

59       These  functions  enable the access and creation of configuration files
60       associated with the pools facility.  Since the pool configuration is an
61       opaque    type,    an    initial   configuration   is   obtained   with
62       pool_conf_alloc() and released with pool_conf_free() when the  configu‐
63       ration  is  no  longer of interest. The conf argument for each function
64       refers to the target configuration to which the operation applies.
65
66
67       The pool_conf_close() function closes the given configuration,  releas‐
68       ing associated resources.
69
70
71       The  pool_conf_commit()  function  commits  changes  made  to the given
72       pool_conf_t to permanent storage. If the active flag is  non-zero,  the
73       state  of  the system will be configured to match that described in the
74       supplied pool_conf_t. If configuring the system  fails,  pool_conf_com‐
75       mit() will attempt to restore the system to its previous state.
76
77
78       The  pool_conf_export()  function  saves the given configuration to the
79       specified location. The only currently supported  value  of  format  is
80       POX_NATIVE,  which is the format native to libpool, the output of which
81       can be used as input to pool_conf_open().
82
83
84       The pool_conf_info() function returns a string  describing  the  entire
85       configuration.   The string is allocated with malloc(3C). The caller is
86       responsible for freeing the returned string. If  the  flags  option  is
87       non-zero,  the string returned also describes the sub-elements (if any)
88       contained in the configuration.
89
90
91       The pool_conf_location() function returns the location string  provided
92       to pool_conf_open() for the given pool_conf_t.
93
94
95       The pool_conf_open() function creates a pool_conf_t given a location at
96       which the configuration is stored. The valid flags are a bitmap of  the
97       following:
98
99       PO_RDONLY    Open for reading only.
100
101
102       PO_RDWR      Open read-write.
103
104
105       PO_CREAT     Create  a  configuration  at the given location if it does
106                    not exist. If it does, truncate it.
107
108
109       PO_DISCO     Perform `discovery'. This option  only  makes  sense  when
110                    used in conjunction with PO_CREAT, and causes the returned
111                    pool_conf_t to contain the resources and  components  cur‐
112                    rently active on the system.
113
114                    The  use  of this flag is deprecated. PO_CREAT always per‐
115                    forms discovery. If supplied, this flag is ignored.
116
117
118       PO_UPDATE    Use when opening the dynamic state file, which is the con‐
119                    figuration at pool_dynamic_location(3POOL), to ensure that
120                    the contents of the dynamic state file are updated to rep‐
121                    resent the current state of the system.
122
123                    The  use  of this flag is deprecated. The dynamic state is
124                    always current and does not require updating. If supplied,
125                    this flag is ignored.
126
127
128
129       A  call  to  pool_conf_open()  with the pool dynamic location and write
130       permission will hang if the dynamic location has  already  been  opened
131       for writing.
132
133
134       The  pool_conf_remove()  function removes the configuration's permanent
135       storage. If the configuration is still open, it is first closed.
136
137
138       The pool_conf_rollback() function restores the configuration  state  to
139       that held in the configuration's permanent storage. This will either be
140       the state last successfully committed (using pool_conf_commit()) or the
141       state  when the configuration was opened if there have been no success‐
142       fully committed changes since then.
143
144
145       The pool_conf_status() function returns the status of a  configuration,
146       which can be one of the following values:
147
148       POF_INVALID    The configuration is not in a suitable state for use.
149
150
151       POF_VALID      The configuration is in a suitable state for use.
152
153
154
155       The  pool_conf_update() function updates the library snapshot of kernel
156       state. If changed is non-null, it is updated to identify which types of
157       configuration  elements changed during the update. To check for change,
158       treat the changed value as a bitmap of possible element types.
159
160
161       A change is defined for the different element classes as follows:
162
163       POU_SYSTEM    A property on the system element has been created,  modi‐
164                     fied, or removed.
165
166
167       POU_POOL      A  property on a pool element has been created, modified,
168                     or removed. A pool has changed a resource association.
169
170
171       POU_PSET      A property on a pset element has been created,  modified,
172                     or removed. A pset's resource composition has changed.
173
174
175       POU_CPU       A  property  on a CPU element has been created, modified,
176                     or removed.
177
178
179
180       The pool_conf_validate() function checks the validity of  the  contents
181       of  the given configuration. The validation can be at several (increas‐
182       ing) levels of strictness:
183
184       POV_LOOSE      Performs basic internal syntax validation.
185
186
187       POV_STRICT     Performs a more thorough syntax validation and  internal
188                      consistency checks.
189
190
191       POV_RUNTIME    Performs an estimate of whether attempting to commit the
192                      given configuration on the system would succeed or fail.
193                      It  is  optimistic  in that a successful validation does
194                      not guarantee a subsequent commit operation will be suc‐
195                      cessful;  it is conservative in that a failed validation
196                      indicates that a subsequent commit operation on the cur‐
197                      rent system will always fail.
198
199

RETURN VALUES

201       Upon  successful  completion,  pool_conf_alloc() returns an initialized
202       pool_conf_t pointer. Otherwise it returns  NULL  and  pool_error(3POOL)
203       returns the pool-specific error value.
204
205
206       Upon   successful  completion,  pool_conf_close(),  pool_conf_commit(),
207       pool_conf_export(),        pool_conf_open(),        pool_conf_remove(),
208       pool_conf_rollback(),   pool_conf_update(),   and  pool_conf_validate()
209       return 0. Otherwise they return -1 and pool_error() returns  the  pool-
210       specific error value.
211
212
213       The   pool_conf_status()   function   returns   either  POF_INVALID  or
214       POF_VALID.
215

ERRORS

217       The pool_conf_alloc() function will fail if:
218
219       POE_SYSTEM          There is not enough memory  available  to  allocate
220                           the  configuration.  Check  errno  for the specific
221                           system error code.
222
223
224       POE_INVALID_CONF    The configuration is invalid.
225
226
227
228       The pool_conf_close() function will fail if:
229
230       POE_BADPARAM    The supplied configuration's status is not POF_VALID.
231
232
233       POE_SYSTEM      The configuration's permanent store cannot  be  closed.
234                       Check errno for the specific system error code.
235
236
237
238       The pool_conf_commit() function will fail if:
239
240       POE_BADPARAM        The   supplied   configuration's   status   is  not
241                           POF_VALID or the active flag is  non-zero  and  the
242                           system could not be modified.
243
244
245       POE_SYSTEM          The  permanent  store  could  not be updated. Check
246                           errno for the specific system error code.
247
248
249       POE_INVALID_CONF    The configuration is not valid for this system.
250
251
252       POE_ACCESS          The configuration was not opened with  the  correct
253                           permissions.
254
255
256       POE_DATASTORE       The  update  of  the permanent store has failed and
257                           the contents could be corrupted. Check for  a  .bak
258                           file  at  the datastore location if manual recovery
259                           is required.
260
261
262
263       The pool_conf_export() function will fail if:
264
265       POE_BADPARAM     The supplied configuration's status is  not  POF_VALID
266                        or the requested export format is not supported.
267
268
269       POE_DATASTORE    The  creation  of the export file failed. A file might
270                        have been created at the specified  location  but  the
271                        contents of the file might not be correct.
272
273
274
275       The pool_conf_info() function will fail if:
276
277       POE_BADPARAM        The   supplied   configuration's   status   is  not
278                           POF_VALID or flags is neither 0 nor 1.
279
280
281       POE_SYSTEM          There is not enough memory  available  to  allocate
282                           the  buffer  used  to build the information string.
283                           Check errno for the specific system error code.
284
285
286       POE_INVALID_CONF    The configuration is invalid.
287
288
289
290       The pool_conf_location() function will fail if:
291
292       POE_BADPARAM    The supplied configuration's status is not POF_VALID.
293
294
295
296       The pool_conf_open() function will fail if:
297
298       POE_BADPARAM        The  supplied  configuration's  status  is  already
299                           POF_VALID.
300
301
302       POE_SYSTEM          There  is  not enough memory available to store the
303                           supplied location, or the  pools  facility  is  not
304                           active.  Check  errno for the specific system error
305                           code.
306
307
308       POE_INVALID_CONF    The   configuration   to   be    opened    is    at
309                           pool_dynamic_location(3POOL)  and the configuration
310                           is not valid for this system.
311
312
313
314       The pool_conf_remove() function will fail if:
315
316       POE_BADPARAM    The supplied configuration's status is not POF_VALID.
317
318
319       POE_SYSTEM      The configuration's  permanent  storage  could  not  be
320                       removed.  Check  errno  for  the  specific system error
321                       code.
322
323
324
325       The pool_conf_rollback() function will fail if:
326
327       POE_BADPARAM    The supplied configuration's status is not POF_VALID.
328
329
330       POE_SYSTEM      The permanent store could not be accessed. Check  errno
331                       for the specific system error code.
332
333
334
335       The pool_conf_update() function will fail if:
336
337       POE_BADPARAM        The   supplied   configuration's   status   is  not
338                           POF_VALID or the configuration is not  the  dynamic
339                           configuration.
340
341
342       POE_DATASTORE       The kernel snapshot cannot be correctly unpacked.
343
344
345       POE_INVALID_CONF    The  configuration  contains  uncommitted  transac‐
346                           tions.
347
348
349       POE_SYSTEM          A system error occurred during  snapshot  retrieval
350                           and update.
351
352
353
354       The pool_conf_validate() function will fail if:
355
356       POE_BADPARAM        The   supplied   configuration's   status   is  not
357                           POF_VALID.
358
359
360       POE_INVALID_CONF    The configuration is invalid.
361
362

EXAMPLES

364       Example 1 Create the configuration at the specified location.
365
366         #include <pool.h>
367         #include <stdio.h>
368
369         ...
370
371         pool_conf_t *pool_conf;
372         pool_conf = pool_conf_alloc();
373         char *input_location = "/tmp/poolconf.example";
374
375         if (pool_conf_open(pool_conf, input_location,
376             PO_RDONLY) < 0) {
377                 fprintf(stderr, "Opening pool configuration %s
378                         failed\n", input_location);
379         }
380
381

ATTRIBUTES

383       See attributes(5) for descriptions of the following attributes:
384
385
386
387
388       ┌─────────────────────────────┬─────────────────────────────┐
389       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
390       ├─────────────────────────────┼─────────────────────────────┤
391       │CSI                          │Enabled                      │
392       ├─────────────────────────────┼─────────────────────────────┤
393       │Interface Stability          │Uncommitted                  │
394       ├─────────────────────────────┼─────────────────────────────┤
395       │MT-Level                     │Safe                         │
396       └─────────────────────────────┴─────────────────────────────┘
397