Service Configuration Facility Library Functions
scfsimplepropget(3SCF)
NAME
scfsimplepropget, scfsimplepropfree,
scfsimpleapppropsget, scfsimpleapppropsfree,
scfsimpleapppropsnext, scfsimpleapppropssearch,
scfsimplepropnumvalues, scfsimpleproptype,
scfsimplepropname, scfsimpleproppgname,
scfsimplepropnextboolean, scfsimplepropnextcount,
scfsimplepropnextinteger, scfsimplepropnexttime,
scfsimplepropnextastring, scfsimplepropnextustring,
scfsimplepropnextopaque, scfsimplepropnextreset -
simplified property read interface to Service Configuration
Facility
SYNOPSIS
cc [ flag... ] file... -lscf [ library... ]
#include
scfsimplepropt *scfsimplepropget(scfhandlet *handle,
const char *instance, const char *pgname, const char *propname);
void scfsimplepropfree(scfsimplepropt *prop);
scfsimpleapppropst *scfsimpleapppropsget(scfhandlet *handle,
const char *instance);
void scfsimpleapppropsfree(scfsimpleapppropst *propblock);
const scfsimplepropt *scfsimpleapppropsnext
(const scfsimpleapppropst *propblock,scfsimplepropt *last);
const scfsimplepropt *scfsimpleapppropssearch
(const scfsimpleapppropst *propblock, const char *pgname,
const char *propname);
ssizet scfsimplepropnumvalues(const scfsimplepropt *prop);
scftypet scfsimpleproptype(const scfsimplepropt *prop);
const char *scfsimplepropname(const scfsimplepropt *prop);
const char *scfsimpleproppgname(const scfsimplepropt *prop);
SunOS 5.11 Last change: 7 Nov 2007 1
Service Configuration Facility Library Functions
scfsimplepropget(3SCF)
uint8t *scfsimplepropnextboolean(const scfsimplepropt *prop);
uint64t *scfsimplepropnextcount(const scfsimplepropt *prop);
int64t *scfsimplepropnextinteger(const scfsimplepropt *prop);
int64t *scfsimplepropnexttime(const scfsimplepropt *prop,
int32t *nsec);
char *scfsimplepropnextastring(const scfsimplepropt *prop);
char *scfsimplepropnextustring(const scfsimplepropt *prop);
void *scfsimplepropnextopaque(const scfsimplepropt *prop,
sizet *length);
void *scfsimplepropnextreset(const scfsimplepropt *prop);
DESCRIPTION
The simplified read interface to the Service Configuration
Facility deals with properties and blocks of properties.
The scfsimplepropget() function pulls a single property.
The scfsimpleprop*() functions operate on the resulting
scfsimplepropt.
The application might need to get many properties or iterate
through all properties. The scfsimpleapppropsget() func-
tion gets all properties from the service instance that are
in property groups of type 'application'. Individual proper-
ties are pulled from the block using the
scfsimpleapppropsnext() function for iteration or
scfsimpleapppropssearch() to search. The pointer to the
scfsimplepropt returned from iteration or searching can
be acted upon using the scfsimpleprop*() functions. Each
scf*get() function has an accompanying scf*free func-
tion. The application does not free the pointer to the
scfsimplepropt returned from the
scfsimpleapppropsnext() and
scfsimpleapppropssearch() 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 Functions
scfsimplepropget(3SCF)
The scfsimpleprop*() 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 scfsimplepropget() function takes as arguments a
bound handle, a service instance FMRI, and the property
group and property name of a property. If handle is NUL,
the library uses a temporary handle created for the purpose.
If instance is NUL the library automatically finds the FMRI
of the calling process. If pgname is NUL, the library uses
the default application property group. The caller is
responsible for freeing the returned property with
scfsimplepropfree().
The scfsimplepropfree() function frees the
scfsimplepropt allocated by scfsimplepropget().
The scfsimpleapppropsget() function takes a bound handle
and a service instance FMRI and pulls all the application
properties into an scfsimpleapppropst. If handle is
NUL, the library uses a temporary handle created for the
purpose. If instance is NUL, the library looks up the
instance FMRI of the process calling the function. The
caller is responsible for freeing the scfsimpleapppropst
with scfsimpleapppropsfree().
The scfsimpleapppropsfree() function frees the
scfsimpleapppropst allocated by
scfsimpleapppropsget().
The scfsimpleapppropsnext() function iterates over each
property in an scfsimpleapppropst. It takes an
scfsimpleapppropst pointer and the last property
returned from the previous call and returns the next pro-
perty in the scfsimpleapppropst. Because the property is
a reference into the scfsimpleapppropst, its lifetime
extends only until that structure is freed.
Thescfsimpleapppropssearch() 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 property
SunOS 5.11 Last change: 7 Nov 2007 3
Service Configuration Facility Library Functions
scfsimplepropget(3SCF)
is a reference into the scfsimpleapppropst, its lifetime
extends only until that structure is freed. If the property
group name, pgname, is NUL, "application" is used.
The scfsimplepropnumvalues() function takes a pointer to
a property and returns the number of values in that pro-
perty.
The scfsimpleproptype() function takes a pointer to a
property and returns the type of the property in an
scftypet.
The scfsimplepropname() function takes a pointer to a
property and returns a pointer to the property name string.
The scfsimpleproppgname() function takes a pointer to a
property and returns a pointer to the property group name
string. The scfsimplepropnextboolean(),
scfsimplepropnextcount(),
scfsimplepropnextinteger(),
scfsimplepropnextastring(), and
scfsimplepropnextustring() 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 with
scfsimplepropnextreset().
The scfsimplepropnexttime() function takes a pointer to
a property and the address of an allocated int32t to hold
the nanoseconds field, and returns the first value in the
property. Subsequent calls iterate over the property values.
The scfsimplepropnextopaque() 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 the
property values, as do the scfsimplepropnext*() func-
tions. The scfsimplepropnextopaque() function writes the
size of the opaque buffer into the allocated integer.
The scfsimplepropnextreset() function resets iteration
on a property, so that a call to one of the
scfsimplepropnext*() functions returns the first value
in the property.
SunOS 5.11 Last change: 7 Nov 2007 4
Service Configuration Facility Library Functions
scfsimplepropget(3SCF)
RETURN VALUES
Upon successful completion, scfsimplepropget() returns a
pointer to an allocated scfsimplepropt. Otherwise, it
returns NUL.
Upon successful completion, scfsimpleapppropsget()
returns a pointer to an allocated scfsimpleapppropst.
Otherwise, it returns NUL.
Upon successful completion, scfsimpleapppropsnext()
returns a pointer to an scfsimplepropt. Otherwise, it
returns NUL.
Upon successful completion, scfsimpleapppropssearch()
returns a pointer to an scfsimplepropt. Otherwise, it
returns NUL.
Upon successful completion, scfsimplepropnumvalues()
returns the number of values in a property. Otherwise, it
returns -1.
Upon successful completion, scfsimpleproptype() returns
an scftypet. Otherwise, it returns -1.
Upon successful completion, scfsimplepropname() and
scfsimpleproppgname() return character pointers. Other-
wise, they return NUL.
Upon successful completion, scfsimplepropnextboolean(),
scfsimplepropnextcount(),
scfsimplepropnextinteger(), scfsimplepropnexttime(),
scfsimplepropnextastring(),
scfsimplepropnextustring(), and
scfsimplepropnextopaque() return a pointer to the next
value in the property. After all values have been returned,
NUL is returned and SCFERORNONE is set. On failure, NUL
is returned and the appropriate error value is set.
ERORS
The scfsimplepropget() and scfsimpleapppropsget()
functions will fail if:
SCFERORCONECTIONBROKEN
SunOS 5.11 Last change: 7 Nov 2007 5
Service Configuration Facility Library Functions
scfsimplepropget(3SCF)
The connection to the datastore is broken.
SCFERORINVALIDARGUMENT
The instance FMRI is invalid or property name is NUL.
SCFERORNOMEMORY
The memory allocation failed.
SCFERORNOTBOUND
The connection handle is not bound.
SCFERORNOTFOUND
The specified instance or property does not exist.
SCFERORPERMISIONDENIED
The caller is not authorized to read the property's
value(s).
The scfsimpleapppropsnext() function will fail if:
SCFERORNOTSET The value of the propblock argument is
NUL.
The scfsimpleapppropssearch() function will fail if:
SCFERORNOTFOUND The property was not found.
SCFERORNOTSET The value of the propblock or prop-
name argument is NUL.
The scfsimplepropnumvalues(), scfsimpleproptype(),
scfsimplepropname(), and scfsimpleproppgname() func-
tions will fail if:
SunOS 5.11 Last change: 7 Nov 2007 6
Service Configuration Facility Library Functions
scfsimplepropget(3SCF)
SCFERORNOTSET The property is NUL.
The scfsimplepropnextboolean(),
scfsimplepropnextcount(),
scfsimplepropnextinteger(), scfsimplepropnexttime(),
scfsimplepropnextastring(),
scfsimplepropnextustring(), and
scfsimplepropnextopaque() functions will fail if:
SCFERORNOTSET The property is NUL.
SCFERORTYPEMISMATCH 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.
*/
scfsimplepropt *prop;
ssizet numvals;
int64t *sizeval;
prop = scfsimplepropget(
"svc:/localhost/category/service/instance",
NUL, "size");
numvals = scfsimplepropnumvalues(prop);
if(numvals > 0){
sizeval = scfsimplepropnextinteger(prop);
}
scfsimplepropfree(prop);
Example 2 Property Iteration
scfsimplepropt *prop;
scfsimpleapppropst *appprops;
appprops = scfsimpleapppropsget(
"svc:/localhost/category/service/instance");
SunOS 5.11 Last change: 7 Nov 2007 7
Service Configuration Facility Library Functions
scfsimplepropget(3SCF)
prop = scfsimpleapppropsnext(appprops, NUL);
while(prop != NUL)
{
/*
* 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 = scfsimpleapppropsnext(appprops, prop);
}
scfsimpleapppropsfree(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.
*/
scfsimpleapppropst *appprops;
scfsimplepropt *prop;
int i;
int64t *intlist;
ssizet numvals;
appprops = scfsimpleapppropsget(
"svc:/localhost/category/service/instance");
prop = scfsimpleapppropssearch(appprops, "appname", "numlist");
if(prop != NUL){
numvals = scfsimplepropnumvalues(prop);
if(numvals > 0){
intlist = malloc(numvals * sizeof(int64t));
SunOS 5.11 Last change: 7 Nov 2007 8
Service Configuration Facility Library Functions
scfsimplepropget(3SCF)
val = scfsimplepropnextinteger(prop);
for(i=0, i < numvals, i]){
intlist[i] = *val;
val = scfsimplepropnextinteger(prop);
}
}
}
scfsimpleapppropsfree(appprops);
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Committed
MT-Level Safe
SEE ALSO
libscf(3LIB), scferror(3SCF), attributes(5)
SunOS 5.11 Last change: 7 Nov 2007 9
Service Configuration Facility Library Functions
scfsimplepropget(3SCF)
SunOS 5.11 Last change: 7 Nov 2007 10
|
