1scf_tmpl_prop_naSmeer(v3iScCeF)Configuration Facility Library Fsucnfc_ttimopnls_prop_name(3SCF)
2
3
4

NAME

6       scf_tmpl_prop_name,     scf_tmpl_prop_type,     scf_tmpl_prop_required,
7       scf_tmpl_prop_common_name,                   scf_tmpl_prop_description,
8       scf_tmpl_prop_units,     scf_tmpl_prop_visibility,    scf_tmpl_visibil‐
9       ity_to_string, scf_tmpl_prop_cardinality,  scf_tmpl_prop_internal_seps,
10       scf_tmpl_value_name_constraints,              scf_count_ranges_destroy,
11       scf_int_ranges_destroy,         scf_tmpl_value_count_range_constraints,
12       scf_tmpl_value_int_range_constraints,      scf_tmpl_value_name_choices,
13       scf_values_destroy,                 scf_tmpl_value_count_range_choices,
14       scf_tmpl_value_int_range_choices,           scf_tmpl_value_common_name,
15       scf_tmpl_value_description, scf_tmpl_value_in_constraint - retrieve the
16       metadata about a specific property
17

SYNOPSIS

19       cc [ flag... ] file... -lscf [ library... ]
20       #include <libscf.h>
21
22       ssize_t scf_tmpl_prop_name(const scf_prop_tmpl_t *prop_tmpl,
23            char **out);
24
25
26       int scf_tmpl_prop_type(const scf_prop_tmpl_t *prop_tmpl,
27            scf_type_t *out);
28
29
30       int scf_tmpl_prop_required(const scf_prop_tmpl_t *prop_tmpl,
31            uint8_t *out)
32
33
34       ssize_t scf_tmpl_prop_common_name(const scf_prop_tmpl_t *prop_tmpl,
35            char *locale, char **out);
36
37
38       ssize_t scf_tmpl_prop_description(const scf_prop_tmpl_t *prop_tmpl,
39            char * locale, char **out);
40
41
42       ssize_t scf_tmpl_prop_units(const scf_prop_tmpl_t *prop_tmpl,
43            const char *locale, char **out);
44
45
46       int scf_tmpl_prop_visibility(const scf_prop_tmpl_t *prop_tmpl,
47            uint8_t *out);
48
49
50       const char *scf_tmpl_visibility_to_string(uint8_t visibility);
51
52
53       int scf_tmpl_prop_cardinality(const scf_prop_tmpl_t *prop_tmpl,
54            uint64_t *min, uint64_t *max);
55
56
57       int scf_tmpl_prop_internal_seps(const scf_prop_tmpl_t *prop_tmpl,
58            scf_values_t *out);
59
60
61       int scf_tmpl_value_name_constraints(const scf_prop_tmpl_t *prop_tmpl,
62            scf_values_t *out);
63
64
65       void scf_count_ranges_destroy(scf_count_ranges_t *ranges);
66
67
68       void scf_int_ranges_destroy(scf_int_ranges_t *ranges);
69
70
71       int scf_tmpl_value_count_range_constraints(
72            const scf_prop_tmpl_t *prop_tmpl, scf_count_ranges_t *ranges);
73
74
75       int scf_tmpl_value_int_range_constraints(
76            const scf_prop_tmpl_t *prop_tmpl, scf_int_ranges_t *ranges);
77
78
79       int scf_tmpl_value_name_choices(const scf_prop_tmpl_t *prop_tmpl,
80            scf_values_t *vals);
81
82
83       void scf_values_destroy(scf_values_t *vals);
84
85
86       int scf_tmpl_value_count_range_choices(
87            const scf_prop_tmpl_t *prop_tmpl, scf_count_ranges_t *ranges);
88
89
90       int scf_tmpl_value_int_range_choices(const scf_prop_tmpl_t *prop_tmpl,
91            scf_int_ranges_t *ranges);
92
93
94       ssize_t scf_tmpl_value_common_name(const scf_prop_tmpl_t *prop_tmpl,
95            const char *locale, const char *value, char **out);
96
97
98       ssize_t scf_tmpl_value_description(const scf_prop_tmpl_t *prop_tmpl,
99            const char *locale, const char *value, char **out);
100
101
102       int scf_tmpl_value_in_constraint(const scf_prop_tmpl_t *prop_tmpl,
103            scf_value_t *value, scf_tmpl_errors_t **errs);
104
105

DESCRIPTION

107       These  functions  retrieve the metadata about a specific property. They
108       require that the template for the property has already been located  by
109       one of the scf_tmpl_prop_create(3SCF) suite of functions.
110
111
112       The  scf_tmpl_prop_name() function will retrieve the property's name as
113       currently templated and place it in *out. The caller is responsible for
114       freeing the *out buffer on success.
115
116
117       The  scf_tmpl_prop_type()  function will retrieve the type of the prop‐
118       erty as templated and place the type in out.
119
120
121       The scf_tmpl_prop_required() function will determine whether the  prop‐
122       erty  is  required  in this property group and place the result of that
123       check in out. If required is unset, out will be the default, 0. If  the
124       property is explicitly set to required, out will be 1.
125
126
127       The  scf_tmpl_prop_common_name()  function will retrieve the property's
128       localized common name as currently templated and place it  in  *out.  A
129       locale (as described in setlocale(3C)) can be specified, or if the sup‐
130       plied locale is NULL, the current locale will be used. If a common name
131       in the specified locale is not found, the function will also look for a
132       common name in the C locale. Some templates will not specify the  prop‐
133       erty common name. The caller is responsible for freeing the *out buffer
134       on success.
135
136
137       The scf_tmpl_prop_description() function will retrieve  the  property's
138       localized  description  as  currently templated and place it in *out. A
139       locale (as described in setlocale(3C)) can be specified, or if the sup‐
140       plied locale is NULL, the current locale will be used. If a description
141       in the specified locale is not found, the function will also look for a
142       description  in the C locale. Some templates will not specify the prop‐
143       erty description. The caller is responsible for freeing the *out buffer
144       on success.
145
146
147       The scf_tmpl_prop_visibility() function will retrieve the visibility of
148       the property as currently templated and place it in out. A property can
149       be    SCF_TMPL_VISIBILITY_HIDDEN,    SCF_TMPL_VISIBILITY_READONLY,   or
150       SCF_TMPL_VISIBILITY_READWRITE. If the visibility is unset,  this  func‐
151       tion will return the default, SCF_TMPL_VISIBILITY_READWRITE.
152
153
154       The scf_tmpl_prop_cardinality() function will retrieve the minimum num‐
155       ber of values and maximum number of values allowed  for  this  property
156       and  place  them in min and max, respectively. If the values are unset,
157       the defaults of 0 for min and UINT64_MAX for max.
158
159
160       The scf_values_destroy() function destroys  an  scf_values_t  structure
161       and all memory associated with it.
162
163
164       The scf_values_t structure is populated by a number of functions. Based
165       on the value type, it is populated with an array of the values.  It  is
166       also  always  populated  with an array of astring translations of those
167       values.
168
169         typedef struct scf_time {
170               int64_t         t_seconds;
171               int32_t         t_ns;
172         } scf_time_t;
173
174         typedef struct scf_values {
175               scf_type_t              value_type;
176               char                    *reserved;
177               int                     value_count;
178               const char              **values_as_astring;
179               union {
180                       uint64_t        *v_count;
181                       uint8_t         *v_boolean;
182                       int64_t         *v_integer;
183                       char            **v_astring;
184                       char            **v_ustring;
185                       char            **v_opaque;
186                       scf_time_t      *v_time;
187               } sv_data;
188         } scf_values_t;
189
190
191
192       The scf_tmpl_prop_internal_seps() function will retrieve  the  list  of
193       internal  separators as currently defined in the template. Each separa‐
194       tor will be a single string character in a different  element  of  out.
195       Some  templates will not specify any internal separators. The caller is
196       responsible for calling scf_values_destroy() on success.
197
198
199       The scf_tmpl_value_name_constraints() function will retrieve the set of
200       property  values the property is expected to be part of. Some templates
201       will not specify any constraints. The caller is responsible for calling
202       scf_values_destroy() on success.
203
204
205       The scf_tmpl_value_count_range_constraints() function will retrieve the
206       set of defined lower and upper bounds as defined by the  property  tem‐
207       plate  and  place  them  in ranges. Some templates will not specify any
208       range constraints.
209
210
211       The    scf_count_ranges_t    structure    is    populated    by     the
212       scf_tmpl_value_count_range_constraints()                            and
213       scf_tmpl_value_count_range_choices()                         functions.
214       scf_count_ranges_destroy()  destroys an scf_count_ranges_t and all mem‐
215       ory associated with it.
216
217         typedef struct scf_count_ranges {
218                 int             scr_num_ranges;
219                 uint64_t        *scr_min;
220                 uint64_t        *scr_max;
221         } scf_count_ranges_t;
222
223
224
225       The scf_tmpl_value_int_range_constraints() function will  retrieve  the
226       set  of  defined lower and upper bounds as defined by the property tem‐
227       plate and place them in ranges. Some templates  will  not  specify  any
228       range constraints.
229
230
231       The     scf_int_ranges_t     structure     is    populated    by    the
232       scf_tmpl_value_int_range_constraints()                              and
233       scf_tmpl_value_int_range_choices()            functions.            The
234       scf_int_ranges_destroy() function destroys an scf_int_ranges_t and  all
235       memory associated with it.
236
237         typedef struct scf_int_ranges {
238                 int             scr_num_ranges;
239                 int64_t         *scr_min;
240                 int64_t         *scr_max;
241         } scf_int_ranges_t;
242
243
244
245       The  scf_tmpl_value_name_choices()  function  will  retrieve the set of
246       property value choices that should be offered to a user. Some templates
247       will  not  specify  any  choices. The caller is responsible for calling
248       scf_values_destroy() on success.
249
250
251       The scf_tmpl_value_count_range_choices() function will retrieve the set
252       of  defined  lower and upper bounds as defined by the property template
253       and place them in ranges. Some templates will  not  specify  any  range
254       choices.
255
256
257       The  scf_tmpl_value_int_range_constraints()  function will retrieve the
258       set of defined lower and upper bounds as defined by the  property  tem‐
259       plate  and  place  them  in ranges. Some templates will not specify any
260       range constraints.
261
262
263       The scf_tmpl_value_common_name() function  will  retrieve  the  value's
264       common  name  as currently templated and place it in *out. A locale (as
265       described in setlocale(3C)) can be specified, or if the supplied locale
266       is NULL, the current locale will be used. If a common name in the spec‐
267       ified locale is not found, the function will also  look  for  a  common
268       name  in the C locale. Some templates will not specify the value common
269       name. The caller is responsible for freeing the *out buffer on success.
270
271
272       The scf_tmpl_value_description() function  will  retrieve  the  value's
273       description  as  currently templated and place it in *out. A locale (as
274       described in setlocale(3C)) can be specified, or if the supplied locale
275       is NULL, the current locale will be used. If a description in the spec‐
276       ified locale is not found, the function will also look for  a  descrip‐
277       tion  in  the  C  locale.  Some  templates  will  not specify the value
278       description. The caller is responsible for freeing the *out  buffer  on
279       success.
280
281
282       The  scf_tmpl_value_in_constraint()  function will check that the value
283       provided matches the constraints as defined in  the  property  template
284       provided. This currently means it will determine if the value provided:
285
286           o      is of the proper type for the property template defined,
287
288           o      is within a range defined, if it is a numeric type, and
289
290           o      is  within  the  name  constraints,  if name constraints are
291                  defined.
292
293
294       If the template property does not define a type, ranges will be consid‐
295       ered  of the same type as the numeric values being checked. Some ranges
296       might consider the value out of constraint when tested as  one  numeric
297       type  but  within  constraint if tested as other numeric type. Refer to
298       strtoull(3C) and strtoll(3C) to see the  implications  when  retrieving
299       numeric  values  from  the  repository or converting strings to numeric
300       values in libscf(3LIB).
301
302
303       If errs is not NULL, an scf_tmpl_error_t will be created, populated and
304       added  to errs in case of a constraint violation. The caller is respon‐
305       sible for calling scf_tmpl_errors_destroy() to  free  memory  allocated
306       for all scf_tmpl_error_t associated to errs.
307

RETURN VALUES

309       Upon  successful  completion,  scf_tmpl_prop_name(), scf_tmpl_prop_com‐
310       mon_name(),     scf_tmpl_prop_description(),     scf_tmpl_prop_units(),
311       scf_tmpl_value_common_name(),  and  scf_tmpl_value_description() return
312       the length of the string written, not including  the  terminating  null
313       byte. Otherwise, they return -1.
314
315
316       Upon         successful        completion,        scf_tmpl_prop_type(),
317       scf_tmpl_prop_required(),                   scf_tmpl_prop_visibility(),
318       scf_tmpl_prop_cardinality(),             scf_tmpl_prop_internal_seps(),
319       scf_tmpl_value_name_constraints(),      scf_tmpl_value_count_range_con‐
320       straints(),                     scf_tmpl_value_int_range_constraints(),
321       scf_tmpl_value_name_choices(),    scf_tmpl_value_count_range_choices(),
322       scf_tmpl_value_int_range_choices() return 0. Otherwise, they return -1.
323
324
325       The scf_tmpl_value_in_constraint() functions returns 0 on success, 1 if
326       the value is not in the constraint, and -1 on failure.
327
328
329       Upon successful completion, scf_tmpl_visibility_to_string()  returns  a
330       string of the visibility supplied.
331

ERRORS

333       The             scf_tmpl_prop_name(),             scf_tmpl_prop_type(),
334       scf_tmpl_prop_required(),                  scf_tmpl_prop_common_name(),
335       scf_tmpl_prop_description(), scf_tmpl_prop_units(), scf_tmpl_prop_visi‐
336       bility(),  scf_tmpl_prop_cardinality(),  scf_tmpl_prop_internal_seps(),
337       scf_tmpl_value_name_constraints(),      scf_tmpl_value_count_range_con‐
338       straints(),                     scf_tmpl_value_int_range_constraints(),
339       scf_tmpl_value_name_choices(),    scf_tmpl_value_count_range_choices(),
340       scf_tmpl_value_int_range_choices(),       scf_tmpl_value_common_name(),
341       scf_tmpl_value_description(),  and scf_tmpl_value_in_constraint() func‐
342       tions will fail if:
343
344       SCF_ERROR_BACKEND_ACCESS
345
346           The storage mechanism that the repository server  (svc.configd(1M))
347           chose for the operation denied access.
348
349
350       SCF_ERROR_CONNECTION_BROKEN
351
352           The connection to the repository was lost.
353
354
355       SCF_ERROR_DELETED
356
357           The template property group has been deleted.
358
359
360       SCF_ERROR_HANDLE_DESTROYED
361
362           The handle passed in has been destroyed.
363
364
365       SCF_ERROR_INTERNAL
366
367           An internal error occurred.
368
369
370       SCF_ERROR_NO_MEMORY
371
372           There is not enough memory to populate the scf_pg_tmpl_t.
373
374
375       SCF_ERROR_NO_RESOURCES
376
377           The  server  does  not  have  adequate  resources  to  complete the
378           request.
379
380
381       SCF_ERROR_NOT_BOUND
382
383           The handle is not currently bound.
384
385
386       SCF_ERROR_PERMISSION_DENIED
387
388           The template could not be read due to access restrictions.
389
390
391       SCF_ERROR_TEMPLATE_INVALID
392
393           The template data is invalid.
394
395
396
397       The         scf_tmpl_prop_type(),          scf_tmpl_prop_common_name(),
398       scf_tmpl_prop_description(),  scf_tmpl_prop_units(), scf_tmpl_prop_car‐
399       dinality(),   scf_tmpl_prop_internal_seps(),   scf_tmpl_value_name_con‐
400       straints(),                   scf_tmpl_value_count_range_constraints(),
401       scf_tmpl_value_int_range_constraints(),  scf_tmpl_value_name_choices(),
402       scf_tmpl_value_count_range_choices(),
403       scf_tmpl_value_int_range_choices(),  scf_tmpl_value_common_name(),  and
404       scf_tmpl_value_description(), functions will fail if:
405
406       SCF_ERROR_NOT_FOUND    The property does not exist or exists and has no
407                              value.
408
409
410
411       The scf_tmpl_value_in_constraint() function will fail if:
412
413       SCF_ERROR_INVALID_ARGUMENT    Value is not a valid scf_value_t.
414
415
416
417       The   scf_tmpl_prop_common_name(),   scf_tmpl_prop_description()    and
418       scf_tmpl_prop_units() functions will fail if:
419
420       SCF_ERROR_INVALID_ARGUMENT    The  locale  string is too long to make a
421                                     property name.
422
423
424
425       The scf_tmpl_value_common_name() and scf_tmpl_value_description() func‐
426       tions will fail if:
427
428       SCF_ERROR_INVALID_ARGUMENT    The value and locale strings are too long
429                                     to make a property name.
430
431
432
433       The            scf_tmpl_value_count_range_constraints()             and
434       scf_tmpl_value_count_range_choices() functions will fail if:
435
436       SCF_ERROR_CONSTRAINT_VIOLATED
437
438           The range has negative values.
439
440
441
442       The              scf_tmpl_value_int_range_constraints()             and
443       scf_tmpl_value_int_range_choices() functions will fail if:
444
445       SCF_ERROR_CONSTRAINT_VIOLATED
446
447           The range values don't fit in a int64_t.
448
449
450
451       The                           scf_tmpl_value_count_range_constraints(),
452       scf_tmpl_value_int_range_constraints(),
453       scf_tmpl_value_count_range_choices()                                and
454       scf_tmpl_value_int_range_choices() functions will fail if:
455
456       SCF_ERROR_CONSTRAINT_VIOLATED
457
458           A range with min value > max value is found.
459
460

ATTRIBUTES

462       See attributes(5) for descriptions of the following attributes:
463
464
465
466
467       ┌─────────────────────────────┬─────────────────────────────┐
468       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
469       ├─────────────────────────────┼─────────────────────────────┤
470       │Interface Stability          │Committed                    │
471       ├─────────────────────────────┼─────────────────────────────┤
472       │MT-Level                     │Safe                         │
473       └─────────────────────────────┴─────────────────────────────┘
474

SEE ALSO

476       svc.configd(1M),    scf_tmpl_prop_create(3SCF),   setlocale(3C),   str‐
477       toll(3C), strtoull(3C), attributes(5), smf_template(5)
478
479
480
481SunOS 5.11                        28 Oct 2008         scf_tmpl_prop_name(3SCF)
Impressum