path: root/usr/src/man/man3scf/scf_tmpl_prop_name.3scf

'\" 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]
.TH SCF_TMPL_PROP_NAME 3SCF "Oct 28, 2008"
.SH 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
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lscf\fR [ \fIlibrary\fR\&.\|.\|. ]
#include <libscf.h>

\fBssize_t\fR \fBscf_tmpl_prop_name\fR(\fBconst scf_prop_tmpl_t *\fR\fIprop_tmpl\fR,
     \fBchar **\fR\fIout\fR);
.fi

.LP
.nf
\fBint\fR \fBscf_tmpl_prop_type\fR(\fBconst scf_prop_tmpl_t *\fR\fIprop_tmpl\fR,
     \fBscf_type_t *\fR\fIout\fR);
.fi

.LP
.nf
\fBint\fR \fBscf_tmpl_prop_required\fR(\fBconst scf_prop_tmpl_t *\fR\fIprop_tmpl\fR,
     \fBuint8_t *\fR\fIout\fR)
.fi

.LP
.nf
\fBssize_t\fR \fBscf_tmpl_prop_common_name\fR(\fBconst scf_prop_tmpl_t *\fR\fIprop_tmpl\fR,
     \fBchar *\fR\fIlocale\fR, \fBchar **\fR\fIout\fR);
.fi

.LP
.nf
\fBssize_t\fR \fBscf_tmpl_prop_description\fR(\fBconst scf_prop_tmpl_t *\fR\fIprop_tmpl\fR,
     \fBchar *\fR \fIlocale\fR, \fBchar **\fR\fIout\fR);
.fi

.LP
.nf
\fBssize_t\fR \fBscf_tmpl_prop_units\fR(\fBconst scf_prop_tmpl_t *\fR\fIprop_tmpl\fR,
     \fBconst char *\fR\fIlocale\fR, \fBchar **\fR\fIout\fR);
.fi

.LP
.nf
\fBint\fR \fBscf_tmpl_prop_visibility\fR(\fBconst scf_prop_tmpl_t *\fR\fIprop_tmpl\fR,
     \fBuint8_t *\fR\fIout\fR);
.fi

.LP
.nf
\fBconst char *\fR\fBscf_tmpl_visibility_to_string\fR(\fBuint8_t\fR \fIvisibility\fR);
.fi

.LP
.nf
\fBint\fR \fBscf_tmpl_prop_cardinality\fR(\fBconst scf_prop_tmpl_t *\fR\fIprop_tmpl\fR,
     \fBuint64_t *\fR\fImin\fR, \fBuint64_t *\fR\fImax\fR);
.fi

.LP
.nf
\fBint\fR \fBscf_tmpl_prop_internal_seps\fR(\fBconst scf_prop_tmpl_t *\fR\fIprop_tmpl\fR,
     \fBscf_values_t *\fR\fIout\fR);
.fi

.LP
.nf
\fBint\fR \fBscf_tmpl_value_name_constraints\fR(\fBconst scf_prop_tmpl_t *\fR\fIprop_tmpl\fR,
     \fBscf_values_t *\fR\fIout\fR);
.fi

.LP
.nf
\fBvoid\fR \fBscf_count_ranges_destroy\fR(\fBscf_count_ranges_t *\fR\fIranges\fR);
.fi

.LP
.nf
\fBvoid\fR \fBscf_int_ranges_destroy\fR(\fBscf_int_ranges_t *\fR\fIranges\fR);
.fi

.LP
.nf
\fBint\fR \fBscf_tmpl_value_count_range_constraints\fR(
     \fBconst scf_prop_tmpl_t *\fR\fIprop_tmpl\fR, \fBscf_count_ranges_t *\fR\fIranges\fR);
.fi

.LP
.nf
\fBint\fR \fBscf_tmpl_value_int_range_constraints\fR(
     \fBconst scf_prop_tmpl_t *\fR\fIprop_tmpl\fR, \fBscf_int_ranges_t *\fR\fIranges\fR);
.fi

.LP
.nf
\fBint\fR \fBscf_tmpl_value_name_choices\fR(\fBconst scf_prop_tmpl_t *\fR\fIprop_tmpl\fR,
     \fBscf_values_t *\fR\fIvals\fR);
.fi

.LP
.nf
\fBvoid\fR \fBscf_values_destroy\fR(\fBscf_values_t *\fR\fIvals\fR);
.fi

.LP
.nf
\fBint\fR \fBscf_tmpl_value_count_range_choices\fR(
     \fBconst scf_prop_tmpl_t *\fR\fIprop_tmpl\fR, \fBscf_count_ranges_t *\fR\fIranges\fR);
.fi

.LP
.nf
\fBint\fR \fBscf_tmpl_value_int_range_choices\fR(\fBconst scf_prop_tmpl_t *\fR\fIprop_tmpl\fR,
     \fBscf_int_ranges_t *\fR\fIranges\fR);
.fi

.LP
.nf
\fBssize_t\fR \fBscf_tmpl_value_common_name\fR(\fBconst scf_prop_tmpl_t *\fR\fIprop_tmpl\fR,
     \fBconst char *\fR\fIlocale\fR, \fBconst char *\fR\fIvalue\fR, \fBchar **\fR\fIout\fR);
.fi

.LP
.nf
\fBssize_t\fR \fBscf_tmpl_value_description\fR(\fBconst scf_prop_tmpl_t *\fR\fIprop_tmpl\fR,
     \fBconst char *\fR\fIlocale\fR, \fBconst char *\fR\fIvalue\fR, \fBchar **\fR\fIout\fR);
.fi

.LP
.nf
\fBint\fR \fBscf_tmpl_value_in_constraint\fR(\fBconst scf_prop_tmpl_t *\fR\fIprop_tmpl\fR,
     \fBscf_value_t *\fR\fIvalue\fR, \fBscf_tmpl_errors_t **\fR\fIerrs\fR);
.fi

.SH DESCRIPTION
.sp
.LP
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
\fBscf_tmpl_prop_create\fR(3SCF) suite of functions.
.sp
.LP
The \fBscf_tmpl_prop_name()\fR function will retrieve the property's name as
currently templated and place it in *\fIout\fR. The caller is responsible for
freeing the *\fIout\fR buffer on success.
.sp
.LP
The \fBscf_tmpl_prop_type()\fR function will retrieve the type of the property
as templated and place the type in out.
.sp
.LP
The \fBscf_tmpl_prop_required()\fR 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.
.sp
.LP
The \fBscf_tmpl_prop_common_name()\fR function will retrieve the property's
localized common name as currently templated and place it in *\fIout\fR. A
locale (as described in \fBsetlocale\fR(3C)) can be specified, or if the
supplied locale is \fINULL\fR, 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 *\fIout\fR buffer on
success.
.sp
.LP
The \fBscf_tmpl_prop_description()\fR function will retrieve the property's
localized description as currently templated and place it in *\fIout\fR. A
locale (as described in \fBsetlocale\fR(3C)) can be specified, or if the
supplied locale is \fINULL\fR, 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 *\fIout\fR buffer on
success.
.sp
.LP
The \fBscf_tmpl_prop_visibility()\fR function will retrieve the visibility of
the property as currently templated and place it in out. A property can be
\fBSCF_TMPL_VISIBILITY_HIDDEN\fR, \fBSCF_TMPL_VISIBILITY_READONLY\fR, or
\fBSCF_TMPL_VISIBILITY_READWRITE\fR. If the visibility is unset, this function
will return the default, \fBSCF_TMPL_VISIBILITY_READWRITE\fR.
.sp
.LP
The \fBscf_tmpl_prop_cardinality()\fR function will retrieve the minimum number
of values and maximum number of values allowed for this property and place them
in \fImin\fR and \fImax\fR, respectively. If the values are unset, the defaults
of 0 for \fImin\fR and \fBUINT64_MAX\fR for \fImax\fR.
.sp
.LP
The \fBscf_values_destroy()\fR function destroys an \fBscf_values_t\fR
structure and all memory associated with it.
.sp
.LP
The \fBscf_values_t\fR 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 \fIastring\fR translations of those values.
.sp
.in +2
.nf
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;
.fi
.in -2

.sp
.LP
The \fBscf_tmpl_prop_internal_seps()\fR 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
\fBscf_values_destroy()\fR on success.
.sp
.LP
The \fBscf_tmpl_value_name_constraints()\fR 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
\fBscf_values_destroy()\fR on success.
.sp
.LP
The \fBscf_tmpl_value_count_range_constraints()\fR function will retrieve the
set of defined lower and upper bounds as defined by the property template and
place them in \fIranges\fR. Some templates will not specify any range
constraints.
.sp
.LP
The \fBscf_count_ranges_t\fR structure is populated by the
\fBscf_tmpl_value_count_range_constraints()\fR and
\fBscf_tmpl_value_count_range_choices()\fR functions.
\fBscf_count_ranges_destroy()\fR destroys an \fBscf_count_ranges_t\fR and all
memory associated with it.
.sp
.in +2
.nf
typedef struct scf_count_ranges {
        int             scr_num_ranges;
        uint64_t        *scr_min;
        uint64_t        *scr_max;
} scf_count_ranges_t;
.fi
.in -2

.sp
.LP
The \fBscf_tmpl_value_int_range_constraints()\fR function will retrieve the set
of defined lower and upper bounds as defined by the property template and place
them in \fIranges\fR. Some templates will not specify any range constraints.
.sp
.LP
The \fBscf_int_ranges_t\fR structure is populated by the
\fBscf_tmpl_value_int_range_constraints()\fR and
\fBscf_tmpl_value_int_range_choices()\fR functions. The
\fBscf_int_ranges_destroy()\fR function destroys an \fBscf_int_ranges_t\fR and
all memory associated with it.
.sp
.in +2
.nf
typedef struct scf_int_ranges {
        int             scr_num_ranges;
        int64_t         *scr_min;
        int64_t         *scr_max;
} scf_int_ranges_t;
.fi
.in -2

.sp
.LP
The \fBscf_tmpl_value_name_choices()\fR 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
\fBscf_values_destroy()\fR on success.
.sp
.LP
The \fBscf_tmpl_value_count_range_choices()\fR function will retrieve the set
of defined lower and upper bounds as defined by the property template and place
them in ranges\fI\fR. Some templates will not specify any range choices.
.sp
.LP
The \fBscf_tmpl_value_int_range_constraints()\fR function will retrieve the set
of defined lower and upper bounds as defined by the property template and place
them in \fIranges\fR. Some templates will not specify any range constraints.
.sp
.LP
The \fBscf_tmpl_value_common_name()\fR function will retrieve the value's
common name as currently templated and place it in *\fIout\fR. A locale (as
described in \fBsetlocale\fR(3C)) can be specified, or if the supplied locale
is \fINULL\fR, 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 *\fIout\fR buffer on success.
.sp
.LP
The \fBscf_tmpl_value_description()\fR function will retrieve the value's
description as currently templated and place it in *\fIout\fR. A locale (as
described in \fBsetlocale\fR(3C)) can be specified, or if the supplied locale
is \fINULL\fR, 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 *\fIout\fR buffer on success.
.sp
.LP
The \fBscf_tmpl_value_in_constraint()\fR 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:
.RS +4
.TP
.ie t \(bu
.el o
is of the proper type for the property template defined,
.RE
.RS +4
.TP
.ie t \(bu
.el o
is within a range defined, if it is a numeric type, and
.RE
.RS +4
.TP
.ie t \(bu
.el o
is within the name constraints, if name constraints are defined.
.RE
.sp
.LP
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 \fBstrtoull\fR(3C) and
\fBstrtoll\fR(3C) to see the implications when retrieving numeric values from
the repository or converting strings to numeric values in \fBlibscf\fR(3LIB).
.sp
.LP
If \fIerrs\fR is not \fINULL\fR, an \fBscf_tmpl_error_t\fR will be created,
populated and added to \fIerrs\fR in case of a constraint violation. The caller
is responsible for calling \fBscf_tmpl_errors_destroy()\fR to free memory
allocated for all \fBscf_tmpl_error_t\fR associated to \fIerrs\fR.
.SH RETURN VALUES
.sp
.LP
Upon successful completion, \fBscf_tmpl_prop_name()\fR,
\fBscf_tmpl_prop_common_name()\fR, \fBscf_tmpl_prop_description()\fR,
\fBscf_tmpl_prop_units()\fR, \fBscf_tmpl_value_common_name()\fR, and
\fBscf_tmpl_value_description()\fR return the length of the string written, not
including the terminating null byte. Otherwise, they return -1.
.sp
.LP
Upon successful completion, \fBscf_tmpl_prop_type()\fR,
\fBscf_tmpl_prop_required()\fR, \fBscf_tmpl_prop_visibility()\fR,
\fBscf_tmpl_prop_cardinality()\fR, \fBscf_tmpl_prop_internal_seps()\fR,
\fBscf_tmpl_value_name_constraints()\fR,
\fBscf_tmpl_value_count_range_constraints()\fR,
\fBscf_tmpl_value_int_range_constraints()\fR,
\fBscf_tmpl_value_name_choices()\fR,
\fBscf_tmpl_value_count_range_choices()\fR,
\fBscf_tmpl_value_int_range_choices()\fR return 0. Otherwise, they return -1.
.sp
.LP
The \fBscf_tmpl_value_in_constraint()\fR functions returns 0 on success, 1 if
the value is not in the constraint, and -1 on failure.
.sp
.LP
Upon successful completion, \fBscf_tmpl_visibility_to_string()\fR returns a
string of the visibility supplied.
.SH ERRORS
.sp
.LP
The \fBscf_tmpl_prop_name()\fR, \fBscf_tmpl_prop_type()\fR,
\fBscf_tmpl_prop_required()\fR, \fBscf_tmpl_prop_common_name()\fR,
\fBscf_tmpl_prop_description()\fR, \fBscf_tmpl_prop_units()\fR,
\fBscf_tmpl_prop_visibility()\fR, \fBscf_tmpl_prop_cardinality()\fR,
\fBscf_tmpl_prop_internal_seps()\fR, \fBscf_tmpl_value_name_constraints()\fR,
\fBscf_tmpl_value_count_range_constraints()\fR,
\fBscf_tmpl_value_int_range_constraints()\fR,
\fBscf_tmpl_value_name_choices()\fR,
\fBscf_tmpl_value_count_range_choices()\fR,
\fBscf_tmpl_value_int_range_choices()\fR, \fBscf_tmpl_value_common_name()\fR,
\fBscf_tmpl_value_description()\fR, and \fBscf_tmpl_value_in_constraint()\fR
functions will fail if:
.sp
.ne 2
.na
\fB\fBSCF_ERROR_BACKEND_ACCESS\fR\fR
.ad
.sp .6
.RS 4n
The storage mechanism that the repository server (\fBsvc.configd\fR(1M)) chose
for the operation denied access.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_CONNECTION_BROKEN\fR\fR
.ad
.sp .6
.RS 4n
The connection to the repository was lost.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_DELETED\fR\fR
.ad
.sp .6
.RS 4n
The template property group has been deleted.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_HANDLE_DESTROYED\fR\fR
.ad
.sp .6
.RS 4n
The handle passed in has been destroyed.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_INTERNAL\fR\fR
.ad
.sp .6
.RS 4n
An internal error occurred.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_NO_MEMORY\fR\fR
.ad
.sp .6
.RS 4n
There is not enough memory to populate the \fBscf_pg_tmpl_t\fR.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_NO_RESOURCES\fR\fR
.ad
.sp .6
.RS 4n
The server does not have adequate resources to complete the request.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_NOT_BOUND\fR\fR
.ad
.sp .6
.RS 4n
The handle is not currently bound.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_PERMISSION_DENIED\fR\fR
.ad
.sp .6
.RS 4n
The template could not be read due to access restrictions.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_TEMPLATE_INVALID\fR\fR
.ad
.sp .6
.RS 4n
The template data is invalid.
.RE

.sp
.LP
The \fBscf_tmpl_prop_type()\fR, \fBscf_tmpl_prop_common_name()\fR,
\fBscf_tmpl_prop_description()\fR, \fBscf_tmpl_prop_units()\fR,
\fBscf_tmpl_prop_cardinality()\fR, \fBscf_tmpl_prop_internal_seps()\fR,
\fBscf_tmpl_value_name_constraints()\fR,
\fBscf_tmpl_value_count_range_constraints()\fR,
\fBscf_tmpl_value_int_range_constraints()\fR,
\fBscf_tmpl_value_name_choices()\fR,
\fBscf_tmpl_value_count_range_choices()\fR,
\fBscf_tmpl_value_int_range_choices()\fR, \fBscf_tmpl_value_common_name()\fR,
and \fBscf_tmpl_value_description()\fR, functions will fail if:
.sp
.ne 2
.na
\fB\fBSCF_ERROR_NOT_FOUND\fR\fR
.ad
.RS 23n
The property does not exist or exists and has no value.
.RE

.sp
.LP
The \fBscf_tmpl_value_in_constraint()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
.ad
.RS 30n
Value is not a valid \fBscf_value_t\fR.
.RE

.sp
.LP
The \fBscf_tmpl_prop_common_name()\fR, \fBscf_tmpl_prop_description()\fR and
\fBscf_tmpl_prop_units()\fR functions will fail if:
.sp
.ne 2
.na
\fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
.ad
.RS 30n
The locale string is too long to make a property name.
.RE

.sp
.LP
The \fBscf_tmpl_value_common_name()\fR and \fBscf_tmpl_value_description()\fR
functions will fail if:
.sp
.ne 2
.na
\fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
.ad
.RS 30n
The value and locale strings are too long to make a property name.
.RE

.sp
.LP
The \fBscf_tmpl_value_count_range_constraints()\fR and
\fBscf_tmpl_value_count_range_choices()\fR functions will fail if:
.sp
.ne 2
.na
\fB\fBSCF_ERROR_CONSTRAINT_VIOLATED\fR\fR
.ad
.sp .6
.RS 4n
The range has negative values.
.RE

.sp
.LP
The \fBscf_tmpl_value_int_range_constraints()\fR and
\fBscf_tmpl_value_int_range_choices()\fR functions will fail if:
.sp
.ne 2
.na
\fB\fBSCF_ERROR_CONSTRAINT_VIOLATED\fR\fR
.ad
.sp .6
.RS 4n
The range values don't fit in a \fBint64_t\fR.
.RE

.sp
.LP
The \fBscf_tmpl_value_count_range_constraints()\fR,
\fBscf_tmpl_value_int_range_constraints()\fR,
\fBscf_tmpl_value_count_range_choices()\fR and
\fBscf_tmpl_value_int_range_choices()\fR functions will fail if:
.sp
.ne 2
.na
\fB\fBSCF_ERROR_CONSTRAINT_VIOLATED\fR\fR
.ad
.sp .6
.RS 4n
A range with \fImin\fR value > \fImax\fR value is found.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Committed
_
MT-Level	Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBsvc.configd\fR(1M), \fBscf_tmpl_prop_create\fR(3SCF), \fBsetlocale\fR(3C),
\fBstrtoll\fR(3C), \fBstrtoull\fR(3C), \fBattributes\fR(5),
\fBsmf_template\fR(5)