SCF_TMPL_PROP_NAME(3SCF) Service Configuration Facility Library Functions
NAME
scf_tmpl_prop_name, scf_tmpl_prop_type, scf_tmpl_prop_required,
scf_tmpl_prop_common_name, scf_tmpl_prop_description,
scf_tmpl_prop_units, scf_tmpl_prop_visibility,
scf_tmpl_visibility_to_string, scf_tmpl_prop_cardinality,
scf_tmpl_prop_internal_seps, scf_tmpl_value_name_constraints,
scf_count_ranges_destroy, scf_int_ranges_destroy,
scf_tmpl_value_count_range_constraints,
scf_tmpl_value_int_range_constraints, scf_tmpl_value_name_choices,
scf_values_destroy, scf_tmpl_value_count_range_choices,
scf_tmpl_value_int_range_choices, scf_tmpl_value_common_name,
scf_tmpl_value_description, scf_tmpl_value_in_constraint - retrieve
the metadata about a specific property
SYNOPSIS
cc [
flag... ]
file...
-lscf [
library... ]
#include <libscf.h>
ssize_t scf_tmpl_prop_name(
const scf_prop_tmpl_t *prop_tmpl,
char **out);
int scf_tmpl_prop_type(
const scf_prop_tmpl_t *prop_tmpl,
scf_type_t *out);
int scf_tmpl_prop_required(
const scf_prop_tmpl_t *prop_tmpl,
uint8_t *out)
ssize_t scf_tmpl_prop_common_name(
const scf_prop_tmpl_t *prop_tmpl,
char *locale,
char **out);
ssize_t scf_tmpl_prop_description(
const scf_prop_tmpl_t *prop_tmpl,
char * locale,
char **out);
ssize_t scf_tmpl_prop_units(
const scf_prop_tmpl_t *prop_tmpl,
const char *locale,
char **out);
int scf_tmpl_prop_visibility(
const scf_prop_tmpl_t *prop_tmpl,
uint8_t *out);
const char *scf_tmpl_visibility_to_string(
uint8_t visibility);
int scf_tmpl_prop_cardinality(
const scf_prop_tmpl_t *prop_tmpl,
uint64_t *min,
uint64_t *max);
int scf_tmpl_prop_internal_seps(
const scf_prop_tmpl_t *prop_tmpl,
scf_values_t *out);
int scf_tmpl_value_name_constraints(
const scf_prop_tmpl_t *prop_tmpl,
scf_values_t *out);
void scf_count_ranges_destroy(
scf_count_ranges_t *ranges);
void scf_int_ranges_destroy(
scf_int_ranges_t *ranges);
int scf_tmpl_value_count_range_constraints(
const scf_prop_tmpl_t *prop_tmpl,
scf_count_ranges_t *ranges);
int scf_tmpl_value_int_range_constraints(
const scf_prop_tmpl_t *prop_tmpl,
scf_int_ranges_t *ranges);
int scf_tmpl_value_name_choices(
const scf_prop_tmpl_t *prop_tmpl,
scf_values_t *vals);
void scf_values_destroy(
scf_values_t *vals);
int scf_tmpl_value_count_range_choices(
const scf_prop_tmpl_t *prop_tmpl,
scf_count_ranges_t *ranges);
int scf_tmpl_value_int_range_choices(
const scf_prop_tmpl_t *prop_tmpl,
scf_int_ranges_t *ranges);
ssize_t scf_tmpl_value_common_name(
const scf_prop_tmpl_t *prop_tmpl,
const char *locale,
const char *value,
char **out);
ssize_t scf_tmpl_value_description(
const scf_prop_tmpl_t *prop_tmpl,
const char *locale,
const char *value,
char **out);
int scf_tmpl_value_in_constraint(
const scf_prop_tmpl_t *prop_tmpl,
scf_value_t *value,
scf_tmpl_errors_t **errs);
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.
typedef struct scf_time {
int64_t t_seconds;
int32_t t_ns;
} scf_time_t;
typedef struct scf_values {
scf_type_t value_type;
char *reserved;
int value_count;
const char **values_as_astring;
union {
uint64_t *v_count;
uint8_t *v_boolean;
int64_t *v_integer;
char **v_astring;
char **v_ustring;
char **v_opaque;
scf_time_t *v_time;
} sv_data;
} scf_values_t;
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.
typedef struct scf_count_ranges {
int scr_num_ranges;
uint64_t *scr_min;
uint64_t *scr_max;
} scf_count_ranges_t;
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.
typedef struct scf_int_ranges {
int scr_num_ranges;
int64_t *scr_min;
int64_t *scr_max;
} scf_int_ranges_t;
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:
o is of the proper type for the property template defined,
o is within a range defined, if it is a numeric type, and
o 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.
Upon successful completion,
scf_tmpl_prop_type(),
scf_tmpl_prop_required(),
scf_tmpl_prop_visibility(),
scf_tmpl_prop_cardinality(),
scf_tmpl_prop_internal_seps(),
scf_tmpl_value_name_constraints(),
scf_tmpl_value_count_range_constraints(),
scf_tmpl_value_int_range_constraints(),
scf_tmpl_value_name_choices(),
scf_tmpl_value_count_range_choices(),
scf_tmpl_value_int_range_choices() return 0. Otherwise, they return
-1.
The
scf_tmpl_value_in_constraint() functions returns 0 on success, 1
if the value is not in the constraint, and -1 on failure.
Upon successful completion,
scf_tmpl_visibility_to_string() returns a
string of the visibility supplied.
ERRORS
The
scf_tmpl_prop_name(),
scf_tmpl_prop_type(),
scf_tmpl_prop_required(),
scf_tmpl_prop_common_name(),
scf_tmpl_prop_description(),
scf_tmpl_prop_units(),
scf_tmpl_prop_visibility(),
scf_tmpl_prop_cardinality(),
scf_tmpl_prop_internal_seps(),
scf_tmpl_value_name_constraints(),
scf_tmpl_value_count_range_constraints(),
scf_tmpl_value_int_range_constraints(),
scf_tmpl_value_name_choices(),
scf_tmpl_value_count_range_choices(),
scf_tmpl_value_int_range_choices(),
scf_tmpl_value_common_name(),
scf_tmpl_value_description(), and
scf_tmpl_value_in_constraint() functions will fail if:
SCF_ERROR_BACKEND_ACCESS The storage mechanism that the repository server (
svc.configd(8))
chose for the operation denied access.
SCF_ERROR_CONNECTION_BROKEN The connection to the repository was lost.
SCF_ERROR_DELETED The template property group has been deleted.
SCF_ERROR_HANDLE_DESTROYED The handle passed in has been destroyed.
SCF_ERROR_INTERNAL An internal error occurred.
SCF_ERROR_NO_MEMORY There is not enough memory to populate the
scf_pg_tmpl_t.
SCF_ERROR_NO_RESOURCES The server does not have adequate resources to complete the
request.
SCF_ERROR_NOT_BOUND The handle is not currently bound.
SCF_ERROR_PERMISSION_DENIED The template could not be read due to access restrictions.
SCF_ERROR_TEMPLATE_INVALID The template data is invalid.
The
scf_tmpl_prop_type(),
scf_tmpl_prop_common_name(),
scf_tmpl_prop_description(),
scf_tmpl_prop_units(),
scf_tmpl_prop_cardinality(),
scf_tmpl_prop_internal_seps(),
scf_tmpl_value_name_constraints(),
scf_tmpl_value_count_range_constraints(),
scf_tmpl_value_int_range_constraints(),
scf_tmpl_value_name_choices(),
scf_tmpl_value_count_range_choices(),
scf_tmpl_value_int_range_choices(),
scf_tmpl_value_common_name(), and
scf_tmpl_value_description(), functions will fail if:
SCF_ERROR_NOT_FOUND The property does not exist or exists and has
no value.
The
scf_tmpl_value_in_constraint() function will fail if:
SCF_ERROR_INVALID_ARGUMENT Value is not a valid
scf_value_t.
The
scf_tmpl_prop_common_name(),
scf_tmpl_prop_description() and
scf_tmpl_prop_units() functions will fail if:
SCF_ERROR_INVALID_ARGUMENT The locale string is too long to make a
property name.
The
scf_tmpl_value_common_name() and
scf_tmpl_value_description() functions will fail if:
SCF_ERROR_INVALID_ARGUMENT The value and locale strings are too
long to make a property name.
The
scf_tmpl_value_count_range_constraints() and
scf_tmpl_value_count_range_choices() functions will fail if:
SCF_ERROR_CONSTRAINT_VIOLATED The range has negative values.
The
scf_tmpl_value_int_range_constraints() and
scf_tmpl_value_int_range_choices() functions will fail if:
SCF_ERROR_CONSTRAINT_VIOLATED The range values don't fit in a
int64_t.
The
scf_tmpl_value_count_range_constraints(),
scf_tmpl_value_int_range_constraints(),
scf_tmpl_value_count_range_choices() and
scf_tmpl_value_int_range_choices() functions will fail if:
SCF_ERROR_CONSTRAINT_VIOLATED A range with
min value >
max value is found.
ATTRIBUTES
See
attributes(7) for descriptions of the following attributes:
+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | Committed |
+--------------------+-----------------+
|MT-Level | Safe |
+--------------------+-----------------+
SEE ALSO
setlocale(3C),
strtoll(3C),
strtoull(3C),
scf_tmpl_prop_create(3SCF),
attributes(7),
smf_template(7),
svc.configd(8) October 28, 2008 SCF_TMPL_PROP_NAME(3SCF)