share/man/man3scf/scf_iter_create.3scf

   1 '\" te
   2 .\" Copyright (c) 2008, Sun Microsystems, Inc.
   3 .\" All Rights Reserved.
   4 .\" 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.
   5 .\" 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.
   6 .\" 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]
   7 .TH SCF_ITER_CREATE 3SCF "Dec 4, 2008"
   8 .SH NAME
   9 scf_iter_create, scf_iter_handle, scf_iter_destroy, scf_iter_reset,
  10 scf_iter_handle_scopes, scf_iter_scope_services, scf_iter_service_instances,
  11 scf_iter_service_pgs, scf_iter_service_pgs_typed, scf_iter_instance_snapshots,
  12 scf_iter_snaplevel_pgs, scf_iter_snaplevel_pgs_typed, scf_iter_instance_pgs,
  13 scf_iter_instance_pgs_typed, scf_iter_instance_pgs_composed,
  14 scf_iter_instance_pgs_typed_composed, scf_iter_pg_properties,
  15 scf_iter_property_values, scf_iter_next_scope, scf_iter_next_service,
  16 scf_iter_next_instance, scf_iter_next_snapshot, scf_iter_next_pg,
  17 scf_iter_next_property, scf_iter_next_value \- iterate through the Service
  18 Configuration Facility repository
  19 .SH SYNOPSIS
  20 .LP
  21 .nf
  22 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lscf\fR [ \fIlibrary\fR\&.\|.\|. ]
  23 #include <libscf.h>
  24
  25 \fBscf_iter_t *\fR\fBscf_iter_create\fR(\fBscf_handle_t *\fR\fIhandle\fR);
  26 .fi
  27
  28 .LP
  29 .nf
  30 \fBscf_handle_t *\fR\fBscf_iter_handle\fR(\fBscf_iter_t *\fR\fIiter\fR);
  31 .fi
  32
  33 .LP
  34 .nf
  35 \fBvoid\fR \fBscf_iter_destroy\fR(\fBscf_iter_t *\fR\fIiter\fR);
  36 .fi
  37
  38 .LP
  39 .nf
  40 \fBvoid\fR \fBscf_iter_reset\fR(\fBscf_iter_t *\fR\fIiter\fR);
  41 .fi
  42
  43 .LP
  44 .nf
  45 \fBint\fR \fBscf_iter_handle_scopes\fR(\fBscf_iter_t *\fR\fIiter\fR, \fBconst scf_handle_t *\fR\fIh\fR);
  46 .fi
  47
  48 .LP
  49 .nf
  50 \fBint\fR \fBscf_iter_scope_services\fR(\fBscf_iter_t *\fR\fIiter\fR, \fBconst scf_scope_t *\fR\fIparent\fR);
  51 .fi
  52
  53 .LP
  54 .nf
  55 \fBint\fR \fBscf_iter_service_instances\fR(\fBscf_iter_t *\fR\fIiter\fR,
  56      \fBconst scf_service_t *\fR\fIparent\fR);
  57 .fi
  58
  59 .LP
  60 .nf
  61 \fBint\fR \fBscf_iter_service_pgs\fR(\fBscf_iter_t *\fR\fIiter\fR, \fBconst scf_service_t *\fR\fIparent\fR);
  62 .fi
  63
  64 .LP
  65 .nf
  66 \fBint\fR \fBscf_iter_service_pgs_typed\fR(\fBscf_iter_t *\fR\fIiter\fR,
  67      \fBconst scf_service_t *\fR\fIparent\fR, \fBconst char *\fR\fIpgtype\fR);
  68 .fi
  69
  70 .LP
  71 .nf
  72 \fBint\fR \fBscf_iter_instance_snapshots\fR(\fBscf_iter_t *\fR\fIiter\fR,
  73      \fBconst scf_instance_t *\fR\fIparent\fR);
  74 .fi
  75
  76 .LP
  77 .nf
  78 \fBint\fR \fBscf_iter_snaplevel_pgs\fR(\fBscf_iter_t *\fR\fIiter\fR,
  79      \fBconst scf_snaplevel_t *\fR\fIparent\fR);
  80 .fi
  81
  82 .LP
  83 .nf
  84 \fBint\fR \fBscf_iter_snaplevel_pgs_typed\fR(\fBscf_iter_t *\fR\fIiter\fR,
  85      \fBconst scf_snaplevel_t *\fR\fIparent\fR, \fBconst char *\fR\fIpgtype\fR);
  86 .fi
  87
  88 .LP
  89 .nf
  90 \fBint\fR \fBscf_iter_instance_pgs\fR(\fBscf_iter_t *\fR\fIiter\fR, \fBscf_instance_t *\fR\fIparent\fR);
  91 .fi
  92
  93 .LP
  94 .nf
  95 \fBint\fR \fBscf_iter_instance_pgs_typed\fR(\fBscf_iter_t *\fR\fIiter\fR,
  96      \fBscf_instance_t *\fR\fIparent\fR, \fBconst char *\fR\fIpgtype\fR);
  97 .fi
  98
  99 .LP
 100 .nf
 101 \fBint\fR \fBscf_iter_instance_pgs_composed\fR(\fBscf_iter_t *\fR\fIiter\fR,
 102      \fBconst scf_instance_t *\fR\fIinstance\fR, \fBconst scf_snapshot_t *\fR\fIsnapshot\fR);
 103 .fi
 104
 105 .LP
 106 .nf
 107 \fBint\fR \fBscf_iter_instance_pgs_typed_composed\fR(\fBscf_iter_t *\fR\fIiter\fR,
 108      \fBconst scf_instance_t *\fR\fIinstance\fR, \fBconst scf_snapshot_t *\fR\fIsnapshot\fR,
 109      \fBconst char *\fR\fIpgtype\fR);
 110 .fi
 111
 112 .LP
 113 .nf
 114 \fBint\fR \fBscf_iter_pg_properties\fR(\fBscf_iter_t *\fR\fIiter\fR,
 115      \fBconst scf_propertygroup_t *\fR\fIparent\fR);
 116 .fi
 117
 118 .LP
 119 .nf
 120 \fBint\fR \fBscf_iter_property_values\fR(\fBscf_iter_t *\fR\fIiter\fR,
 121      \fBconst scf_property_t *\fR\fIparent\fR);
 122 .fi
 123
 124 .LP
 125 .nf
 126 \fBint\fR \fBscf_iter_next_scope\fR(\fBscf_iter_t *\fR\fIiter\fR, \fBscf_scope_t *\fR\fIout\fR);
 127 .fi
 128
 129 .LP
 130 .nf
 131 \fBint\fR \fBscf_iter_next_service\fR(\fBscf_iter_t *\fR\fIiter\fR, \fBscf_service_t *\fR\fIout\fR);
 132 .fi
 133
 134 .LP
 135 .nf
 136 \fBint\fR \fBscf_iter_next_instance\fR(\fBscf_iter_t *\fR\fIiter\fR, \fBscf_instance_t *\fR\fIout\fR);
 137 .fi
 138
 139 .LP
 140 .nf
 141 \fBint\fR \fBscf_iter_next_snapshot\fR(\fBscf_iter_t *\fR\fIiter\fR, \fBscf_snapshot_t *\fR\fIout\fR);
 142 .fi
 143
 144 .LP
 145 .nf
 146 \fBint\fR \fBscf_iter_next_pg\fR(\fBscf_iter_t *\fR\fIiter\fR, \fBscf_propertygroup_t  *\fR\fIout\fR);
 147 .fi
 148
 149 .LP
 150 .nf
 151 \fBint\fR \fBscf_iter_next_property\fR(\fBscf_iter_t *\fR\fIiter\fR, \fBscf_property_t *\fR\fIout\fR);
 152 .fi
 153
 154 .LP
 155 .nf
 156 \fBint\fR \fBscf_iter_next_value\fR(\fBscf_iter_t *\fR\fIiter\fR, \fBscf_value_t *\fR\fIout\fR);
 157 .fi
 158
 159 .SH DESCRIPTION
 160 .sp
 161 .LP
 162 The \fBscf_iter_create()\fR function creates a new iterator associated with
 163 \fIhandle\fR. The \fBscf_iter_destroy()\fR function destroys an iteration.
 164 .sp
 165 .LP
 166 The \fBscf_iter_reset()\fR function releases any resources involved with an
 167 active iteration and returns the iterator to its initial state.
 168 .sp
 169 .LP
 170 The \fBscf_iter_handle_scopes()\fR, \fBscf_iter_scope_services()\fR,
 171 \fBscf_iter_service_instances()\fR, \fBscf_iter_instance_snapshots()\fR,
 172 \fBscf_iter_service_pgs()\fR, \fBscf_iter_instance_pgs()\fR,
 173 \fBscf_iter_snaplevel_pgs()\fR, \fBscf_iter_pg_properties()\fR, and
 174 \fBscf_iter_property_values()\fR functions set up a new iteration of all the
 175 children \fIparent\fR of a particular type. The
 176 \fBscf_iter_property_values()\fR function will iterate over values in the order
 177 in which they were specified with \fBscf_entry_add_value\fR(3SCF).
 178 .sp
 179 .LP
 180 The \fBscf_iter_service_pgs_typed()\fR, \fBscf_iter_instance_pgs_typed()\fR,
 181 and \fBscf_iter_snaplevel_pgs_typed()\fR functions iterate over the child
 182 property groups of \fIparent\fR, but restrict them to a particular property
 183 group type.
 184 .sp
 185 .LP
 186 The \fBscf_iter_instance_pgs_composed()\fR function sets up a new iteration of
 187 the composed view of instance's children at the time \fIsnapshot\fR was taken.
 188 If \fIsnapshot\fR is \fINULL\fR, the current properties are used. The composed
 189 view of an instance's properties is the union of the properties of the instance
 190 and its ancestors. Properties of the instance take precedence over properties
 191 of the service with the same name, including property group name. Property
 192 groups retrieved with this iterator might not have \fIinstance\fR as their
 193 parent and properties retrieved from such property groups might not have the
 194 indicated property group as their parent. If \fIinstance\fR and its parent have
 195 property groups with the same name but different types, the properties in the
 196 property group of the parent are excluded. The
 197 \fBscf_iter_instance_pgs_typed_composed()\fR function behaves as
 198 \fBscf_iter_instance_pgs_composed()\fR, except the property groups of the type
 199 \fIpgtype\fR are returned.
 200 .sp
 201 .LP
 202 The \fBscf_iter_next_scope()\fR, \fBscf_iter_next_service()\fR,
 203 \fBscf_iter_next_instance()\fR, \fBscf_iter_next_snapshot()\fR,
 204 \fBscf_iter_next_pg()\fR, \fBscf_iter_next_property()\fR, and
 205 \fBscf_iter_next_value()\fR functions retrieve the next element of the
 206 iteration.
 207 .SH RETURN VALUES
 208 .sp
 209 .LP
 210 Upon successful completion, \fBscf_iter_create()\fR returns a pointer to a new
 211 iterator. Otherwise, it returns \fINULL\fR.
 212 .sp
 213 .LP
 214 Upon successful completion, \fBscf_iter_handle()\fR returns the handle
 215 associated with \fIiter\fR. Otherwise it returns \fINULL\fR.
 216 .sp
 217 .LP
 218 Upon successful completion, \fBscf_iter_handle_scopes()\fR,
 219 \fBscf_iter_scope_services()\fR, \fBscf_iter_service_instances()\fR,
 220 \fBscf_iter_instance_snapshots()\fR, \fBscf_iter_service_pgs()\fR,
 221 \fBscf_iter_instance_pgs()\fR, \fBscf_iter_snaplevel_pgs()\fR,
 222 \fBscf_iter_pg_properties()\fR, \fBscf_iter_property_values()\fR,
 223 \fBscf_iter_service_pgs_typed()\fR, \fBscf_iter_instance_pgs_composed()\fR,
 224 \fBscf_iter_instance_pgs_typed()\fR,
 225 \fBscf_iter_instance_pgs_typed_composed()\fR, and
 226 \fBscf_iter_snaplevel_pgs_typed()\fR return 0. Otherwise, they return -1.
 227 .sp
 228 .LP
 229 Upon successful completion, \fBscf_iter_next_scope()\fR,
 230 \fBscf_iter_next_service()\fR, \fBscf_iter_next_instance()\fR,
 231 \fBscf_iter_next_snapshot()\fR, \fBscf_iter_next_pg()\fR,
 232 \fBscf_iter_next_property()\fR, and \fBscf_iter_next_value()\fR return 1. If
 233 the iterator is complete, they return 0. Otherwise, they return -1.
 234 .SH ERRORS
 235 .sp
 236 .LP
 237 The \fBscf_iter_create()\fR function will fail if:
 238 .sp
 239 .ne 2
 240 .na
 241 \fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
 242 .ad
 243 .RS 30n
 244 The handle argument is NULL.
 245 .RE
 246
 247 .sp
 248 .ne 2
 249 .na
 250 \fB\fBSCF_ERROR_NO_MEMORY\fR\fR
 251 .ad
 252 .RS 30n
 253 There is no memory available.
 254 .RE
 255
 256 .sp
 257 .ne 2
 258 .na
 259 \fB\fBSCF_ERROR_NO_RESOURCES\fR\fR
 260 .ad
 261 .RS 30n
 262 The server does not have adequate resources for a new iteration.
 263 .RE
 264
 265 .sp
 266 .LP
 267 The \fBscf_iter_handle()\fR function will fail if:
 268 .sp
 269 .ne 2
 270 .na
 271 \fB\fBSCF_ERROR_HANDLE_DESTROYED\fR\fR
 272 .ad
 273 .RS 30n
 274 The handle associated with \fIiter\fR has been destroyed.
 275 .RE
 276
 277 .sp
 278 .LP
 279 The \fBscf_iter_next_value()\fR function will fail if:
 280 .sp
 281 .ne 2
 282 .na
 283 \fB\fBSCF_ERROR_PERMISSION_DENIED\fR\fR
 284 .ad
 285 .sp .6
 286 .RS 4n
 287 The value could not be read due to access restrictions.
 288 .RE
 289
 290 .sp
 291 .LP
 292 The \fBscf_iter_handle_scopes()\fR, \fBscf_iter_scope_services()\fR,
 293 \fBscf_iter_service_instances()\fR, \fBscf_iter_instance_snapshots()\fR,
 294 \fBscf_iter_service_pgs()\fR, \fBscf_iter_instance_pgs()\fR,
 295 \fBscf_iter_instance_pgs_composed()\fR, \fBscf_iter_snaplevel_pgs()\fR,
 296 \fBscf_iter_pg_properties()\fR, \fBscf_iter_property_values()\fR,
 297 \fBscf_iter_service_pgs_typed()\fR, \fBscf_iter_instance_pgs_typed()\fR,
 298 \fBscf_iter_instance_pgs_typed_composed()\fR, and
 299 \fBscf_iter_snaplevel_pgs_typed()\fR functions will fail if:
 300 .sp
 301 .ne 2
 302 .na
 303 \fB\fBSCF_ERROR_DELETED\fR\fR
 304 .ad
 305 .sp .6
 306 .RS 4n
 307 The parent has been deleted.
 308 .RE
 309
 310 .sp
 311 .ne 2
 312 .na
 313 \fB\fBSCF_ERROR_NOT_SET\fR\fR
 314 .ad
 315 .sp .6
 316 .RS 4n
 317 The parent is not set.
 318 .RE
 319
 320 .sp
 321 .ne 2
 322 .na
 323 \fB\fBSCF_ERROR_NOT_BOUND\fR\fR
 324 .ad
 325 .sp .6
 326 .RS 4n
 327 The handle is not bound.
 328 .RE
 329
 330 .sp
 331 .ne 2
 332 .na
 333 \fB\fBSCF_ERROR_CONNECTION_BROKEN\fR\fR
 334 .ad
 335 .sp .6
 336 .RS 4n
 337 The connection to the repository was lost.
 338 .RE
 339
 340 .sp
 341 .ne 2
 342 .na
 343 \fB\fBSCF_ERROR_HANDLE_MISMATCH\fR\fR
 344 .ad
 345 .sp .6
 346 .RS 4n
 347 The \fIiter\fR and \fIparent\fR arguments are not derived from the same handle.
 348 .RE
 349
 350 .sp
 351 .LP
 352 The \fBscf_iter_service_pgs_typed()\fR, \fBscf_iter_instance_pgs_typed()\fR,
 353 \fBscf_iter_instance_pgs_typed_composed()\fR, and
 354 \fBscf_iter_snaplevel_pgs_typed()\fR functions will fail if:
 355 .sp
 356 .ne 2
 357 .na
 358 \fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
 359 .ad
 360 .RS 30n
 361 The \fIpgtype\fR argument is not a valid property group type.
 362 .RE
 363
 364 .sp
 365 .LP
 366 The \fBscf_iter_next_service()\fR, \fBscf_iter_next_instance()\fR,
 367 \fBscf_iter_next_snapshot()\fR, \fBscf_iter_next_pg()\fR,
 368 \fBscf_iter_next_property()\fR, and \fBscf_iter_next_value()\fR functions will
 369 fail if:
 370 .sp
 371 .ne 2
 372 .na
 373 \fB\fBSCF_ERROR_DELETED\fR\fR
 374 .ad
 375 .RS 21n
 376 The parent the iterator is attached to has been deleted.
 377 .RE
 378
 379 .sp
 380 .LP
 381 The \fBscf_iter_next_scope()\fR, \fBscf_iter_next_service()\fR,
 382 \fBscf_iter_next_instance()\fR, \fBscf_iter_next_snapshot()\fR,
 383 \fBscf_iter_next_pg()\fR,\fBscf_iter_next_property()\fR, and
 384 \fBscf_iter_next_value()\fR functions will fail if:
 385 .sp
 386 .ne 2
 387 .na
 388 \fB\fBSCF_ERROR_NOT_SET\fR\fR
 389 .ad
 390 .sp .6
 391 .RS 4n
 392 The iterator is not set.
 393 .RE
 394
 395 .sp
 396 .ne 2
 397 .na
 398 \fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
 399 .ad
 400 .sp .6
 401 .RS 4n
 402 The requested object type does not match the type the iterator is walking.
 403 .RE
 404
 405 .sp
 406 .ne 2
 407 .na
 408 \fB\fBSCF_ERROR_NOT_BOUND\fR\fR
 409 .ad
 410 .sp .6
 411 .RS 4n
 412 The handle is not bound.
 413 .RE
 414
 415 .sp
 416 .ne 2
 417 .na
 418 \fB\fBSCF_ERROR_HANDLE_MISMATCH\fR\fR
 419 .ad
 420 .sp .6
 421 .RS 4n
 422 The \fIiter\fR and \fIparent\fR arguments are not derived from the same handle.
 423 .RE
 424
 425 .sp
 426 .ne 2
 427 .na
 428 \fB\fBSCF_ERROR_CONNECTION_BROKEN\fR\fR
 429 .ad
 430 .sp .6
 431 .RS 4n
 432 The connection to the repository was lost.
 433 .RE
 434
 435 .sp
 436 .LP
 437 The \fBscf_iter_scope_services()\fR, \fBscf_iter_service_instances()\fR,
 438 \fBscf_iter_service_pgs()\fR, \fBscf_iter_instance_snapshots()\fR,
 439 \fBscf_iter_instance_pgs()\fR, \fBscf_iter_instance_pgs_composed()\fR,
 440 \fBscf_iter_snaplevel_pgs()\fR, \fBscf_iter_pg_properties()\fR,
 441 \fBscf_iter_property_values()\fR, \fBscf_iter_service_pgs_typed()\fR,
 442 \fBscf_iter_instance_pgs_typed()\fR,
 443 \fBscf_iter_instance_pgs_typed_composed()\fR,
 444 \fBscf_iter_snaplevel_pgs_typed()\fR, \fBscf_iter_next_service()\fR,
 445 \fBscf_iter_next_instance()\fR, \fBscf_iter_next_snapshot()\fR,
 446 \fBscf_iter_next_pg()\fR, and \fBscf_iter_next_property()\fR functions will
 447 fail if:
 448 .sp
 449 .ne 2
 450 .na
 451 \fB\fBSCF_ERROR_NO_RESOURCES\fR\fR
 452 .ad
 453 .RS 26n
 454 The server does not have the resources to complete the request.
 455 .RE
 456
 457 .sp
 458 .LP
 459 The \fBscf_error\fR(3SCF) function can be used to retrieve the error value.
 460 .SH EXAMPLES
 461 .LP
 462 \fBExample 1 \fRIterate over all instances under a service.
 463 .sp
 464 .in +2
 465 .nf
 466 scf_iter_t *iter = scf_iter_create(handle);
 467
 468 if (iter == NULL || scf_iter_service_instances(iter, parent) == -1) {
 469      /* failure */
 470 }
 471 while ((r = scf_iter_next_instance(iter, child)) > 0) {
 472      /* process child */
 473 }
 474 if (r < 0) {
 475      /* failure */
 476 }
 477 scf_iter_destroy(iter);
 478 .fi
 479 .in -2
 480
 481 .LP
 482 \fBExample 2 \fRConnect to the repository, walk all services and instances and
 483 print their FMRIs.
 484 .sp
 485 .in +2
 486 .nf
 487 scf_handle_t *handle = scf_handle_create(SCF_VERSION);
 488 scf_scope_t *scope = scf_scope_create(handle);
 489 scf_service_t *svc = scf_service_create(handle);
 490 scf_instance_t *inst = scf_instance_create(handle);
 491 scf_iter_t *svc_iter = scf_iter_create(handle);
 492 scf_iter_t *inst_iter = scf_iter_create(handle);
 493
 494 size_t sz = scf_limit(SCF_LIMIT_MAX_FMRI_LENGTH) + 1;
 495 char *fmri = malloc(sz + 1);
 496
 497 int r;
 498
 499 if (handle == NULL || scope == NULL || svc == NULL ||
 500      inst == NULL || svc_iter == NULL || inst_iter == NULL ||
 501      fmri == NULL) {
 502          /* failure */
 503 }
 504 if (scf_handle_bind(handle) == -1 ||
 505      scf_handle_get_scope(handle, SCF_SCOPE_LOCAL, scope) == -1 ||
 506      scf_iter_scope_services(svc_iter, scope) == -1) {
 507           /* failure */
 508 }
 509 while ((r = scf_iter_next_service(svc_iter, svc)) > 0) {
 510      if (scf_service_to_fmri(svc, fmri, sz) < 0) {
 511           /* failure */
 512      }
 513      puts(fmri);
 514      if (scf_iter_service_instances(inst_iter, svc) < 0) {
 515           /* failure */
 516      }
 517      while ((r = scf_iter_next_instance(inst_iter, inst)) > 0) {
 518           if (scf_instance_to_fmri(inst, fmri, sz) < 0) {
 519                /* failure */
 520           }
 521           puts(fmri);
 522      }
 523      if (r < 0)
 524           break;
 525 }
 526 if (r < 0) {
 527      /* failure */
 528 }
 529
 530 scf_handle_destroy(handle);
 531 scf_scope_destroy(scope);
 532 scf_service_destroy(svc);
 533 scf_instance_destroy(inst);
 534 scf_iter_destroy(svc_iter);
 535 scf_iter_destroy(inst_iter);
 536 .fi
 537 .in -2
 538
 539 .SH ATTRIBUTES
 540 .sp
 541 .LP
 542 See \fBattributes\fR(5) for descriptions of the following attributes:
 543 .sp
 544
 545 .sp
 546 .TS
 547 box;
 548 c | c
 549 l | l .
 550 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 551 _
 552 Interface Stability     Committed
 553 _
 554 MT-Level        Safe
 555 .TE
 556
 557 .SH SEE ALSO
 558 .sp
 559 .LP
 560 \fBlibscf\fR(3LIB), \fBscf_entry_add_value\fR(3SCF), \fBscf_error\fR(3SCF),
 561 \fBscf_handle_create\fR(3SCF), \fBattributes\fR(5)