Service Configuration Facility Library Functions
scftmplpropname(3SCF)
NAME
scftmplpropname, scftmplproptype,
scftmplproprequired, scftmplpropcommonname,
scftmplpropdescription, scftmplpropunits,
scftmplpropvisibility, scftmplvisibilitytostring,
scftmplpropcardinality, scftmplpropinternalseps,
scftmplvaluenameconstraints, scfcountrangesdestroy,
scfintrangesdestroy,
scftmplvaluecountrangeconstraints,
scftmplvalueintrangeconstraints,
scftmplvaluenamechoices, scfvaluesdestroy,
scftmplvaluecountrangechoices,
scftmplvalueintrangechoices,
scftmplvaluecommonname, scftmplvaluedescription,
scftmplvalueinconstraint - retrieve the metadata about a
specific property
SYNOPSIS
cc [ flag... ] file... -lscf [ library... ]
#include
ssizet scftmplpropname(const scfproptmplt *proptmpl,
char **out);
int scftmplproptype(const scfproptmplt *proptmpl,
scftypet *out);
int scftmplproprequired(const scfproptmplt *proptmpl,
uint8t *out)
ssizet scftmplpropcommonname(const scfproptmplt *proptmpl,
char *locale, char **out);
ssizet scftmplpropdescription(const scfproptmplt *proptmpl,
char * locale, char **out);
ssizet scftmplpropunits(const scfproptmplt *proptmpl,
const char *locale, char **out);
int scftmplpropvisibility(const scfproptmplt *proptmpl,
uint8t *out);
const char *scftmplvisibilitytostring(uint8t visibility);
SunOS 5.11 Last change: 28 Oct 2008 1
Service Configuration Facility Library Functions
scftmplpropname(3SCF)
int scftmplpropcardinality(const scfproptmplt *proptmpl,
uint64t *min, uint64t *max);
int scftmplpropinternalseps(const scfproptmplt *proptmpl,
scfvaluest *out);
int scftmplvaluenameconstraints(const scfproptmplt *proptmpl,
scfvaluest *out);
void scfcountrangesdestroy(scfcountrangest *ranges);
void scfintrangesdestroy(scfintrangest *ranges);
int scftmplvaluecountrangeconstraints(
const scfproptmplt *proptmpl, scfcountrangest *ranges);
int scftmplvalueintrangeconstraints(
const scfproptmplt *proptmpl, scfintrangest *ranges);
int scftmplvaluenamechoices(const scfproptmplt *proptmpl,
scfvaluest *vals);
void scfvaluesdestroy(scfvaluest *vals);
int scftmplvaluecountrangechoices(
const scfproptmplt *proptmpl, scfcountrangest *ranges);
int scftmplvalueintrangechoices(const scfproptmplt *proptmpl,
scfintrangest *ranges);
ssizet scftmplvaluecommonname(const scfproptmplt *proptmpl,
const char *locale, const char *value, char **out);
ssizet scftmplvaluedescription(const scfproptmplt *proptmpl,
const char *locale, const char *value, char **out);
int scftmplvalueinconstraint(const scfproptmplt *proptmpl,
scfvaluet *value, scftmplerrorst **errs);
SunOS 5.11 Last change: 28 Oct 2008 2
Service Configuration Facility Library Functions
scftmplpropname(3SCF)
DESCRIPTION
These functions retrieve the metadata about a specific pro-
perty. They require that the template for the property has
already been located by one of the
scftmplpropcreate(3SCF) suite of functions.
The scftmplpropname() 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 scftmplproptype() function will retrieve the type of
the property as templated and place the type in out.
The scftmplproprequired() 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 scftmplpropcommonname() 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 NUL, the
current locale will be used. If a common name in the speci-
fied 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 scftmplpropdescription() 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 NUL, the
current locale will be used. If a description in the speci-
fied 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 scftmplpropvisibility() function will retrieve the
visibility of the property as currently templated and place
it in out. A property can be SCFTMPLVISIBILITYHIDEN,
SCFTMPLVISIBILITYREADONLY, or
SCFTMPLVISIBILITYREADWRITE. If the visibility is unset,
SunOS 5.11 Last change: 28 Oct 2008 3
Service Configuration Facility Library Functions
scftmplpropname(3SCF)
this function will return the default,
SCFTMPLVISIBILITYREADWRITE.
The scftmplpropcardinality() 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 UINT64MAX for max.
The scfvaluesdestroy() function destroys an scfvaluest
structure and all memory associated with it.
The scfvaluest structure is populated by a number of func-
tions. 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 scftime {
int64t tseconds;
int32t tns;
} scftimet;
typedef struct scfvalues {
scftypet valuetype;
char *reserved;
int valuecount;
const char **valuesasastring;
union {
uint64t *vcount;
uint8t *vboolean;
int64t *vinteger;
char **vastring;
char **vustring;
char **vopaque;
scftimet *vtime;
} svdata;
} scfvaluest;
The scftmplpropinternalseps() function will retrieve the
list of internal separators as currently defined in the tem-
plate. 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 cal-
ling scfvaluesdestroy() on success.
SunOS 5.11 Last change: 28 Oct 2008 4
Service Configuration Facility Library Functions
scftmplpropname(3SCF)
The scftmplvaluenameconstraints() 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 scfvaluesdestroy()
on success.
The scftmplvaluecountrangeconstraints() 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 scfcountrangest structure is populated by the
scftmplvaluecountrangeconstraints() and
scftmplvaluecountrangechoices() functions.
scfcountrangesdestroy() destroys an scfcountrangest
and all memory associated with it.
typedef struct scfcountranges {
int scrnumranges;
uint64t *scrmin;
uint64t *scrmax;
} scfcountrangest;
The scftmplvalueintrangeconstraints() 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 scfintrangest structure is populated by the
scftmplvalueintrangeconstraints() and
scftmplvalueintrangechoices() functions. The
scfintrangesdestroy() function destroys an
scfintrangest and all memory associated with it.
typedef struct scfintranges {
int scrnumranges;
int64t *scrmin;
int64t *scrmax;
} scfintrangest;
The scftmplvaluenamechoices() 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 scfvaluesdestroy() on
SunOS 5.11 Last change: 28 Oct 2008 5
Service Configuration Facility Library Functions
scftmplpropname(3SCF)
success.
The scftmplvaluecountrangechoices() 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 scftmplvalueintrangeconstraints() 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 scftmplvaluecommonname() 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 speci-
fied, or if the supplied locale is NUL, 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 com-
mon name. The caller is responsible for freeing the *out
buffer on success.
The scftmplvaluedescription() function will retrieve the
value's description as currently templated and place it in
*out. A locale (as described in setlocale(3C)) can be speci-
fied, or if the supplied locale is NUL, 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 scftmplvalueinconstraint() 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.
SunOS 5.11 Last change: 28 Oct 2008 6
Service Configuration Facility Library Functions
scftmplpropname(3SCF)
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 con-
straint when tested as one numeric type but within con-
straint 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 NUL, an scftmplerrort will be created,
populated and added to errs in case of a constraint viola-
tion. The caller is responsible for calling
scftmplerrorsdestroy() to free memory allocated for all
scftmplerrort associated to errs.
RETURN VALUES
Upon successful completion, scftmplpropname(),
scftmplpropcommonname(), scftmplpropdescription(),
scftmplpropunits(), scftmplvaluecommonname(), and
scftmplvaluedescription() return the length of the string
written, not including the terminating null byte. Otherwise,
they return -1.
Upon successful completion, scftmplproptype(),
scftmplproprequired(), scftmplpropvisibility(),
scftmplpropcardinality(), scftmplpropinternalseps(),
scftmplvaluenameconstraints(),
scftmplvaluecountrangeconstraints(),
scftmplvalueintrangeconstraints(),
scftmplvaluenamechoices(),
scftmplvaluecountrangechoices(),
scftmplvalueintrangechoices() return 0. Otherwise, they
return -1.
The scftmplvalueinconstraint() functions returns 0 on
success, 1 if the value is not in the constraint, and -1 on
failure.
Upon successful completion, scftmplvisibilitytostring()
returns a string of the visibility supplied.
ERORS
The scftmplpropname(), scftmplproptype(),
scftmplproprequired(), scftmplpropcommonname(),
scftmplpropdescription(), scftmplpropunits(),
scftmplpropvisibility(), scftmplpropcardinality(),
scftmplpropinternalseps(),
SunOS 5.11 Last change: 28 Oct 2008 7
Service Configuration Facility Library Functions
scftmplpropname(3SCF)
scftmplvaluenameconstraints(),
scftmplvaluecountrangeconstraints(),
scftmplvalueintrangeconstraints(),
scftmplvaluenamechoices(),
scftmplvaluecountrangechoices(),
scftmplvalueintrangechoices(),
scftmplvaluecommonname(), scftmplvaluedescription(),
and scftmplvalueinconstraint() functions will fail if:
SCFERORBACKENDACES
The storage mechanism that the repository server
(svc.configd(1M)) chose for the operation denied access.
SCFERORCONECTIONBROKEN
The connection to the repository was lost.
SCFERORDELETED
The template property group has been deleted.
SCFERORHANDLEDESTROYED
The handle passed in has been destroyed.
SCFERORINTERNAL
An internal error occurred.
SCFERORNOMEMORY
There is not enough memory to populate the
scfpgtmplt.
SCFERORNORESOURCES
The server does not have adequate resources to complete
the request.
SCFERORNOTBOUND
The handle is not currently bound.
SunOS 5.11 Last change: 28 Oct 2008 8
Service Configuration Facility Library Functions
scftmplpropname(3SCF)
SCFERORPERMISIONDENIED
The template could not be read due to access restric-
tions.
SCFERORTEMPLATEINVALID
The template data is invalid.
The scftmplproptype(), scftmplpropcommonname(),
scftmplpropdescription(), scftmplpropunits(),
scftmplpropcardinality(), scftmplpropinternalseps(),
scftmplvaluenameconstraints(),
scftmplvaluecountrangeconstraints(),
scftmplvalueintrangeconstraints(),
scftmplvaluenamechoices(),
scftmplvaluecountrangechoices(),
scftmplvalueintrangechoices(),
scftmplvaluecommonname(), and
scftmplvaluedescription(), functions will fail if:
SCFERORNOTFOUND The property does not exist or exists
and has no value.
The scftmplvalueinconstraint() function will fail if:
SCFERORINVALIDARGUMENT Value is not a valid
scfvaluet.
The scftmplpropcommonname(), scftmplpropdescription()
and scftmplpropunits() functions will fail if:
SCFERORINVALIDARGUMENT The locale string is too long
to make a property name.
The scftmplvaluecommonname() and
scftmplvaluedescription() functions will fail if:
SCFERORINVALIDARGUMENT The value and locale strings
are too long to make a pro-
perty name.
SunOS 5.11 Last change: 28 Oct 2008 9
Service Configuration Facility Library Functions
scftmplpropname(3SCF)
The scftmplvaluecountrangeconstraints() and
scftmplvaluecountrangechoices() functions will fail if:
SCFERORCONSTRAINTVIOLATED
The range has negative values.
The scftmplvalueintrangeconstraints() and
scftmplvalueintrangechoices() functions will fail if:
SCFERORCONSTRAINTVIOLATED
The range values don't fit in a int64t.
The scftmplvaluecountrangeconstraints(),
scftmplvalueintrangeconstraints(),
scftmplvaluecountrangechoices() and
scftmplvalueintrangechoices() functions will fail if:
SCFERORCONSTRAINTVIOLATED
A range with min value > max value is found.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Committed
MT-Level Safe
SEE ALSO
svc.configd(1M), scftmplpropcreate(3SCF), setlocale(3C),
strtoll(3C), strtoull(3C), attributes(5), smftemplate(5)
SunOS 5.11 Last change: 28 Oct 2008 10
Service Configuration Facility Library Functions
scftmplpropname(3SCF)
SunOS 5.11 Last change: 28 Oct 2008 11
|
