Service Configuration Facility Library Functions
scf_simple_prop_get(3SCF)
NAME
scf_simple_prop_get, scf_simple_prop_free,
scf_simple_app_props_get, scf_simple_app_props_free,
scf_simple_app_props_next, scf_simple_app_props_search,
scf_simple_prop_numvalues, scf_simple_prop_type,
scf_simple_prop_name, scf_simple_prop_pgname,
scf_simple_prop_next_boolean, scf_simple_prop_next_count,
scf_simple_prop_next_integer, scf_simple_prop_next_time,
scf_simple_prop_next_astring, scf_simple_prop_next_ustring,
scf_simple_prop_next_opaque, scf_simple_prop_next_reset -
simplified property read interface to Service Configuration FacilitySYNOPSIS
cc [ flag... ] file... -lscf [ library... ]
#include
scf_simple_prop_t *scf_simple_prop_get(scf_handle_t *handle,
const char *instance, const char *pgname, const char *propname);void scf_simple_prop_free(scf_simple_prop_t *prop);
scf_simple_app_props_t *scf_simple_app_props_get(scf_handle_t *handle,
const char *instance);void scf_simple_app_props_free(scf_simple_app_props_t *propblock);
const scf_simple_prop_t *scf_simple_app_props_next
(const scf_simple_app_props_t *propblock,scf_simple_prop_t *last);
const scf_simple_prop_t *scf_simple_app_props_search
(const scf_simple_app_props_t *propblock, const char *pgname,
const char *propname);ssize_t scf_simple_prop_numvalues(const scf_simple_prop_t *prop);
scf_type_t scf_simple_prop_type(const scf_simple_prop_t *prop);
const char *scf_simple_prop_name(const scf_simple_prop_t *prop);
const char *scf_simple_prop_pgname(const scf_simple_prop_t *prop);
SunOS 5.11 Last change: 7 Nov 2007 1
Service Configuration Facility Library Functionsscf_simple_prop_get(3SCF)
uint8_t *scf_simple_prop_next_boolean(const scf_simple_prop_t *prop);
uint64_t *scf_simple_prop_next_count(const scf_simple_prop_t *prop);
int64_t *scf_simple_prop_next_integer(const scf_simple_prop_t *prop);
int64_t *scf_simple_prop_next_time(const scf_simple_prop_t *prop,
int32_t *nsec);
char *scf_simple_prop_next_astring(const scf_simple_prop_t *prop);
char *scf_simple_prop_next_ustring(const scf_simple_prop_t *prop);
void *scf_simple_prop_next_opaque(const scf_simple_prop_t *prop,
size_t *length);
void *scf_simple_prop_next_reset(const scf_simple_prop_t *prop);
DESCRIPTION
The simplified read interface to the Service Configuration Facility deals with properties and blocks of properties.The scf_simple_prop_get() function pulls a single property.
The scf_simple_prop_*() functions operate on the resulting
scf_simple_prop_t.
The application might need to get many properties or iteratethrough all properties. The scf_simple_app_props_get() func-
tion gets all properties from the service instance that arein property groups of type 'application'. Individual proper-
ties are pulled from the block using thescf_simple_app_props_next() function for iteration or
scf_simple_app_props_search() to search. The pointer to the
scf_simple_prop_t returned from iteration or searching can
be acted upon using the scf_simple_prop_*() functions. Each
scf_*_get() function has an accompanying scf_*_free func-
tion. The application does not free the pointer to thescf_simple_prop_t returned from the
scf_simple_app_props_next() and
scf_simple_app_props_search() calls. A free call is only
used with a corresponding get call.SunOS 5.11 Last change: 7 Nov 2007 2
Service Configuration Facility Library Functionsscf_simple_prop_get(3SCF)
The scf_simple_prop_*() functions return references to the
read-only in-memory copy of the property information. Any
changes to this information results in unstable behavior and inaccurate results. The simplified read interface provides read access only, with no provisions to modify data in the service configuration facility repository.The scf_simple_prop_get() function takes as arguments a
bound handle, a service instance FMRI, and the property group and property name of a property. If handle is NULL, the library uses a temporary handle created for the purpose. If instance is NULL the library automatically finds the FMRI of the calling process. If pgname is NULL, the library uses the default application property group. The caller is responsible for freeing the returned property withscf_simple_prop_free().
The scf_simple_prop_free() function frees the
scf_simple_prop_t allocated by scf_simple_prop_get().
The scf_simple_app_props_get() function takes a bound handle
and a service instance FMRI and pulls all the applicationproperties into an scf_simple_app_props_t. If handle is
NULL, the library uses a temporary handle created for the purpose. If instance is NULL, the library looks up the instance FMRI of the process calling the function. Thecaller is responsible for freeing the scf_simple_app_props_t
with scf_simple_app_props_free().
The scf_simple_app_props_free() function frees the
scf_simple_app_props_t allocated by
scf_simple_app_props_get().
The scf_simple_app_props_next() function iterates over each
property in an scf_simple_app_props_t. It takes an
scf_simple_app_props_t pointer and the last property
returned from the previous call and returns the next pro-
perty in the scf_simple_app_props_t. Because the property is
a reference into the scf_simple_app_props_t, its lifetime
extends only until that structure is freed.Thescf_simple_app_props_search() function queries for an
exact match on a property in a property group. It takes an apps prop object, a property group name, and a property name, and returns a property pointer. Because the propertySunOS 5.11 Last change: 7 Nov 2007 3
Service Configuration Facility Library Functionsscf_simple_prop_get(3SCF)
is a reference into the scf_simple_app_props_t, its lifetime
extends only until that structure is freed. If the property group name, pgname, is NULL, "application" is used.The scf_simple_prop_numvalues() function takes a pointer to
a property and returns the number of values in that pro-
perty.The scf_simple_prop_type() function takes a pointer to a
property and returns the type of the property in anscf_type_t.
The scf_simple_prop_name() function takes a pointer to a
property and returns a pointer to the property name string.The scf_simple_prop_pgname() function takes a pointer to a
property and returns a pointer to the property group namestring. The scf_simple_prop_next_boolean(),
scf_simple_prop_next_count(),
scf_simple_prop_next_integer(),
scf_simple_prop_next_astring(), and
scf_simple_prop_next_ustring() functions take a pointer to a
property and return the first value in the property. Subse-
quent calls iterate over all the values in the property. The property's internal iteration can be reset withscf_simple_prop_next_reset().
The scf_simple_prop_next_time() function takes a pointer to
a property and the address of an allocated int32_t to hold
the nanoseconds field, and returns the first value in the property. Subsequent calls iterate over the property values.The scf_simple_prop_next_opaque() function takes a pointer
to a property and the address of an allocated integer to hold the size of the opaque buffer. It returns the first value in the property. Subsequent calls iterate over theproperty values, as do the scf_simple_prop_next_*() func-
tions. The scf_simple_prop_next_opaque() function writes the
size of the opaque buffer into the allocated integer.The scf_simple_prop_next_reset() function resets iteration
on a property, so that a call to one of thescf_simple_prop_next_*() functions returns the first value
in the property.SunOS 5.11 Last change: 7 Nov 2007 4
Service Configuration Facility Library Functionsscf_simple_prop_get(3SCF)
RETURN VALUES
Upon successful completion, scf_simple_prop_get() returns a
pointer to an allocated scf_simple_prop_t. Otherwise, it
returns NULL.Upon successful completion, scf_simple_app_props_get()
returns a pointer to an allocated scf_simple_app_props_t.
Otherwise, it returns NULL.Upon successful completion, scf_simple_app_props_next()
returns a pointer to an scf_simple_prop_t. Otherwise, it
returns NULL.Upon successful completion, scf_simple_app_props_search()
returns a pointer to an scf_simple_prop_t. Otherwise, it
returns NULL.Upon successful completion, scf_simple_prop_numvalues()
returns the number of values in a property. Otherwise, itreturns -1.
Upon successful completion, scf_simple_prop_type() returns
an scf_type_t. Otherwise, it returns -1.
Upon successful completion, scf_simple_prop_name() and
scf_simple_prop_pgname() return character pointers. Other-
wise, they return NULL.Upon successful completion, scf_simple_prop_next_boolean(),
scf_simple_prop_next_count(),
scf_simple_prop_next_integer(), scf_simple_prop_next_time(),
scf_simple_prop_next_astring(),
scf_simple_prop_next_ustring(), and
scf_simple_prop_next_opaque() return a pointer to the next
value in the property. After all values have been returned,NULL is returned and SCF_ERROR_NONE is set. On failure, NULL
is returned and the appropriate error value is set.ERRORS
The scf_simple_prop_get() and scf_simple_app_props_get()
functions will fail if:SCF_ERROR_CONNECTION_BROKEN
SunOS 5.11 Last change: 7 Nov 2007 5
Service Configuration Facility Library Functionsscf_simple_prop_get(3SCF)
The connection to the datastore is broken.SCF_ERROR_INVALID_ARGUMENT
The instance FMRI is invalid or property name is NULL.SCF_ERROR_NO_MEMORY
The memory allocation failed.SCF_ERROR_NOT_BOUND
The connection handle is not bound.SCF_ERROR_NOT_FOUND
The specified instance or property does not exist.SCF_ERROR_PERMISSION_DENIED
The caller is not authorized to read the property's value(s).The scf_simple_app_props_next() function will fail if:
SCF_ERROR_NOT_SET The value of the propblock argument is
NULL.The scf_simple_app_props_search() function will fail if:
SCF_ERROR_NOT_FOUND The property was not found.
SCF_ERROR_NOT_SET The value of the propblock or prop-
name argument is NULL.The scf_simple_prop_numvalues(), scf_simple_prop_type(),
scf_simple_prop_name(), and scf_simple_prop_pgname() func-
tions will fail if:SunOS 5.11 Last change: 7 Nov 2007 6
Service Configuration Facility Library Functionsscf_simple_prop_get(3SCF)
SCF_ERROR_NOT_SET The property is NULL.
The scf_simple_prop_next_boolean(),
scf_simple_prop_next_count(),
scf_simple_prop_next_integer(), scf_simple_prop_next_time(),
scf_simple_prop_next_astring(),
scf_simple_prop_next_ustring(), and
scf_simple_prop_next_opaque() functions will fail if:
SCF_ERROR_NOT_SET The property is NULL.
SCF_ERROR_TYPE_MISMATCH The requested type does not match
the property type.EXAMPLES
Example 1 Simple Property Get /* * In this example, we pull the property named "size" from the * default property group. We make sure that the property * isn't empty, and then copy it into the sizeval variable. */scf_simple_prop_t *prop;
ssize_t numvals;
int64_t *sizeval;
prop = scf_simple_prop_get(
"svc://localhost/category/service/instance", NULL, "size");numvals = scf_simple_prop_numvalues(prop);
if(numvals > 0){sizeval = scf_simple_prop_next_integer(prop);
}scf_simple_prop_free(prop);
Example 2 Property Iterationscf_simple_prop_t *prop;
scf_simple_app_props_t *appprops;
appprops = scf_simple_app_props_get(
"svc://localhost/category/service/instance");SunOS 5.11 Last change: 7 Nov 2007 7
Service Configuration Facility Library Functionsscf_simple_prop_get(3SCF)
prop = scf_simple_app_props_next(appprops, NULL);
while(prop != NULL) { /* * This iteration will go through every property in the * instance's application block. The user can use * the set of property functions to pull the values out * of prop, as seen in other examples. */ (...code acting on each property...)prop = scf_simple_app_props_next(appprops, prop);
}scf_simple_app_props_free(appprops);
Example 3 Property Searching /* * In this example, we pull the property block from the instance, * and then query it. Generally speaking, the simple get would * be used for an example like this, but for the purposes of* illustration, the non-simple approach is used. The property
* is a list of integers that are pulled into an array. * Note how val is passed back into each call, as described above. */scf_simple_app_props_t *appprops;
scf_simple_prop_t *prop;
int i;int64_t *intlist;
ssize_t numvals;
appprops = scf_simple_app_props_get(
"svc://localhost/category/service/instance");prop = scf_simple_app_props_search(appprops, "appname", "numlist");
if(prop != NULL){numvals = scf_simple_prop_numvalues(prop);
if(numvals > 0){intlist = malloc(numvals * sizeof(int64_t));
SunOS 5.11 Last change: 7 Nov 2007 8
Service Configuration Facility Library Functionsscf_simple_prop_get(3SCF)
val = scf_simple_prop_next_integer(prop);
for(i=0, i < numvals, i++){ intlist[i] = *val;val = scf_simple_prop_next_integer(prop);
} } }scf_simple_app_props_free(appprops);
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | Committed ||_____________________________|_____________________________|
| MT-Level | Safe |
|_____________________________|_____________________________|
SEE ALSO
libscf(3LIB), scf_error(3SCF), attributes(5)
SunOS 5.11 Last change: 7 Nov 2007 9
Service Configuration Facility Library Functionsscf_simple_prop_get(3SCF)
SunOS 5.11 Last change: 7 Nov 2007 10