 |
Index for
Section 3 |
|
 |
Alphabetical
listing for C |
|
 |
Bottom of
page |
|
cfg_subsys_query(3)
NAME
cfg_subsys_query - determine the value of selected subsystem attributes
SYNOPSIS
#include <cfg.h>
cfg_status_t cfg_subsys_query(
cfg_handle_t *handle,
caddr_t subsys,
cfg_attr_t *attributes,
int nattributes );
LIBRARY
Configuration Management Library (libcfg.a)
PARAMETERS
handle
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.
subsys
Specifies the name of the subsystem for which you are getting attribute
values.
attributes
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.
nattributes
An integer value specifying the number of attributes for which you are
requesting information.
DESCRIPTION
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:
Attribute data type
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.
Attribute operations
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).
Attribute status
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
_____________________________________________________
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.)
RETURN VALUES
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).
EXAMPLES
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.
SEE ALSO
Commands: cfgmgr(8), sysconfig(8)
Routines: cfg_connect(3), cfg_subsys_query_all(3), libcfg(3)
|
Index for
Section 3 |
|
|
Alphabetical
listing for C |
|
 |
Top of
page |
|