1scf_simple_prop_Sgeertv(i3cSeCFC)onfiguration Facility LibrarysFcufn_cstiimopnlse_prop_get(3SCF)
2
6 scf_simple_prop_get, scf_simple_prop_free, scf_simple_app_props_get,
7 scf_simple_app_props_free, scf_simple_app_props_next, scf_sim‐
8 ple_app_props_search, scf_simple_prop_numvalues, scf_simple_prop_type,
9 scf_simple_prop_name, scf_simple_prop_pgname, scf_sim‐
10 ple_prop_next_boolean, scf_simple_prop_next_count, scf_sim‐
11 ple_prop_next_integer, scf_simple_prop_next_time, scf_sim‐
12 ple_prop_next_astring, scf_simple_prop_next_ustring, scf_sim‐
13 ple_prop_next_opaque, scf_simple_prop_next_reset - simplified property
14 read interface to Service Configuration Facility
15
17 cc [ flag... ] file... -lscf [ library... ]
18 #include <libscf.h>
19 scf_simple_prop_t *scf_simple_prop_get(scf_handle_t *handle,
21 const char *instance, const char *pgname, const char *propname);
22 void scf_simple_prop_free(scf_simple_prop_t *prop);
25 scf_simple_app_props_t *scf_simple_app_props_get(scf_handle_t *handle,
28 const char *instance);
29 void scf_simple_app_props_free(scf_simple_app_props_t *propblock);
32 const scf_simple_prop_t *scf_simple_app_props_next
35 (const scf_simple_app_props_t *propblock,scf_simple_prop_t *last);
36 const scf_simple_prop_t *scf_simple_app_props_search
39 (const scf_simple_app_props_t *propblock, const char *pgname,
40 const char *propname);
41 ssize_t scf_simple_prop_numvalues(const scf_simple_prop_t *prop);
44 scf_type_t scf_simple_prop_type(const scf_simple_prop_t *prop);
47 const char *scf_simple_prop_name(const scf_simple_prop_t *prop);
50 const char *scf_simple_prop_pgname(const scf_simple_prop_t *prop);
53 uint8_t *scf_simple_prop_next_boolean(const scf_simple_prop_t *prop);
56 uint64_t *scf_simple_prop_next_count(const scf_simple_prop_t *prop);
59 int64_t *scf_simple_prop_next_integer(const scf_simple_prop_t *prop);
62 int64_t *scf_simple_prop_next_time(const scf_simple_prop_t *prop,
65 int32_t *nsec);
66 char *scf_simple_prop_next_astring(const scf_simple_prop_t *prop);
69 char *scf_simple_prop_next_ustring(const scf_simple_prop_t *prop);
72 void *scf_simple_prop_next_opaque(const scf_simple_prop_t *prop,
75 size_t *length);
76 void *scf_simple_prop_next_reset(const scf_simple_prop_t *prop);
79
82 The simplified read interface to the Service Configuration Facility
83 deals with properties and blocks of properties.
84 The scf_simple_prop_get() function pulls a single property. The
87 scf_simple_prop_*() functions operate on the resulting scf_sim‐
88 ple_prop_t.
89 The application might need to get many properties or iterate through
92 all properties. The scf_simple_app_props_get() function gets all prop‐
93 erties from the service instance that are in property groups of type
94 'application'. Individual properties are pulled from the block using
95 the scf_simple_app_props_next() function for iteration or scf_sim‐
96 ple_app_props_search() to search. The pointer to the scf_simple_prop_t
97 returned from iteration or searching can be acted upon using the
98 scf_simple_prop_*() functions. Each scf_*_get() function has an accom‐
99 panying scf_*_free function. The application does not free the pointer
100 to the scf_simple_prop_t returned from the scf_simple_app_props_next()
101 and scf_simple_app_props_search() calls. A free call is only used with
102 a corresponding get call.
103 The scf_simple_prop_*() functions return references to the read-only
106 in-memory copy of the property information. Any changes to this infor‐
107 mation results in unstable behavior and inaccurate results. The simpli‐
108 fied read interface provides read access only, with no provisions to
109 modify data in the service configuration facility repository.
110 The scf_simple_prop_get() function takes as arguments a bound handle, a
113 service instance FMRI, and the property group and property name of a
114 property. If handle is NULL, the library uses a temporary handle cre‐
115 ated for the purpose. If instance is NULL the library automatically
116 finds the FMRI of the calling process. If pgname is NULL, the library
117 uses the default application property group. The caller is responsible
118 for freeing the returned property with scf_simple_prop_free().
119 The scf_simple_prop_free() function frees the scf_simple_prop_t allo‐
122 cated by scf_simple_prop_get().
123 The scf_simple_app_props_get() function takes a bound handle and a ser‐
126 vice instance FMRI and pulls all the application properties into an
127 scf_simple_app_props_t. If handle is NULL, the library uses a temporary
128 handle created for the purpose. If instance is NULL, the library looks
129 up the instance FMRI of the process calling the function. The caller is
130 responsible for freeing the scf_simple_app_props_t with scf_sim‐
131 ple_app_props_free().
132 The scf_simple_app_props_free() function frees the scf_sim‐
135 ple_app_props_t allocated by scf_simple_app_props_get().
136 The scf_simple_app_props_next() function iterates over each property in
139 an scf_simple_app_props_t. It takes an scf_simple_app_props_t pointer
140 and the last property returned from the previous call and returns the
141 next property in the scf_simple_app_props_t. Because the property is a
142 reference into the scf_simple_app_props_t, its lifetime extends only
143 until that structure is freed.
144 Thescf_simple_app_props_search() function queries for an exact match on
147 a property in a property group. It takes an apps prop object, a prop‐
148 erty group name, and a property name, and returns a property pointer.
149 Because the property is a reference into the scf_simple_app_props_t,
150 its lifetime extends only until that structure is freed. If the prop‐
151 erty group name, pgname, is NULL, "application" is used.
152 The scf_simple_prop_numvalues() function takes a pointer to a property
155 and returns the number of values in that property.
156 The scf_simple_prop_type() function takes a pointer to a property and
159 returns the type of the property in an scf_type_t.
160 The scf_simple_prop_name() function takes a pointer to a property and
163 returns a pointer to the property name string.
164 The scf_simple_prop_pgname() function takes a pointer to a property and
167 returns a pointer to the property group name string. The scf_sim‐
168 ple_prop_next_boolean(), scf_simple_prop_next_count(), scf_sim‐
169 ple_prop_next_integer(), scf_simple_prop_next_astring(), and scf_sim‐
170 ple_prop_next_ustring() functions take a pointer to a property and
171 return the first value in the property. Subsequent calls iterate over
172 all the values in the property. The property's internal iteration can
173 be reset with scf_simple_prop_next_reset().
174 The scf_simple_prop_next_time() function takes a pointer to a property
177 and the address of an allocated int32_t to hold the nanoseconds field,
178 and returns the first value in the property. Subsequent calls iterate
179 over the property values.
180 The scf_simple_prop_next_opaque() function takes a pointer to a prop‐
183 erty and the address of an allocated integer to hold the size of the
184 opaque buffer. It returns the first value in the property. Subsequent
185 calls iterate over the property values, as do the scf_sim‐
186 ple_prop_next_*() functions. The scf_simple_prop_next_opaque() function
187 writes the size of the opaque buffer into the allocated integer.
188 The scf_simple_prop_next_reset() function resets iteration on a prop‐
191 erty, so that a call to one of the scf_simple_prop_next_*() functions
192 returns the first value in the property.
193
195 Upon successful completion, scf_simple_prop_get() returns a pointer to
196 an allocated scf_simple_prop_t. Otherwise, it returns NULL.
197 Upon successful completion, scf_simple_app_props_get() returns a
200 pointer to an allocated scf_simple_app_props_t. Otherwise, it returns
201 NULL.
202 Upon successful completion, scf_simple_app_props_next() returns a
205 pointer to an scf_simple_prop_t. Otherwise, it returns NULL.
206 Upon successful completion, scf_simple_app_props_search() returns a
209 pointer to an scf_simple_prop_t. Otherwise, it returns NULL.
210 Upon successful completion, scf_simple_prop_numvalues() returns the
213 number of values in a property. Otherwise, it returns -1.
214 Upon successful completion, scf_simple_prop_type() returns an
217 scf_type_t. Otherwise, it returns -1.
218 Upon successful completion, scf_simple_prop_name() and scf_sim‐
221 ple_prop_pgname() return character pointers. Otherwise, they return
222 NULL.
223 Upon successful completion, scf_simple_prop_next_boolean(), scf_sim‐
226 ple_prop_next_count(), scf_simple_prop_next_integer(), scf_sim‐
227 ple_prop_next_time(), scf_simple_prop_next_astring(), scf_sim‐
228 ple_prop_next_ustring(), and scf_simple_prop_next_opaque() return a
229 pointer to the next value in the property. After all values have been
230 returned, NULL is returned and SCF_ERROR_NONE is set. On failure, NULL
231 is returned and the appropriate error value is set.
232
234 The scf_simple_prop_get() and scf_simple_app_props_get() functions will
235 fail if:
236 SCF_ERROR_CONNECTION_BROKEN
238 The connection to the datastore is broken.
240 SCF_ERROR_INVALID_ARGUMENT
243 The instance FMRI is invalid or property name is NULL.
245 SCF_ERROR_NO_MEMORY
248 The memory allocation failed.
250 SCF_ERROR_NOT_BOUND
253 The connection handle is not bound.
255 SCF_ERROR_NOT_FOUND
258 The specified instance or property does not exist.
260 SCF_ERROR_PERMISSION_DENIED
263 The caller is not authorized to read the property's value(s).
265 The scf_simple_app_props_next() function will fail if:
269 SCF_ERROR_NOT_SET The value of the propblock argument is NULL.
271 The scf_simple_app_props_search() function will fail if:
275 SCF_ERROR_NOT_FOUND The property was not found.
277 SCF_ERROR_NOT_SET The value of the propblock or propname argument
280 is NULL.
281 The scf_simple_prop_numvalues(), scf_simple_prop_type(), scf_sim‐
285 ple_prop_name(), and scf_simple_prop_pgname() functions will fail if:
286 SCF_ERROR_NOT_SET The property is NULL.
288 The scf_simple_prop_next_boolean(), scf_simple_prop_next_count(),
292 scf_simple_prop_next_integer(), scf_simple_prop_next_time(), scf_sim‐
293 ple_prop_next_astring(), scf_simple_prop_next_ustring(), and scf_sim‐
294 ple_prop_next_opaque() functions will fail if:
295 SCF_ERROR_NOT_SET The property is NULL.
297 SCF_ERROR_TYPE_MISMATCH The requested type does not match the prop‐
300 erty type.
301
304 Example 1 Simple Property Get
305 /*
307 * In this example, we pull the property named "size" from the
308 * default property group. We make sure that the property
309 * isn't empty, and then copy it into the sizeval variable.
310 */
311 scf_simple_prop_t *prop;
313 ssize_t numvals;
314 int64_t *sizeval;
315 prop = scf_simple_prop_get(
317 "svc://localhost/category/service/instance",
318 NULL, "size");
319 numvals = scf_simple_prop_numvalues(prop);
321 if(numvals > 0){
323 sizeval = scf_simple_prop_next_integer(prop);
324 }
325 scf_simple_prop_free(prop);
327 Example 2 Property Iteration
330 scf_simple_prop_t *prop;
332 scf_simple_app_props_t *appprops;
333 appprops = scf_simple_app_props_get(
335 "svc://localhost/category/service/instance");
336 prop = scf_simple_app_props_next(appprops, NULL);
338 while(prop != NULL)
340 {
341 /*
342 * This iteration will go through every property in the
343 * instance's application block. The user can use
344 * the set of property functions to pull the values out
345 * of prop, as seen in other examples.
346 */
347 (...code acting on each property...)
349 prop = scf_simple_app_props_next(appprops, prop);
352 }
354 scf_simple_app_props_free(appprops);
356 Example 3 Property Searching
359 /*
361 * In this example, we pull the property block from the instance,
362 * and then query it. Generally speaking, the simple get would
363 * be used for an example like this, but for the purposes of
364 * illustration, the non-simple approach is used. The property
365 * is a list of integers that are pulled into an array.
366 * Note how val is passed back into each call, as described above.
367 */
368 scf_simple_app_props_t *appprops;
370 scf_simple_prop_t *prop;
371 int i;
372 int64_t *intlist;
373 ssize_t numvals;
374 appprops = scf_simple_app_props_get(
376 "svc://localhost/category/service/instance");
377 prop = scf_simple_app_props_search(appprops, "appname", "numlist");
379 if(prop != NULL){
381 numvals = scf_simple_prop_numvalues(prop);
383 if(numvals > 0){
385 intlist = malloc(numvals * sizeof(int64_t));
387 val = scf_simple_prop_next_integer(prop);
389 for(i=0, i < numvals, i++){
391 intlist[i] = *val;
392 val = scf_simple_prop_next_integer(prop);
393 }
394 }
395 }
396 scf_simple_app_props_free(appprops);
398
401 See attributes(5) for descriptions of the following attributes:
402 ┌─────────────────────────────┬─────────────────────────────┐
407 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
408 ├─────────────────────────────┼─────────────────────────────┤
409 │Interface Stability │Committed │
410 ├─────────────────────────────┼─────────────────────────────┤
411 │MT-Level │Safe │
412 └─────────────────────────────┴─────────────────────────────┘
413
415 libscf(3LIB), scf_error(3SCF), attributes(5)
416SunOS 5.11 7 Nov 2007 scf_simple_prop_get(3SCF)