scf_tmpl_get_by_pg(3scf)

1scf_tmpl_pg_creaSteer(v3iScCeF)Configuration Facility Library Fsucnfc_ttimopnls_pg_create(3SCF)
2
3
4

NAME

6       scf_tmpl_pg_create,       scf_tmpl_pg_reset,       scf_tmpl_pg_destroy,
7       scf_tmpl_get_by_pg_name, scf_tmpl_get_by_pg, scf_tmpl_iter_pgs  -  tem‐
8       plate property group functions
9

SYNOPSIS

11       cc [ flag... ] file... -lscf [ library... ]
12       #include <libscf.h>
13
14       scf_pg_tmpl_t *scf_tmpl_pg_create(scf_handle_t *handle);
15
16
17       void scf_tmpl_pg_reset(scf_pg_tmpl_t *pg_tmpl);
18
19
20       void scf_tmpl_pg_destroy(scf_pg_tmpl_t *pg_tmpl);
21
22
23       int scf_tmpl_get_by_pg_name(const char *instance_fmri,
24            const char *snapshot, const char *pg_name,
25            const char *pg_type, scf_pg_tmpl_t *pg_tmpl, int flags);
26
27
28       int scf_tmpl_get_by_pg(scf_propertygroup_t *pg,
29            scf_pg_tmpl_t *pg_tmpl, int flags)
30
31
32       int scf_tmpl_iter_pgs(scf_pg_tmpl_t *pg_tmpl, const char *fmri,
33            const char *snapshot, const char *pg_type, int flags);
34
35

DESCRIPTION

37       The  template  property group functions locate and give access to meta‐
38       data about SMF configuration for service instances. They  are  used  to
39       directly  access property group metadata and explore metadata for prop‐
40       erties contained in those property groups.
41
42
43       A property group does not need to be  currently  defined  in  order  to
44       explore  metadata  about it, as long as the metadata is defined.  Thus,
45       the property group template functions operate on  strings  rather  than
46       scf_propertygroup_t entities.
47
48
49       By     default,     when     an    instance    FMRI    is    specified,
50       scf_tmpl_get_by_pg_name() and scf_tmpl_iter_pgs() lookup composed  data
51       from  the running snapshot of the instance. A different snapshot may be
52       explicitly selected by specifying a valid  snapshot  name  rather  than
53       NULL  for  the  snapshot  argument. If a service FMRI is specified, the
54       current properties are used.
55
56
57       By default, these functions also explore template data defined  by  the
58       service  or  instance  itself, the service's restarter, and global tem‐
59       plate data. See smf_template(5) for more information about this  compo‐
60       sition.
61
62
63       Once   retrieved,   the   scf_pg_tmpl_t   can  be  explored  using  the
64       scf_tmpl_pg_name(3SCF) and scf_tmpl_prop_create(3SCF)  suite  of  func‐
65       tions.
66
67
68       Before   calling  scf_tmpl_get_by_pg(),  scf_tmpl_get_by_pg_name(),  or
69       scf_tmpl_iter_pgs(),   the   scf_pg_tmpl_t   must   be   allocated   by
70       scf_tmpl_pg_create(). The scf_pg_tmpl_t can be reset to contain no tem‐
71       plate information with scf_tmpl_pg_reset(), so that it can be  used  to
72       start  an  iteration  from  scratch. All associated memory can be freed
73       with scf_tmpl_pg_destroy().
74
75
76       The scf_tmpl_get_by_pg() function locates the  most  specific  matching
77       template  for  the property group supplied. The parent of that property
78       group can be either a service or an instance.
79
80
81       The scf_tmpl_get_by_pg_name() function locates the most specific match‐
82       ing  template  for the property group as specified. As described above,
83       when  the snapshot argument is NULL the  default  running  snapshot  is
84       used. If flags includes SCF_PG_TMPL_FLAG_CURRENT, the snapshot argument
85       is ignored and the current configuration is  used.  If  flags  includes
86       SCF_PG_TMPL_FLAG_EXACT,  only  the  exact  FMRI is looked up. Either or
87       both of the pg_name and pg_type arguments may be specified as NULL.  In
88       this  case, pg_name and/or pg_type is wildcarded and matches any value.
89       The most specific snapshot matching those arguments is returned.
90
91
92       The scf_tmpl_iter_pgs() function iterates across all templates  defined
93       for  the specified FMRI, snapshot, and optional property group type. It
94       also  takes   an   optional   flags   argument.   If   flags   includes
95       SCF_PG_TMPL_FLAG_CURRENT,  the  snapshot  argument  is  ignored and the
96       "running" snapshot is used. SCF_PG_TMPL_FLAG_REQUIRED searches only for
97       required  property  groups.  SCF_PG_TMPL_FLAG_EXACT  looks  only at the
98       exact FMRI provided for templates, and not for templates defined on its
99       restarter or globally.
100
101
102       The  iterator  state  for scf_tmpl_iter_pgs() is stored on the template
103       data  structure.  The  data  structure   should   be   allocated   with
104       scf_tmpl_pg_create()  and  to  continue  the  iteration  the previously
105       returned structure should be passed in as an argument.
106

RETURN VALUES

108       The scf_tmpl_pg_create() function returns NULL on failure and a pointer
109       to  an  allocated and populated scf_pg_tmpl_t on success. The caller is
110       responsible for freeing the memory with scf_tmpl_pg_destroy().
111
112
113       The scf_tmpl_get_by_pg() and scf_tmpl_get_by_pg_name() functions return
114       0 on success and -1 on failure.
115
116
117       The scf_tmpl_iter_pgs() function returns 1 on successful completion. If
118       the iteration is complete, it returns 0. It returns -1 on error.
119

ERRORS

121       The      scf_tmpl_get_by_pg(),      scf_tmpl_get_by_pg_name(),      and
122       scf_tmpl_iter_pgs() functions will fail if:
123
124       SCF_ERROR_BACKEND_ACCESS
125
126           The  storage mechanism that the repository server (svc.configd(1M))
127           chose for the operation denied access.
128
129
130       SCF_ERROR_CONNECTION_BROKEN
131
132           The connection to the repository was lost.
133
134
135       SCF_ERROR_DELETED
136
137           The instance or its template property group has been deleted.
138
139
140       SCF_ERROR_HANDLE_DESTROYED
141
142           The handle passed in has been destroyed.
143
144
145       SCF_ERROR_INTERNAL
146
147           An internal error occurred.
148
149
150       SCF_ERROR_INVALID_ARGUMENT
151
152           The handle argument, fmri argument, snapshot name, pg_name,  or  pg
153           is invalid.
154
155
156       SCF_ERROR_NO_MEMORY
157
158           There is not enough memory to populate the scf_pg_tmpl_t.
159
160
161       SCF_ERROR_NO_RESOURCES
162
163           The  server  does  not  have  adequate  resources  to  complete the
164           request.
165
166
167       SCF_ERROR_NOT_BOUND
168
169           The handle is not currently bound.
170
171
172       SCF_ERROR_NOT_FOUND
173
174           The object matching FMRI does not exist in the repository,  or  the
175           snapshot does not exist.
176
177
178       SCF_ERROR_PERMISSION_DENIED
179
180           The template could not be read due to access restrictions.
181
182
183
184       The scf_tmpl_get_by_pg() function will fail if:
185
186       SCF_ERROR_NOT_SET    The property group specified by pg is not set.
187
188
189
190       The scf_tmpl_pg_create() function will fail if:
191
192       SCF_ERROR_INVALID_ARGUMENT    The handle argument is NULL.
193
194
195       SCF_ERROR_NO_MEMORY           There is no memory available.
196
197

ATTRIBUTES

199       See attributes(5) for descriptions of the following attributes:
200
201
202
203
204       ┌─────────────────────────────┬─────────────────────────────┐
205       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
206       ├─────────────────────────────┼─────────────────────────────┤
207       │Interface Stability          │Committed                    │
208       ├─────────────────────────────┼─────────────────────────────┤
209       │MT-Level                     │Safe                         │
210       └─────────────────────────────┴─────────────────────────────┘
211

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES

ERRORS

ATTRIBUTES

SEE ALSO