1scf_tmpl_prop_naSmeer(v3iScCeF)Configuration Facility Library Fsucnfc_ttimopnls_prop_name(3SCF)
2
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
19 cc [ flag... ] file... -lscf [ library... ]
20 #include <libscf.h>
21 ssize_t scf_tmpl_prop_name(const scf_prop_tmpl_t *prop_tmpl,
23 char **out);
24 int scf_tmpl_prop_type(const scf_prop_tmpl_t *prop_tmpl,
27 scf_type_t *out);
28 int scf_tmpl_prop_required(const scf_prop_tmpl_t *prop_tmpl,
31 uint8_t *out)
32 ssize_t scf_tmpl_prop_common_name(const scf_prop_tmpl_t *prop_tmpl,
35 char *locale, char **out);
36 ssize_t scf_tmpl_prop_description(const scf_prop_tmpl_t *prop_tmpl,
39 char * locale, char **out);
40 ssize_t scf_tmpl_prop_units(const scf_prop_tmpl_t *prop_tmpl,
43 const char *locale, char **out);
44 int scf_tmpl_prop_visibility(const scf_prop_tmpl_t *prop_tmpl,
47 uint8_t *out);
48 const char *scf_tmpl_visibility_to_string(uint8_t visibility);
51 int scf_tmpl_prop_cardinality(const scf_prop_tmpl_t *prop_tmpl,
54 uint64_t *min, uint64_t *max);
55 int scf_tmpl_prop_internal_seps(const scf_prop_tmpl_t *prop_tmpl,
58 scf_values_t *out);
59 int scf_tmpl_value_name_constraints(const scf_prop_tmpl_t *prop_tmpl,
62 scf_values_t *out);
63 void scf_count_ranges_destroy(scf_count_ranges_t *ranges);
66 void scf_int_ranges_destroy(scf_int_ranges_t *ranges);
69 int scf_tmpl_value_count_range_constraints(
72 const scf_prop_tmpl_t *prop_tmpl, scf_count_ranges_t *ranges);
73 int scf_tmpl_value_int_range_constraints(
76 const scf_prop_tmpl_t *prop_tmpl, scf_int_ranges_t *ranges);
77 int scf_tmpl_value_name_choices(const scf_prop_tmpl_t *prop_tmpl,
80 scf_values_t *vals);
81 void scf_values_destroy(scf_values_t *vals);
84 int scf_tmpl_value_count_range_choices(
87 const scf_prop_tmpl_t *prop_tmpl, scf_count_ranges_t *ranges);
88 int scf_tmpl_value_int_range_choices(const scf_prop_tmpl_t *prop_tmpl,
91 scf_int_ranges_t *ranges);
92 ssize_t scf_tmpl_value_common_name(const scf_prop_tmpl_t *prop_tmpl,
95 const char *locale, const char *value, char **out);
96 ssize_t scf_tmpl_value_description(const scf_prop_tmpl_t *prop_tmpl,
99 const char *locale, const char *value, char **out);
100 int scf_tmpl_value_in_constraint(const scf_prop_tmpl_t *prop_tmpl,
103 scf_value_t *value, scf_tmpl_errors_t **errs);
104
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 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 The scf_tmpl_prop_type() function will retrieve the type of the prop‐
118 erty as templated and place the type in out.
119 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 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 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 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 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 The scf_values_destroy() function destroys an scf_values_t structure
161 and all memory associated with it.
162 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 typedef struct scf_time {
170 int64_t t_seconds;
171 int32_t t_ns;
172 } scf_time_t;
173 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 o is of the proper type for the property template defined,
287 o is within a range defined, if it is a numeric type, and
289 o is within the name constraints, if name constraints are
291 defined.
292 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 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
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 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 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 Upon successful completion, scf_tmpl_visibility_to_string() returns a
330 string of the visibility supplied.
331
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 SCF_ERROR_BACKEND_ACCESS
345 The storage mechanism that the repository server (svc.configd(1M))
347 chose for the operation denied access.
348 SCF_ERROR_CONNECTION_BROKEN
351 The connection to the repository was lost.
353 SCF_ERROR_DELETED
356 The template property group has been deleted.
358 SCF_ERROR_HANDLE_DESTROYED
361 The handle passed in has been destroyed.
363 SCF_ERROR_INTERNAL
366 An internal error occurred.
368 SCF_ERROR_NO_MEMORY
371 There is not enough memory to populate the scf_pg_tmpl_t.
373 SCF_ERROR_NO_RESOURCES
376 The server does not have adequate resources to complete the
378 request.
379 SCF_ERROR_NOT_BOUND
382 The handle is not currently bound.
384 SCF_ERROR_PERMISSION_DENIED
387 The template could not be read due to access restrictions.
389 SCF_ERROR_TEMPLATE_INVALID
392 The template data is invalid.
394 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 SCF_ERROR_NOT_FOUND The property does not exist or exists and has no
407 value.
408 The scf_tmpl_value_in_constraint() function will fail if:
412 SCF_ERROR_INVALID_ARGUMENT Value is not a valid scf_value_t.
414 The scf_tmpl_prop_common_name(), scf_tmpl_prop_description() and
418 scf_tmpl_prop_units() functions will fail if:
419 SCF_ERROR_INVALID_ARGUMENT The locale string is too long to make a
421 property name.
422 The scf_tmpl_value_common_name() and scf_tmpl_value_description() func‐
426 tions will fail if:
427 SCF_ERROR_INVALID_ARGUMENT The value and locale strings are too long
429 to make a property name.
430 The scf_tmpl_value_count_range_constraints() and
434 scf_tmpl_value_count_range_choices() functions will fail if:
435 SCF_ERROR_CONSTRAINT_VIOLATED
437 The range has negative values.
439 The scf_tmpl_value_int_range_constraints() and
443 scf_tmpl_value_int_range_choices() functions will fail if:
444 SCF_ERROR_CONSTRAINT_VIOLATED
446 The range values don't fit in a int64_t.
448 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 SCF_ERROR_CONSTRAINT_VIOLATED
457 A range with min value > max value is found.
459
462 See attributes(5) for descriptions of the following attributes:
463 ┌─────────────────────────────┬─────────────────────────────┐
468 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
469 ├─────────────────────────────┼─────────────────────────────┤
470 │Interface Stability │Committed │
471 ├─────────────────────────────┼─────────────────────────────┤
472 │MT-Level │Safe │
473 └─────────────────────────────┴─────────────────────────────┘
474
476 svc.configd(1M), scf_tmpl_prop_create(3SCF), setlocale(3C), str‐
477 toll(3C), strtoull(3C), attributes(5), smf_template(5)
478SunOS 5.11 28 Oct 2008 scf_tmpl_prop_name(3SCF)