Manual Page Result
0
Command: cfg_subsys_query | Section: 3 | Source: Digital UNIX | File: cfg_subsys_query.3.gz
cfg_subsys_query(3) Library Functions Manual cfg_subsys_query(3)
NAME
cfg_subsys_query - Determine the value of selected subsystem attributes
LIBRARY
Configuration Management Library (libcfg.a)
SYNOPSIS
#include <cfg.h> cfg_status_t cfg_subsys_query(
cfg_handle_t *handle,
caddr_t subsys,
cfg_attr_t *attributes,
int nattributes);
PARAMETERS
Structure identifying the means of communication between your applica-
tion 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 at-
tributes 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 at-
tribute. For binary data items, the information includes the
size of the attribute's current value. An integer value speci-
fying the number of attributes for which you are requesting in-
formation.
DESCRIPTION
Use the cfg_subsys_query() routine to get information about a list of
subsystem attributes. You can get information about one or more at-
tributes.
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 in-
formation 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 infor-
mation about more than one attribute, an array of structures is re-
turned. For information about this structure, see libcfg(3).
The following list describes the information returned to your applica-
tion 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 at-
tribute in the subsystem code determines what operations you can per-
form 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 con-
figured), and CFG_OP_RECONFIGURE (you can modify the value of the at-
tribute). 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: tab(@);
lfHB lfHB lfCW l. _
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@T{ Subsystem failure (code within the subsystem re-
turned an error) T}
CFG_ATTR_EINDEX@T{ The index for an indexed attribute is out of range
T}
CFG_ATTR_EMEM@T{ Unable to allocate memory to return the attribute
value T}
_ 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.)
EXAMPLES
The following example illustrates the use of the cfg_subsys_query() li-
brary 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, "nmounts"); strcpy (attributes[1].name,
"mountpoint");
/***************************************************/ /* Call the
cfg_subsys_query() routine */
retval = cfg_subsys_query(&handle, "lvm", 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 attrib-
utes, nmounts and mountpoint. When the cfg_subsys_query() routine re-
turns information about those attributes, the application tests the re-
turn status of the routine. The application reports any errors re-
turned. If cfg_subsys_query() routine returns CFG_SUCCESS, the status
for each attribute is tested and any errors are reported. The applica-
tion displays to the user the value of attributes that return
CFG_ATTR_SUCCESS.
RETURN VALUES
Upon successful completion, cfg_subsys_query() returns CFG_SUCCESS.
Other return values indicate that an error has occurred. For informa-
tion about handling return values from routines in the configuration
management library, see libcfg(3).
RELATED INFORMATION
Commands: cfgmgr(8), sysconfig(8)
Routines: cfg_connect(3), cfg_subsys_query_all(3), libcfg(3) delim off
cfg_subsys_query(3)