te
Copyright (c) 2008, Sun Microsystems Inc. All Rights Reserved.
The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
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

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);

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:

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.

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.

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

SCF_ERROR_CONNECTION_BROKEN

SCF_ERROR_DELETED

SCF_ERROR_HANDLE_DESTROYED

SCF_ERROR_INTERNAL

SCF_ERROR_NO_MEMORY

SCF_ERROR_NO_RESOURCES

SCF_ERROR_NOT_BOUND

SCF_ERROR_PERMISSION_DENIED

SCF_ERROR_TEMPLATE_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 scf_tmpl_value_in_constraint() function will fail if:

SCF_ERROR_INVALID_ARGUMENT

The scf_tmpl_prop_common_name(), scf_tmpl_prop_description() and scf_tmpl_prop_units() functions will fail if:

SCF_ERROR_INVALID_ARGUMENT

The scf_tmpl_value_common_name() and scf_tmpl_value_description() functions will fail if:

SCF_ERROR_INVALID_ARGUMENT

The scf_tmpl_value_count_range_constraints() and scf_tmpl_value_count_range_choices() functions will fail if:

SCF_ERROR_CONSTRAINT_VIOLATED

The scf_tmpl_value_int_range_constraints() and scf_tmpl_value_int_range_choices() functions will fail if:

SCF_ERROR_CONSTRAINT_VIOLATED

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

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Committed
MT-Level	Safe

svc.configd(1M), scf_tmpl_prop_create(3SCF), setlocale(3C), strtoll(3C), strtoull(3C), attributes(5), smf_template(5)