 |
Index for
Section 3 |
|
 |
Alphabetical
listing for C |
|
 |
Bottom of
page |
|
cfg_subsys_query_all(3)
NAME
cfg_subsys_query_all - Determine the value of all attributes for a
subsystem
LIBRARY
Configuration Management Library (libcfg.a)
SYNOPSIS
#include <cfg.h>
cfg_status_t cfg_subsys_query_all(
cfg_handle_t *handle,
caddr_t subsys,
cfg_attr_t **attributes,
int *nattributes);
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
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.
nattributes
An integer value specifying the number of attributes for which
information has been returned.
DESCRIPTION
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.
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:
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 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).
Attribute status
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
_________________________________________________________________
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.)
EXAMPLES
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.
RETURN VALUES
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).
RELATED INFORMATION
Commands: cfgmgr(8), sysconfig(8)
Routines: cfg_subsys_query(3), libcfg(3)
|
Index for
Section 3 |
|
|
Alphabetical
listing for C |
|
 |
Top of
page |
|