scf_iter_next_pg(3scf)

1scf_iter_create(S3eSrCvFi)ce Configuration Facility Library Funcstcifo_nister_create(3SCF)
2
3
4

NAME

6       scf_iter_create,   scf_iter_handle,  scf_iter_destroy,  scf_iter_reset,
7       scf_iter_handle_scopes,     scf_iter_scope_services,      scf_iter_ser‐
8       vice_instances,    scf_iter_service_pgs,    scf_iter_service_pgs_typed,
9       scf_iter_instance_snapshots,                    scf_iter_snaplevel_pgs,
10       scf_iter_snaplevel_pgs_typed,                    scf_iter_instance_pgs,
11       scf_iter_instance_pgs_typed,            scf_iter_instance_pgs_composed,
12       scf_iter_instance_pgs_typed_composed,           scf_iter_pg_properties,
13       scf_iter_property_values,  scf_iter_next_scope,  scf_iter_next_service,
14       scf_iter_next_instance,    scf_iter_next_snapshot,    scf_iter_next_pg,
15       scf_iter_next_property, scf_iter_next_value - iterate through the  Ser‐
16       vice Configuration Facility repository
17

SYNOPSIS

19       cc [ flag... ] file... -lscf [ library... ]
20       #include <libscf.h>
21
22       scf_iter_t *scf_iter_create(scf_handle_t *handle);
23
24
25       scf_handle_t *scf_iter_handle(scf_iter_t *iter);
26
27
28       void scf_iter_destroy(scf_iter_t *iter);
29
30
31       void scf_iter_reset(scf_iter_t *iter);
32
33
34       int scf_iter_handle_scopes(scf_iter_t *iter, const scf_handle_t *h);
35
36
37       int scf_iter_scope_services(scf_iter_t *iter, const scf_scope_t *parent);
38
39
40       int scf_iter_service_instances(scf_iter_t *iter,
41            const scf_service_t *parent);
42
43
44       int scf_iter_service_pgs(scf_iter_t *iter, const scf_service_t *parent);
45
46
47       int scf_iter_service_pgs_typed(scf_iter_t *iter,
48            const scf_service_t *parent, const char *pgtype);
49
50
51       int scf_iter_instance_snapshots(scf_iter_t *iter,
52            const scf_instance_t *parent);
53
54
55       int scf_iter_snaplevel_pgs(scf_iter_t *iter,
56            const scf_snaplevel_t *parent);
57
58
59       int scf_iter_snaplevel_pgs_typed(scf_iter_t *iter,
60            const scf_snaplevel_t *parent, const char *pgtype);
61
62
63       int scf_iter_instance_pgs(scf_iter_t *iter, scf_instance_t *parent);
64
65
66       int scf_iter_instance_pgs_typed(scf_iter_t *iter,
67            scf_instance_t *parent, const char *pgtype);
68
69
70       int scf_iter_instance_pgs_composed(scf_iter_t *iter,
71            const scf_instance_t *instance, const scf_snapshot_t *snapshot);
72
73
74       int scf_iter_instance_pgs_typed_composed(scf_iter_t *iter,
75            const scf_instance_t *instance, const scf_snapshot_t *snapshot,
76            const char *pgtype);
77
78
79       int scf_iter_pg_properties(scf_iter_t *iter,
80            const scf_propertygroup_t *parent);
81
82
83       int scf_iter_property_values(scf_iter_t *iter,
84            const scf_property_t *parent);
85
86
87       int scf_iter_next_scope(scf_iter_t *iter, scf_scope_t *out);
88
89
90       int scf_iter_next_service(scf_iter_t *iter, scf_service_t *out);
91
92
93       int scf_iter_next_instance(scf_iter_t *iter, scf_instance_t *out);
94
95
96       int scf_iter_next_snapshot(scf_iter_t *iter, scf_snapshot_t *out);
97
98
99       int scf_iter_next_pg(scf_iter_t *iter, scf_propertygroup_t  *out);
100
101
102       int scf_iter_next_property(scf_iter_t *iter, scf_property_t *out);
103
104
105       int scf_iter_next_value(scf_iter_t *iter, scf_value_t *out);
106
107

DESCRIPTION

109       The  scf_iter_create()  function creates a new iterator associated with
110       handle. The scf_iter_destroy() function destroys an iteration.
111
112
113       The scf_iter_reset() function releases any resources involved  with  an
114       active iteration and returns the iterator to its initial state.
115
116
117       The  scf_iter_handle_scopes(), scf_iter_scope_services(), scf_iter_ser‐
118       vice_instances(),     scf_iter_instance_snapshots(),      scf_iter_ser‐
119       vice_pgs(),      scf_iter_instance_pgs(),     scf_iter_snaplevel_pgs(),
120       scf_iter_pg_properties(), and scf_iter_property_values() functions  set
121       up a new iteration of all the children parent of a particular type. The
122       scf_iter_property_values() function will iterate  over  values  in  the
123       order in which they were specified with scf_entry_add_value(3SCF).
124
125
126       The  scf_iter_service_pgs_typed(),  scf_iter_instance_pgs_typed(),  and
127       scf_iter_snaplevel_pgs_typed() functions iterate over the  child  prop‐
128       erty groups of parent, but restrict them to a particular property group
129       type.
130
131
132       The scf_iter_instance_pgs_composed() function sets up a  new  iteration
133       of  the  composed  view of instance's children at the time snapshot was
134       taken. If snapshot is NULL, the current properties are used.  The  com‐
135       posed  view  of an instance's properties is the union of the properties
136       of the instance and its ancestors.  Properties  of  the  instance  take
137       precedence over properties of the service with the same name, including
138       property group name. Property groups retrieved with this iterator might
139       not  have  instance  as their parent and properties retrieved from such
140       property groups might not have the indicated property  group  as  their
141       parent.  If  instance and its parent have property groups with the same
142       name but different types, the properties in the property group  of  the
143       parent  are  excluded. The scf_iter_instance_pgs_typed_composed() func‐
144       tion behaves as scf_iter_instance_pgs_composed(), except  the  property
145       groups of the type pgtype are returned.
146
147
148       The           scf_iter_next_scope(),           scf_iter_next_service(),
149       scf_iter_next_instance(), scf_iter_next_snapshot(), scf_iter_next_pg(),
150       scf_iter_next_property(),  and scf_iter_next_value() functions retrieve
151       the next element of the iteration.
152

RETURN VALUES

154       Upon successful completion, scf_iter_create() returns a  pointer  to  a
155       new iterator. Otherwise, it returns NULL.
156
157
158       Upon  successful completion, scf_iter_handle() returns the handle asso‐
159       ciated with iter. Otherwise it returns NULL.
160
161
162       Upon       successful       completion,       scf_iter_handle_scopes(),
163       scf_iter_scope_services(),                scf_iter_service_instances(),
164       scf_iter_instance_snapshots(),                  scf_iter_service_pgs(),
165       scf_iter_instance_pgs(),  scf_iter_snaplevel_pgs(), scf_iter_pg_proper‐
166       ties(),    scf_iter_property_values(),    scf_iter_service_pgs_typed(),
167       scf_iter_instance_pgs_composed(),        scf_iter_instance_pgs_typed(),
168       scf_iter_instance_pgs_typed_composed(),                             and
169       scf_iter_snaplevel_pgs_typed() return 0. Otherwise, they return -1.
170
171
172       Upon  successful  completion, scf_iter_next_scope(), scf_iter_next_ser‐
173       vice(),       scf_iter_next_instance(),       scf_iter_next_snapshot(),
174       scf_iter_next_pg(), scf_iter_next_property(), and scf_iter_next_value()
175       return 1. If the iterator is complete, they return 0.  Otherwise,  they
176       return -1.
177

ERRORS

179       The scf_iter_create() function will fail if:
180
181       SCF_ERROR_INVALID_ARGUMENT    The handle argument is NULL.
182
183
184       SCF_ERROR_NO_MEMORY           There is no memory available.
185
186
187       SCF_ERROR_NO_RESOURCES        The   server   does   not  have  adequate
188                                     resources for a new iteration.
189
190
191
192       The scf_iter_handle() function will fail if:
193
194       SCF_ERROR_HANDLE_DESTROYED    The handle associated with iter has  been
195                                     destroyed.
196
197
198
199       The scf_iter_next_value() function will fail if:
200
201       SCF_ERROR_PERMISSION_DENIED
202
203           The value could not be read due to access restrictions.
204
205
206
207       The  scf_iter_handle_scopes(), scf_iter_scope_services(), scf_iter_ser‐
208       vice_instances(),     scf_iter_instance_snapshots(),      scf_iter_ser‐
209       vice_pgs(),  scf_iter_instance_pgs(), scf_iter_instance_pgs_composed(),
210       scf_iter_snaplevel_pgs(),   scf_iter_pg_properties(),    scf_iter_prop‐
211       erty_values(),                            scf_iter_service_pgs_typed(),
212       scf_iter_instance_pgs_typed(),  scf_iter_instance_pgs_typed_composed(),
213       and scf_iter_snaplevel_pgs_typed() functions will fail if:
214
215       SCF_ERROR_DELETED
216
217           The parent has been deleted.
218
219
220       SCF_ERROR_NOT_SET
221
222           The parent is not set.
223
224
225       SCF_ERROR_NOT_BOUND
226
227           The handle is not bound.
228
229
230       SCF_ERROR_CONNECTION_BROKEN
231
232           The connection to the repository was lost.
233
234
235       SCF_ERROR_HANDLE_MISMATCH
236
237           The iter and parent arguments are not derived from the same handle.
238
239
240
241       The     scf_iter_service_pgs_typed(),    scf_iter_instance_pgs_typed(),
242       scf_iter_instance_pgs_typed_composed(),                             and
243       scf_iter_snaplevel_pgs_typed() functions will fail if:
244
245       SCF_ERROR_INVALID_ARGUMENT    The  pgtype argument is not a valid prop‐
246                                     erty group type.
247
248
249
250       The         scf_iter_next_service(),          scf_iter_next_instance(),
251       scf_iter_next_snapshot(), scf_iter_next_pg(), scf_iter_next_property(),
252       and scf_iter_next_value() functions will fail if:
253
254       SCF_ERROR_DELETED    The parent the iterator is attached  to  has  been
255                            deleted.
256
257
258
259       The           scf_iter_next_scope(),           scf_iter_next_service(),
260       scf_iter_next_instance(),                     scf_iter_next_snapshot(),
261       scf_iter_next_pg(),scf_iter_next_property(),  and scf_iter_next_value()
262       functions will fail if:
263
264       SCF_ERROR_NOT_SET
265
266           The iterator is not set.
267
268
269       SCF_ERROR_INVALID_ARGUMENT
270
271           The requested object type does not match the type the  iterator  is
272           walking.
273
274
275       SCF_ERROR_NOT_BOUND
276
277           The handle is not bound.
278
279
280       SCF_ERROR_HANDLE_MISMATCH
281
282           The iter and parent arguments are not derived from the same handle.
283
284
285       SCF_ERROR_CONNECTION_BROKEN
286
287           The connection to the repository was lost.
288
289
290
291       The       scf_iter_scope_services(),      scf_iter_service_instances(),
292       scf_iter_service_pgs(),                  scf_iter_instance_snapshots(),
293       scf_iter_instance_pgs(),              scf_iter_instance_pgs_composed(),
294       scf_iter_snaplevel_pgs(),   scf_iter_pg_properties(),    scf_iter_prop‐
295       erty_values(),                            scf_iter_service_pgs_typed(),
296       scf_iter_instance_pgs_typed(),  scf_iter_instance_pgs_typed_composed(),
297       scf_iter_snaplevel_pgs_typed(),                scf_iter_next_service(),
298       scf_iter_next_instance(), scf_iter_next_snapshot(), scf_iter_next_pg(),
299       and scf_iter_next_property() functions will fail if:
300
301       SCF_ERROR_NO_RESOURCES    The  server  does  not  have the resources to
302                                 complete the request.
303
304
305
306       The scf_error(3SCF) function can be used to retrieve the error value.
307

EXAMPLES

309       Example 1 Iterate over all instances under a service.
310
311         scf_iter_t *iter = scf_iter_create(handle);
312
313         if (iter == NULL || scf_iter_service_instances(iter, parent) == -1) {
314              /* failure */
315         }
316         while ((r = scf_iter_next_instance(iter, child)) > 0) {
317              /* process child */
318         }
319         if (r < 0) {
320              /* failure */
321         }
322         scf_iter_destroy(iter);
323
324
325       Example 2 Connect to the repository, walk all  services  and  instances
326       and print their FMRIs.
327
328         scf_handle_t *handle = scf_handle_create(SCF_VERSION);
329         scf_scope_t *scope = scf_scope_create(handle);
330         scf_service_t *svc = scf_service_create(handle);
331         scf_instance_t *inst = scf_instance_create(handle);
332         scf_iter_t *svc_iter = scf_iter_create(handle);
333         scf_iter_t *inst_iter = scf_iter_create(handle);
334
335         size_t sz = scf_limit(SCF_LIMIT_MAX_FMRI_LENGTH) + 1;
336         char *fmri = malloc(sz + 1);
337
338         int r;
339
340         if (handle == NULL || scope == NULL || svc == NULL ||
341              inst == NULL || svc_iter == NULL || inst_iter == NULL ||
342              fmri == NULL) {
343                  /* failure */
344         }
345         if (scf_handle_bind(handle) == -1 ||
346              scf_handle_get_scope(handle, SCF_SCOPE_LOCAL, scope) == -1 ||
347              scf_iter_scope_services(svc_iter, scope) == -1) {
348                   /* failure */
349         }
350         while ((r = scf_iter_next_service(svc_iter, svc)) > 0) {
351              if (scf_service_to_fmri(svc, fmri, sz) < 0) {
352                   /* failure */
353              }
354              puts(fmri);
355              if (scf_iter_service_instances(inst_iter, svc) < 0) {
356                   /* failure */
357              }
358              while ((r = scf_iter_next_instance(inst_iter, inst)) > 0) {
359                   if (scf_instance_to_fmri(inst, fmri, sz) < 0) {
360                        /* failure */
361                   }
362                   puts(fmri);
363              }
364              if (r < 0)
365                   break;
366         }
367         if (r < 0) {
368              /* failure */
369         }
370
371         scf_handle_destroy(handle);
372         scf_scope_destroy(scope);
373         scf_service_destroy(svc);
374         scf_instance_destroy(inst);
375         scf_iter_destroy(svc_iter);
376         scf_iter_destroy(inst_iter);
377
378

ATTRIBUTES

380       See attributes(5) for descriptions of the following attributes:
381
382
383
384
385       ┌─────────────────────────────┬─────────────────────────────┐
386       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
387       ├─────────────────────────────┼─────────────────────────────┤
388       │Interface Stability          │Committed                    │
389       ├─────────────────────────────┼─────────────────────────────┤
390       │MT-Level                     │Safe                         │
391       └─────────────────────────────┴─────────────────────────────┘
392