scf_simple_prop_next_count(3scf)

1scf_simple_prop_Sgeertv(i3cSeCFC)onfiguration Facility LibrarysFcufn_cstiimopnlse_prop_get(3SCF)
2
3
4

NAME

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

SYNOPSIS

17       cc [ flag... ] file... -lscf [ library... ]
18       #include <libscf.h>
19
20       scf_simple_prop_t *scf_simple_prop_get(scf_handle_t *handle,
21            const char *instance, const char *pgname, const char *propname);
22
23
24       void scf_simple_prop_free(scf_simple_prop_t *prop);
25
26
27       scf_simple_app_props_t *scf_simple_app_props_get(scf_handle_t *handle,
28            const char *instance);
29
30
31       void scf_simple_app_props_free(scf_simple_app_props_t *propblock);
32
33
34       const scf_simple_prop_t *scf_simple_app_props_next
35            (const scf_simple_app_props_t *propblock,scf_simple_prop_t *last);
36
37
38       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
42
43       ssize_t scf_simple_prop_numvalues(const scf_simple_prop_t *prop);
44
45
46       scf_type_t scf_simple_prop_type(const scf_simple_prop_t *prop);
47
48
49       const char *scf_simple_prop_name(const scf_simple_prop_t *prop);
50
51
52       const char *scf_simple_prop_pgname(const scf_simple_prop_t *prop);
53
54
55       uint8_t *scf_simple_prop_next_boolean(const scf_simple_prop_t *prop);
56
57
58       uint64_t *scf_simple_prop_next_count(const scf_simple_prop_t *prop);
59
60
61       int64_t *scf_simple_prop_next_integer(const scf_simple_prop_t *prop);
62
63
64       int64_t *scf_simple_prop_next_time(const scf_simple_prop_t *prop,
65            int32_t *nsec);
66
67
68       char *scf_simple_prop_next_astring(const scf_simple_prop_t *prop);
69
70
71       char *scf_simple_prop_next_ustring(const scf_simple_prop_t *prop);
72
73
74       void *scf_simple_prop_next_opaque(const scf_simple_prop_t *prop,
75            size_t *length);
76
77
78       void *scf_simple_prop_next_reset(const scf_simple_prop_t *prop);
79
80

DESCRIPTION

82       The  simplified  read  interface  to the Service Configuration Facility
83       deals with properties and blocks of properties.
84
85
86       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
90
91       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
104
105       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
111
112       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
120
121       The  scf_simple_prop_free()  function frees the scf_simple_prop_t allo‐
122       cated by scf_simple_prop_get().
123
124
125       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
133
134       The   scf_simple_app_props_free()   function   frees    the    scf_sim‐
135       ple_app_props_t allocated by scf_simple_app_props_get().
136
137
138       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
145
146       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
153
154       The  scf_simple_prop_numvalues() function takes a pointer to a property
155       and returns the number of values in that property.
156
157
158       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
161
162       The  scf_simple_prop_name()  function takes a pointer to a property and
163       returns a pointer to the property name string.
164
165
166       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
175
176       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
181
182       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
189
190       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

RETURN VALUES

195       Upon  successful completion, scf_simple_prop_get() returns a pointer to
196       an allocated scf_simple_prop_t. Otherwise, it returns NULL.
197
198
199       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
203
204       Upon  successful  completion,  scf_simple_app_props_next()  returns   a
205       pointer to an scf_simple_prop_t. Otherwise, it returns NULL.
206
207
208       Upon  successful  completion,  scf_simple_app_props_search()  returns a
209       pointer to an scf_simple_prop_t. Otherwise, it returns NULL.
210
211
212       Upon successful  completion,  scf_simple_prop_numvalues()  returns  the
213       number of values in a property. Otherwise, it returns -1.
214
215
216       Upon   successful   completion,   scf_simple_prop_type()   returns   an
217       scf_type_t. Otherwise, it returns -1.
218
219
220       Upon  successful  completion,   scf_simple_prop_name()   and   scf_sim‐
221       ple_prop_pgname()  return  character  pointers.  Otherwise, they return
222       NULL.
223
224
225       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

ERRORS

234       The scf_simple_prop_get() and scf_simple_app_props_get() functions will
235       fail if:
236
237       SCF_ERROR_CONNECTION_BROKEN
238
239           The connection to the datastore is broken.
240
241
242       SCF_ERROR_INVALID_ARGUMENT
243
244           The instance FMRI is invalid or property name is NULL.
245
246
247       SCF_ERROR_NO_MEMORY
248
249           The memory allocation failed.
250
251
252       SCF_ERROR_NOT_BOUND
253
254           The connection handle is not bound.
255
256
257       SCF_ERROR_NOT_FOUND
258
259           The specified instance or property does not exist.
260
261
262       SCF_ERROR_PERMISSION_DENIED
263
264           The caller is not authorized to read the property's value(s).
265
266
267
268       The scf_simple_app_props_next() function will fail if:
269
270       SCF_ERROR_NOT_SET    The value of the propblock argument is NULL.
271
272
273
274       The scf_simple_app_props_search() function will fail if:
275
276       SCF_ERROR_NOT_FOUND    The property was not found.
277
278
279       SCF_ERROR_NOT_SET      The  value of the propblock or propname argument
280                              is NULL.
281
282
283
284       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
287       SCF_ERROR_NOT_SET    The property is NULL.
288
289
290
291       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
296       SCF_ERROR_NOT_SET          The property is NULL.
297
298
299       SCF_ERROR_TYPE_MISMATCH    The requested type does not match the  prop‐
300                                  erty type.
301
302

EXAMPLES

304       Example 1 Simple Property Get
305
306         /*
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
312         scf_simple_prop_t       *prop;
313         ssize_t                 numvals;
314         int64_t                 *sizeval;
315
316         prop = scf_simple_prop_get(
317                 "svc://localhost/category/service/instance",
318                 NULL, "size");
319
320         numvals = scf_simple_prop_numvalues(prop);
321
322         if(numvals > 0){
323                 sizeval = scf_simple_prop_next_integer(prop);
324         }
325
326         scf_simple_prop_free(prop);
327
328
329       Example 2 Property Iteration
330
331         scf_simple_prop_t              *prop;
332         scf_simple_app_props_t         *appprops;
333
334         appprops = scf_simple_app_props_get(
335                 "svc://localhost/category/service/instance");
336
337         prop = scf_simple_app_props_next(appprops, NULL);
338
339         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
348                 (...code acting on each property...)
349
350
351         prop = scf_simple_app_props_next(appprops, prop);
352
353         }
354
355         scf_simple_app_props_free(appprops);
356
357
358       Example 3 Property Searching
359
360         /*
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
369         scf_simple_app_props_t         *appprops;
370         scf_simple_prop_t              *prop;
371         int                     i;
372         int64_t                 *intlist;
373         ssize_t                 numvals;
374
375         appprops = scf_simple_app_props_get(
376                       "svc://localhost/category/service/instance");
377
378         prop = scf_simple_app_props_search(appprops, "appname", "numlist");
379
380         if(prop != NULL){
381
382                 numvals = scf_simple_prop_numvalues(prop);
383
384                 if(numvals > 0){
385
386                 intlist = malloc(numvals * sizeof(int64_t));
387
388                 val = scf_simple_prop_next_integer(prop);
389
390                         for(i=0, i < numvals, i++){
391                                 intlist[i] = *val;
392                                 val = scf_simple_prop_next_integer(prop);
393                         }
394                 }
395         }
396
397         scf_simple_app_props_free(appprops);
398
399

ATTRIBUTES

401       See attributes(5) for descriptions of the following attributes:
402
403
404
405
406       ┌─────────────────────────────┬─────────────────────────────┐
407       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
408       ├─────────────────────────────┼─────────────────────────────┤
409       │Interface Stability          │Committed                    │
410       ├─────────────────────────────┼─────────────────────────────┤
411       │MT-Level                     │Safe                         │
412       └─────────────────────────────┴─────────────────────────────┘
413