Description

These functions retrieve the metadata about a specific property. They require that
the template for the property has already been located by one of
the scf_tmpl_prop_create(3SCF) suite of functions.

The scf_tmpl_prop_name() function will retrieve the property's name as currently templated and
place it in *out. The caller is responsible for freeing the *out
buffer on success.

The scf_tmpl_prop_type() function will retrieve the type of the property as templated
and place the type in out.

The scf_tmpl_prop_required() function will determine whether the property is required in this
property group and place the result of that check in out. If
required is unset, out will be the default, 0. If the property
is explicitly set to required, out will be 1.

The scf_tmpl_prop_common_name() function will retrieve the property's localized common name as currently
templated and place it in *out. A locale (as described in setlocale(3C))
can be specified, or if the supplied locale is NULL, the current
locale will be used. If a common name in the specified locale
is not found, the function will also look for a common name
in the C locale. Some templates will not specify the property common name.
The caller is responsible for freeing the *out buffer on success.

The scf_tmpl_prop_description() function will retrieve the property's localized description as currently templated
and place it in *out. A locale (as described in setlocale(3C)) can
be specified, or if the supplied locale is NULL, the current locale
will be used. If a description in the specified locale is not
found, the function will also look for a description in the C
locale. Some templates will not specify the property description. The caller is responsible
for freeing the *out buffer on success.

The scf_tmpl_prop_visibility() function will retrieve the visibility of the property as currently
templated and place it in out. A property can be SCF_TMPL_VISIBILITY_HIDDEN, SCF_TMPL_VISIBILITY_READONLY,
or SCF_TMPL_VISIBILITY_READWRITE. If the visibility is unset, this function will return the
default, SCF_TMPL_VISIBILITY_READWRITE.

The scf_tmpl_prop_cardinality() function will retrieve the minimum number of values and maximum
number of values allowed for this property and place them in min
and max, respectively. If the values are unset, the defaults of 0 for
min and UINT64_MAX for max.

The scf_values_destroy() function destroys an scf_values_t structure and all memory associated with
it.

The scf_values_t structure is populated by a number of functions. Based on
the value type, it is populated with an array of the values.
It is also always populated with an array of astring translations of
those values.

The scf_tmpl_prop_internal_seps() function will retrieve the list of internal separators as currently
defined in the template. Each separator will be a single string character
in a different element of out. Some templates will not specify any
internal separators. The caller is responsible for calling scf_values_destroy() on success.

The scf_tmpl_value_name_constraints() function will retrieve the set of property values the property
is expected to be part of. Some templates will not specify any
constraints. The caller is responsible for calling scf_values_destroy() on success.

The scf_tmpl_value_count_range_constraints() function will retrieve the set of defined lower and upper
bounds as defined by the property template and place them in ranges.
Some templates will not specify any range constraints.

The scf_count_ranges_t structure is populated by the scf_tmpl_value_count_range_constraints() and scf_tmpl_value_count_range_choices() functions. scf_count_ranges_destroy()
destroys an scf_count_ranges_t and all memory associated with it.

The scf_tmpl_value_int_range_constraints() function will retrieve the set of defined lower and upper
bounds as defined by the property template and place them in ranges.
Some templates will not specify any range constraints.

The scf_int_ranges_t structure is populated by the scf_tmpl_value_int_range_constraints() and scf_tmpl_value_int_range_choices() functions. The
scf_int_ranges_destroy() function destroys an scf_int_ranges_t and all memory associated with it.

The scf_tmpl_value_name_choices() function will retrieve the set of property value choices that
should be offered to a user. Some templates will not specify any
choices. The caller is responsible for calling scf_values_destroy() on success.

The scf_tmpl_value_count_range_choices() function will retrieve the set of defined lower and upper
bounds as defined by the property template and place them in ranges.
Some templates will not specify any range choices.

The scf_tmpl_value_int_range_constraints() function will retrieve the set of defined lower and upper
bounds as defined by the property template and place them in ranges.
Some templates will not specify any range constraints.

The scf_tmpl_value_common_name() function will retrieve the value's common name as currently templated
and place it in *out. A locale (as described in setlocale(3C)) can
be specified, or if the supplied locale is NULL, the current locale
will be used. If a common name in the specified locale is
not found, the function will also look for a common name in
the C locale. Some templates will not specify the value common name. The
caller is responsible for freeing the *out buffer on success.

The scf_tmpl_value_description() function will retrieve the value's description as currently templated and
place it in *out. A locale (as described in setlocale(3C)) can be
specified, or if the supplied locale is NULL, the current locale will
be used. If a description in the specified locale is not found,
the function will also look for a description in the C locale.
Some templates will not specify the value description. The caller is responsible for
freeing the *out buffer on success.

The scf_tmpl_value_in_constraint() function will check that the value provided matches the constraints
as defined in the property template provided. This currently means it will
determine if the value provided:

is of the proper type for the property template defined,

is within a range defined, if it is a numeric type, and

is within the name constraints, if name constraints are defined.

If the template property does not define a type, ranges will be
considered of the same type as the numeric values being checked. Some
ranges might consider the value out of constraint when tested as one
numeric type but within constraint if tested as other numeric type. Refer
to strtoull(3C) and strtoll(3C) to see the implications when retrieving numeric values
from the repository or converting strings to numeric values in libscf(3LIB).

If errs is not NULL, an scf_tmpl_error_t will be created, populated and
added to errs in case of a constraint violation. The caller is
responsible for calling scf_tmpl_errors_destroy() to free memory allocated for all scf_tmpl_error_t associated to
errs.

Return Values

Upon successful completion, scf_tmpl_prop_name(), scf_tmpl_prop_common_name(), scf_tmpl_prop_description(), scf_tmpl_prop_units(), scf_tmpl_value_common_name(), and scf_tmpl_value_description() return the
length of the string written, not including the terminating null byte. Otherwise,
they return -1.