Hallo, dies ist ein Test.

PWD: /www/data-lst1/unixsoft/unixsoft/kaempfer/.public_html

Running in File Mode
Relative path: ./../../../../../../usr/man/man3scf/scf_iter_create.3scf
Real path: /usr/share/man/man3scf/scf_iter_create.3scf
Zurück

'\" te .\" Copyright (c) 2016, 2017, Oracle and/or its affiliates. All rights reserved. .TH scf_iter_create 3SCF "14 Aug 2017" "Oracle Solaris 11.4" "Service Configuration Facility Library Functions" .SH NAME scf_iter_create, scf_iter_handle, scf_iter_destroy, scf_iter_reset, scf_iter_handle_scopes, scf_iter_scope_services, scf_iter_service_instances, scf_iter_service_pgs, scf_iter_service_pgs_typed, scf_iter_instance_snapshots, scf_iter_snaplevel_pgs, scf_iter_snaplevel_pgs_typed, scf_iter_instance_pgs, scf_iter_instance_pgs_typed, scf_iter_instance_pgs_composed, scf_iter_instance_pgs_typed_composed, scf_iter_pg_pgs, scf_iter_pg_pgs_typed, scf_iter_pg_pgs_composed, scf_iter_pg_pgs_typed_composed, scf_iter_pg_properties, scf_iter_property_values, scf_iter_next_scope, scf_iter_next_service, scf_iter_next_instance, scf_iter_next_snapshot, scf_iter_next_pg, scf_iter_next_property, scf_iter_next_value \- iterate through the Service Configuration Facility repository .SH SYNOPSIS .LP .nf cc [ flag... ] file... -lscf [ library... ] #include <libscf.h> .fi .LP .nf scf_iter_t *scf_iter_create(scf_handle_t *handle); .fi .LP .nf scf_handle_t *scf_iter_handle(scf_iter_t *iter); .fi .LP .nf void scf_iter_destroy(scf_iter_t *iter); .fi .LP .nf void scf_iter_reset(scf_iter_t *iter); .fi .LP .nf int scf_iter_handle_scopes(scf_iter_t *iter, const scf_handle_t *h); .fi .LP .nf int scf_iter_scope_services(scf_iter_t *iter, const scf_scope_t *parent); .fi .LP .nf int scf_iter_service_instances(scf_iter_t *iter, const scf_service_t *parent); .fi .LP .nf int scf_iter_service_pgs(scf_iter_t *iter, const scf_service_t *parent); .fi .LP .nf int scf_iter_service_pgs_typed(scf_iter_t *iter, const scf_service_t *parent, const char *pgtype); .fi .LP .nf int scf_iter_instance_snapshots(scf_iter_t *iter, const scf_instance_t *parent); .fi .LP .nf int scf_iter_snaplevel_pgs(scf_iter_t *iter, const scf_snaplevel_t *parent); .fi .LP .nf int scf_iter_snaplevel_pgs_typed(scf_iter_t *iter, const scf_snaplevel_t *parent, const char *pgtype); .fi .LP .nf int scf_iter_instance_pgs(scf_iter_t *iter, scf_instance_t *parent); .fi .LP .nf int scf_iter_instance_pgs_typed(scf_iter_t *iter, scf_instance_t *parent, const char *pgtype); .fi .LP .nf int scf_iter_instance_pgs_composed(scf_iter_t *iter, const scf_instance_t *instance, const scf_snapshot_t *snapshot); .fi .LP .nf int scf_iter_instance_pgs_typed_composed(scf_iter_t *iter, const scf_instance_t *instance, const scf_snapshot_t *snapshot, const char *pgtype); .fi .LP .nf int scf_iter_pg_pgs(scf_iter_t *iter, scf_propertygroup_t *pg); .fi .LP .nf int scf_iter_pg_pgs_typed(scf_iter_t *iter, scf_propertygroup_t *pg, const char *pgtype); .fi .LP .nf int scf_iter_pg_pgs_composed(scf_iter_t *iter, scf_propertygroup_t *pg, scf_snapshot_t *snapshot); .fi .LP .nf int scf_iter_pg_pgs_typed_composed(scf_iter_t *iter, scf_propertygroup_t *pg, scf_snapshot_t *snapshot, const char *pgtype); .fi .LP .nf int scf_iter_pg_properties(scf_iter_t *iter, const scf_propertygroup_t *parent); .fi .LP .nf int scf_iter_property_values(scf_iter_t *iter, const scf_property_t *parent); .fi .LP .nf int scf_iter_next_scope(scf_iter_t *iter, scf_scope_t *out); .fi .LP .nf int scf_iter_next_service(scf_iter_t *iter, scf_service_t *out); .fi .LP .nf int scf_iter_next_instance(scf_iter_t *iter, scf_instance_t *out); .fi .LP .nf int scf_iter_next_snapshot(scf_iter_t *iter, scf_snapshot_t *out); .fi .LP .nf int scf_iter_next_pg(scf_iter_t *iter, scf_propertygroup_t *out); .fi .LP .nf int scf_iter_next_property(scf_iter_t *iter, scf_property_t *out); .fi .LP .nf int scf_iter_next_value(scf_iter_t *iter, scf_value_t *out); .fi .SH DESCRIPTION .sp .LP The \fBscf_iter_create()\fR function creates a new iterator associated with \fBhandle\fR. .sp .LP The \fBscf_iter_destroy()\fR function destroys an iteration. The \fBscf_error()\fR function is not modified by this call. .sp .LP The \fBscf_iter_reset()\fR function releases any resources involved with an active iteration, and returns the iterator to its initial state. .sp .LP The \fBscf_iter_handle_scopes()\fR, \fBscf_iter_scope_services()\fR, \fBscf_iter_service_instances()\fR, \fBscf_iter_instance_snapshots()\fR, \fBscf_iter_service_pgs()\fR, \fBscf_iter_instance_pgs()\fR, \fBscf_iter_pg_pgs()\fR, \fBscf_iter_snaplevel_pgs()\fR, \fBscf_iter_pg_properties()\fR, and \fBscf_iter_property_values()\fR functions each set up a new iteration. .sp .LP The \fBscf_iter_handle_scopes()\fR function sets up an iterator of all scopes for a given handle. .sp .LP The \fBscf_iter_scope_services()\fR function sets up an iterator of all services for a given scope. .sp .LP The \fBscf_iter_service_instances()\fR function sets up an iterator of all instances for a given service. .sp .LP The \fBscf_iter_instance_snapshots()\fR function sets up an iterator of all snapshots for a given instance. .sp .LP The \fBscf_iter_service_pgs()\fR function sets up an iterator of all property groups for a given service. .sp .LP The \fBscf_iter_instance_pgs()\fR function sets up an iterator of all property groups for a given instance. .sp .LP The \fBscf_iter_pg_pgs()\fR function sets up an iterator of all property groups that directly parented by the given property group. Therefore, only those property groups at the next level are considered. .sp .LP The \fBscf_iter_pg_properties()\fR function sets up an iterator of all properties for a given property group. .sp .LP The \fBscf_iter_property_values()\fR function sets up an iterator of all values for a given property (in the order in which they are specified with \fBscf_entry_add_value\fR(3SCF)). .sp .LP The \fBscf_iter_service_pgs_typed()\fR, \fBscf_iter_instance_pgs_typed()\fR, \fBscf_iter_pg_pgs_typed()\fR, and \fBscf_iter_snaplevel_pgs_typed()\fR functions iterate over the child property groups of the parent, but restrict them to a particular property group type. The \fBscf_iter_pg_pgs_typed()\fR function will iterate over the property groups directly parented by the given property group. Therefore, only those property groups at the next level are considered. .sp .LP The \fBscf_iter_instance_pgs_composed()\fR and \fBscf_iter_pg_pgs_composed()\fR functions set up a new iteration of the composed view of an instance or a property group's children at the time the snapshot is taken. If the snapshot is \fBNULL\fR, the current properties are used. .sp .LP The composed view of properties is the union of properties of the instance and its ancestors within any given property group. Properties of the instance take precedence over properties of the service with the same name and ancestry. Properties and property groups retrieved with this iterator might not have the instance as their ancestor if they exist only in the service. If the instance and its parent have property groups with the same name but different types, the properties in the property group of the parent are excluded. .sp .LP The \fBscf_iter_instance_pgs_typed_composed()\fR and \fBscf_iter_pg_pgs_typed_composed()\fR functions behave as \fBscf_iter_instance_pgs_composed()\fR and \fBscf_iter_pg_pgs_composed()\fR respectively, except only the property groups of the type \fBpgtype\fR are returned. The \fBscf_iter_pg_pgs_composed()\fR and \fBscf_iter_pg_pgs_typed_composed()\fR functions will iterate over the property groups directly parented by the given property group. Therefore, only those property groups at the next level are considered. .sp .LP The \fBscf_iter_next_scope()\fR, \fBscf_iter_next_service()\fR, \fBscf_iter_next_instance()\fR, \fBscf_iter_next_snapshot()\fR, \fBscf_iter_next_pg()\fR, \fBscf_iter_next_property()\fR, and \fBscf_iter_next_value()\fR functions retrieve the next element of the iteration. .SH RETURN VALUES .sp .LP Upon successful completion, the \fBscf_iter_create()\fR function returns a pointer to a new iterator. Otherwise, it returns \fBNULL\fR. .sp .LP Upon successful completion, the \fBscf_iter_handle()\fR function returns the \fBhandle\fR associated with \fBiter\fR. Otherwise, it returns \fBNULL\fR. .sp .LP Upon successful completion, the \fBscf_iter_handle_scopes()\fR, \fBscf_iter_scope_services()\fR, \fBscf_iter_service_instances()\fR, \fBscf_iter_instance_snapshots()\fR, \fBscf_iter_service_pgs()\fR, \fBscf_iter_instance_pgs()\fR, \fBscf_iter_pg_pgs()\fR, \fBscf_iter_snaplevel_pgs()\fR, \fBscf_iter_pg_properties()\fR, \fBscf_iter_property_values()\fR, \fBscf_iter_service_pgs_typed()\fR, \fBscf_iter_instance_pgs_composed()\fR, \fBscf_iter_instance_pgs_typed()\fR, \fBscf_iter_instance_pgs_typed_composed()\fR, \fBscf_iter_pg_pgs_typed()\fR, \fBscf_iter_pg_pgs_composed()\fR, \fBscf_iter_pg_pgs_typed_composed()\fR, and \fBscf_iter_snaplevel_pgs_typed()\fR functions return \fB0\fR. Otherwise, they return \fB-1\fR. .sp .LP Upon successful completion, the \fBscf_iter_next_scope()\fR, \fBscf_iter_next_service()\fR, \fBscf_iter_next_instance()\fR, \fBscf_iter_next_snapshot()\fR, \fBscf_iter_next_pg()\fR, \fBscf_iter_next_property()\fR, and \fBscf_iter_next_value()\fR functions return \fB1\fR. If the iterator is complete, the functions return \fB0\fR. Otherwise, they return \fB-1\fR. .SH ERRORS .sp .LP The \fBscf_iter_create()\fR function will fail if: .sp .ne 2 .mk .na \fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR .ad .RS 30n .rt The handle argument is \fBNULL\fR. .RE .sp .ne 2 .mk .na \fB\fBSCF_ERROR_NO_MEMORY\fR\fR .ad .RS 30n .rt There is no memory available. .RE .sp .ne 2 .mk .na \fB\fBSCF_ERROR_NO_RESOURCES\fR\fR .ad .RS 30n .rt The server does not have adequate resources for a new iteration. .RE .sp .LP The \fBscf_iter_handle()\fR function will fail if: .sp .ne 2 .mk .na \fB\fBSCF_ERROR_HANDLE_DESTROYED\fR\fR .ad .RS 30n .rt The handle associated with \fBiter\fR is destroyed. .RE .sp .LP The \fBscf_iter_next_value()\fR function will fail if: .sp .ne 2 .mk .na \fB\fBSCF_ERROR_PERMISSION_DENIED\fR\fR .ad .br .sp .6 .RS 4n The value cannot be read due to access restrictions. .RE .sp .LP The \fBscf_iter_handle_scopes()\fR, \fBscf_iter_scope_services()\fR, \fBscf_iter_service_instances()\fR, \fBscf_iter_instance_snapshots()\fR, \fBscf_iter_service_pgs()\fR, \fBscf_iter_instance_pgs()\fR, \fBscf_iter_instance_pgs_composed()\fR, \fBscf_iter_pg_pgs()\fR, \fBscf_iter_pg_pgs_composed()\fR, \fBscf_iter_snaplevel_pgs()\fR, \fBscf_iter_pg_properties()\fR, \fBscf_iter_property_values()\fR, \fBscf_iter_service_pgs_typed()\fR, \fBscf_iter_instance_pgs_typed()\fR, \fBscf_iter_instance_pgs_typed_composed()\fR, \fBscf_iter_pg_pgs_typed()\fR, \fBscf_iter_pg_pgs_typed_composed()\fR, and \fBscf_iter_snaplevel_pgs_typed()\fR functions will fail if: .sp .ne 2 .mk .na \fB\fBSCF_ERROR_DELETED\fR\fR .ad .br .sp .6 .RS 4n The parent is deleted. .RE .sp .ne 2 .mk .na \fB\fBSCF_ERROR_NOT_SET\fR\fR .ad .br .sp .6 .RS 4n The parent is not set. .RE .sp .ne 2 .mk .na \fB\fBSCF_ERROR_NOT_BOUND\fR\fR .ad .br .sp .6 .RS 4n The \fBhandle\fR is not bound. .RE .sp .ne 2 .mk .na \fB\fBSCF_ERROR_CONNECTION_BROKEN\fR\fR .ad .br .sp .6 .RS 4n The connection to the repository is lost. .RE .sp .ne 2 .mk .na \fB\fBSCF_ERROR_HANDLE_MISMATCH\fR\fR .ad .br .sp .6 .RS 4n The \fBiter\fR and \fBparent\fR arguments are not derived from the same \fBhandle\fR. .RE .sp .LP The \fBscf_iter_service_pgs_typed()\fR, \fBscf_iter_instance_pgs_typed()\fR, \fBscf_iter_instance_pgs_typed_composed()\fR, \fBscf_iter_pg_pgs_typed()\fR, \fBscf_iter_pg_pgs_typed_composed()\fR, and \fBscf_iter_snaplevel_pgs_typed()\fR functions will fail if: .sp .ne 2 .mk .na \fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR .ad .RS 30n .rt The \fBpgtype\fR argument is not a valid property group type. .RE .sp .LP The \fBscf_iter_next_service()\fR, \fBscf_iter_next_instance()\fR, \fBscf_iter_next_snapshot()\fR, \fBscf_iter_next_pg()\fR, \fBscf_iter_next_property()\fR, and \fBscf_iter_next_value()\fR functions will fail if: .sp .ne 2 .mk .na \fB\fBSCF_ERROR_DELETED\fR\fR .ad .RS 21n .rt The parent that the iterator is attached to, is deleted. .RE .sp .LP The \fBscf_iter_next_scope()\fR, \fBscf_iter_next_service()\fR, \fBscf_iter_next_instance()\fR, \fBscf_iter_next_snapshot()\fR, \fBscf_iter_next_pg()\fR, \fBscf_iter_next_property()\fR, and \fBscf_iter_next_value()\fR functions will fail if: .sp .ne 2 .mk .na \fB\fBSCF_ERROR_NOT_SET\fR\fR .ad .br .sp .6 .RS 4n The iterator is not set. .RE .sp .ne 2 .mk .na \fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR .ad .br .sp .6 .RS 4n The requested object type does not match the type the iterator is walking. .RE .sp .ne 2 .mk .na \fB\fBSCF_ERROR_NOT_BOUND\fR\fR .ad .br .sp .6 .RS 4n The handle is not bound. .RE .sp .ne 2 .mk .na \fB\fBSCF_ERROR_HANDLE_MISMATCH\fR\fR .ad .br .sp .6 .RS 4n The \fBiter\fR and \fBparent\fR arguments are not derived from the same handle. .RE .sp .ne 2 .mk .na \fB\fBSCF_ERROR_CONNECTION_BROKEN\fR\fR .ad .br .sp .6 .RS 4n The connection to the repository is lost. .RE .sp .LP The \fBscf_iter_scope_services()\fR, \fBscf_iter_service_instances()\fR, \fBscf_iter_service_pgs()\fR, \fBscf_iter_instance_snapshots()\fR, \fBscf_iter_instance_snapshots()\fR, \fBscf_iter_instance_pgs_composed()\fR, \fBscf_iter_pg_pgs()\fR, \fBscf_iter_pg_pgs_composed()\fR, \fBscf_iter_snaplevel_pgs()\fR, \fBscf_iter_pg_properties()\fR, \fBscf_iter_property_values()\fR, \fBscf_iter_service_pgs_typed()\fR, \fBscf_iter_instance_pgs_typed()\fR, \fBscf_iter_instance_pgs_typed_composed()\fR, \fBscf_iter_pg_pgs_typed()\fR, \fBscf_iter_pg_pgs_typed_composed()\fR, \fBscf_iter_snaplevel_pgs_typed()\fR, \fBscf_iter_next_service()\fR, \fBscf_iter_next_instance()\fR, \fBscf_iter_next_snapshot()\fR, \fBscf_iter_next_pg()\fR, and \fBscf_iter_next_property()\fR functions will fail if: .sp .ne 2 .mk .na \fB\fBSCF_ERROR_NO_RESOURCES\fR\fR .ad .RS 26n .rt The server does not have the resources to complete the request. .RE .sp .LP The \fBscf_error\fR(3SCF) function can be used to retrieve the error value. .SH EXAMPLES .LP \fBExample 1\fR Iterate Overall Instances Under a Service. .sp .in +2 .nf scf_iter_t *iter = scf_iter_create(handle); if (iter == NULL || scf_iter_service_instances(iter, parent) == -1) { /* failure */ } while ((r = scf_iter_next_instance(iter, child)) > 0) { /* process child */ } if (r < 0) { /* failure */ } scf_iter_destroy(iter); .fi .in -2 .sp .LP \fBExample 2\fR Connect to the Repository, \fBwalk\fR all Services and Instances and Print their FMRIs. .sp .in +2 .nf scf_handle_t *handle = scf_handle_create(SCF_VERSION); scf_scope_t *scope = scf_scope_create(handle); scf_service_t *svc = scf_service_create(handle); scf_instance_t *inst = scf_instance_create(handle); scf_iter_t *svc_iter = scf_iter_create(handle); scf_iter_t *inst_iter = scf_iter_create(handle); size_t sz = scf_limit(SCF_LIMIT_MAX_FMRI_LENGTH) + 1; char *fmri = malloc(sz + 1); int r; if (handle == NULL || scope == NULL || svc == NULL || inst == NULL || svc_iter == NULL || inst_iter == NULL || fmri == NULL) { /* failure */ } if (scf_handle_bind(handle) == -1 || scf_handle_get_scope(handle, SCF_SCOPE_LOCAL, scope) == -1 || scf_iter_scope_services(svc_iter, scope) ==-1) { /* failure */ } while ((r = scf_iter_next_service(svc_iter, svc)) > 0) { if (scf_service_to_fmri(svc, fmri, sz) < 0) { /* failure */ } puts(fmri); if (scf_iter_service_instances(inst_iter, svc) < 0) { /* failure */ } while ((r = scf_iter_next_instance(inst_iter, inst)) > 0) { if (scf_instance_to_fmri(inst, fmri, sz) < 0) { /* failure */ } puts(fmri); } if (r < 0) break; } if (r < 0) { /* failure */ } scf_handle_destroy(handle); scf_scope_destroy(scope); scf_service_destroy(svc); scf_instance_destroy(inst); scf_iter_destroy(svc_iter); scf_iter_destroy(inst_iter); .fi .in -2 .sp .LP \fBExample 3\fR \fBwalk\fR All Property Groups and Print their FMRIs. .sp .in +2 .nf int print_all_pgs(scf_handle_t *h, scf_propertygroup_t *parent_pg) { scf_iter_t *iter = NULL; scf_propertygroup_t *pg = NULL; if (((pg = scf_pg_create(h)) == NULL) || ((iter = scf_iter_create(h)) == NULL)) /* failure */ } /* this fails when there are no child pgs, so return */ if (scf_iter_pg_pgs(iter, parent_pg, NULL) != 0) return (0); while (scf_iter_next_pg(iter, pg) > 0) { size_t sz = scf_limit(SCF_LIMIT_MAX_FMRI_LENGTH) + 1; char *fmri = malloc(sz + 1); if (scf_pg_to_fmri(pg, fmri, sz) < 0) /* failure */ puts(fmri); if (print_all_pgs(h, pg) != 0) /* failure */ free(fmri); } scf_pg_destroy(pg); scf_iter_destroy(iter); return (0); } .fi .in -2 .sp .SH ATTRIBUTES .sp .LP See \fBattributes\fR(7) for descriptions of the following attributes: .sp .TS tab( ) box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) . ATTRIBUTE TYPE ATTRIBUTE VALUE _ Interface Stability Committed _ MT-Level Safe .TE .sp .SH SEE ALSO .sp .LP \fBlibscf\fR(3LIB), \fBscf_entry_add_value\fR(3SCF), \fBscf_error\fR(3SCF), \fBscf_handle_create\fR(3SCF), \fBattributes\fR(7)