|
|
cfg_subsys_query_all(3)
Contents
|
cfg_subsys_query_all - determine the value of all
attributes for a subsystem
#include <cfg.h>
cfg_status_t cfg_subsys_query_all(
cfg_handle_t *handle,
caddr_t subsys,
cfg_attr_t **attributes,
int *nattributes );
Configuration Management Library (libcfg.a)
Structure identifying the means of communication between
your application and the configuration management server.
For local requests, pass NULL in this parameter. For
remote requests, pass the value returned from the cfg_connect()
routine. Specifies the name of the subsystem for
which you are getting attribute values. Returns information
about all attributes for the named subsystem. The
information includes the data type of the attribute, the
list of operations supported by that attribute, the
attribute-specific status of the query operation, the minimum
and maximum allowed values for the attribute, and the
current value of the attribute. For binary data items, the
information includes the size of the attribute's current
value. The system allocates memory for this array, which
you should free when the information in the array is no
longer needed, as shown in the EXAMPLES section. An integer
value specifying the number of attributes for which
information has been returned.
Use the cfg_subsys_query_all() routine to get information
about all the attributes for a particular subsystem.
When your application calls the cfg_subsys_query_all()
routine, it passes the name of the subsystem for which you
want information. The system reads the subsystem name and
finds and collects the information about its attributes.
The system then returns that information to your application.
For array-type attributes, each individual array element
will be returned in a separate cfg_attr_t structure and
the index field will have the index value of the array
element.
The information returned from the cfg_subsys_query_all()
routine is passed in a structure of type cfg_attr_t. If
the subsystem has more than one attribute, an array of
structures is returned. For information about this structure,
see libcfg(3).
The following list describes the information returned to
your application when it calls the cfg_subsys_query_all()
routine: Attributes can be integer, string, or binary
data. As defined in <sys/sysconfig.h>, the integer data
types can be CFG_ATTR_INTTYPE (int), CFG_ATTR_UINTTYPE
(uint), CFG_ATTR_LONGTYPE (long), or CFG_ATTR_ULONGTYPE
(ulong). The string data type is a character string type
named CFG_ATTR_STRTYPE and the binary data type is
CFG_ATTR_BINTYPE. The definition of each attribute in the
subsystem code determines what operations you can perform
on the attribute. The possible operation codes are
CFG_OP_QUERY (you can request information about the
attribute), CFG_OP_CONFIGURE (you can set the attribute
value when the subsystem is initially configured), and
CFG_OP_RECONFIGURE (you can modify the value of the
attribute). During a query request, each attribute is
assigned a status. The following table describes the status
values your application might receive from the
cfg_subsys_query_all() routine:
------------------------------------------------------
Status Code Meaning
------------------------------------------------------
CFG_ATTR_SUCCESS Successful operation
CFG_ATTR_EEXISTS No attribute by that name exists
CFG_ATTR_EOP Attribute does not support the
query operation
CFG_ATTR_ESUBSYS Subsystem failure (code within the
subsystem returned an error)
CFG_ATTR_EINDEX The index for an indexed attribute
is out of range
CFG_ATTR_EMEM Unable to allocate memory to
return the attribute value
------------------------------------------------------
The value of each attribute is returned in a structure.
In addition to the attribute value, this
structure returns the minimum and maximum value for
the attribute and the disposal routine, if any, to
be called once the attribute value is returned. For
binary attributes, the length of attribute's current
value is also returned. (The disposal routine
is used to free kernel memory occupied by string
and binary data.)
Upon successful completion, cfg_subsys_query_all() returns
CFG_SUCCESS. Other return values indicate that an error
has occurred. For information about handling return values
from routines in the configuration management library, see
libcfg(3).
The following example illustrates the use of the cfg_subsys_query_all()
library routine:
cfg_attr_t *attributes; cfg_status_t
retval; cfg_handle_t handle; int
nattributes; int i;
/***************************************************/ /*
Call the cfg_subsys_query_all routine */
retval = cfg_subsys_query_all(&handle, "vfs", &attributes,
&nattributes);
if (retval != CFG_SUCCESS)
print_error (retval);
else {
/* Use data returned from the query */
for (i=0; i<nattributes; i++) {
printf ("%s", attributes[i].name);
if (attributes[i].status != CFG_ATTR_SUCCESS) {
switch (attributes[i].status){
case CFG_ATTR_EOP:
printf("attribute does not allow this operation\n");
break;
.
.
.
default:
printf("unknown error\n");
break;
}
continue;
}
/* Display attribute value to application user */
switch (attributes[i].type){
case CFG_ATTR_INTTYPE:
printf ("%d\n", (int)
attributes[i].attr.num.val);
break;
.
.
.
case CFG_ATTR_STRTYPE:
printf ("%s\n", (int)
attributes[i].attr.str.val);
free(attributes[i].attr.str.val);
break;
case CFG_ATTR_BINTYPE:
printf ("%d bytes of binary data received\n",
(int) \
attributes[i].attr.bin.val_size);
free(attributes[i].attr.str.val);
break;
}
}
/* Free the memory allocated by the configuration management
*/
/* library
*/
free(attributes); }
In this example, the application requests information
about all attributes of the vfs subsystem. When the
cfg_subsys_query_all() routine returns information about
those attributes, the application tests the return status
of the routine. The application reports any errors
returned. If cfg_subsys_query_all() returns CFG_SUCCESS,
the status for each attribute is tested and any errors are
reported. The application displays the value of
attributes that return CFG_ATTR_SUCCESS.
Commands: cfgmgr(8), sysconfig(8)
Routines: cfg_subsys_query(3), libcfg(3)
cfg_subsys_query_all(3)
[ Back ] |
