|
|
cfg_subsys_query(3)
Contents
|
cfg_subsys_query - determine the value of selected subsystem
attributes
#include <cfg.h>
cfg_status_t cfg_subsys_query(
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. On input, names
the attributes for which you are requesting a value.
On return, contains information about the named
attributes. 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. An integer value specifying the
number of attributes for which you are requesting
information.
Use the cfg_subsys_query() routine to get information
about a list of subsystem attributes. You can get information
about one or more attributes.
When your application calls the cfg_subsys_query() routine,
it passes the subsystem name and a list of attribute
names to the system. The system reads this information and
finds and collects the information about the named
attributes. The system then returns the attribute information
to your application.
The information returned from the cfg_subsys_query() routine
is passed in a structure of type cfg_attr_t. If your
application requests information about more than one
attribute, an array of structures is returned. For information
about this structure, see libcfg(3).
To query an individual array element, on input the index
field of the cfg_attr_t structure must be set to the index
value of the array element.
The following list describes the information returned to
your application when it calls the cfg_subsys_query() 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 code 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, the system assigns a status to each
attribute. The following table describes the status values
that your application might receive from the cfg_subsys_query()
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, the disposal routine, if any, to be
called once the attribute value is returned, and
for binary attributes, the length of the current
value of the attribute. (The disposal routine is
used to free kernel memory occupied by string and
binary data.)
Upon successful completion, cfg_subsys_query() 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()
library routine:
cfg_attr_t attributes[2]; cfg_status_t
retval; cfg_handle_t handle; int
i;
/*****************************************************/ /*
Initialize attribute names for the query */
strcpy (attributes[0].name, "bufcache"); strcpy
(attributes[1].name, "max-vnodes");
/***************************************************/ /*
Call the cfg_subsys_query routine */
retval = cfg_subsys_query(&handle, "vfs", attributes, 2);
if (retval != CFG_SUCCESS)
print_error (retval);
else {
/* Use data returned from the query */
for (i=0; i<2; i++) {
printf ("%s", attributes[i].name);
if (attributes[i].status != CFG_ATTR_SUCCESS) {
switch (attributes[i].status){
case CFG_ATTR_EEXISTS:
printf("unknown attribute\n");
break;
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;
}
}
}
In this example, the application requests information
about two attributes, bufcache and max-vnodes. When the
cfg_subsys_query() 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() routine returns CFG_SUCCESS, the status
for each attribute is tested and any errors are reported.
The application displays to the user the value of
attributes that return CFG_ATTR_SUCCESS.
Commands: cfgmgr(8), sysconfig(8)
Routines: cfg_connect(3), cfg_subsys_query_all(3),
libcfg(3)
cfg_subsys_query(3)
[ Back ] |
