libcfg - introduction to the Configuration Management
Library
The configuration management library (libcfg.a) provides
routines that allow applications to manage static and
dynamic kernel subsystems. Applications use the libcfg
routines to communicate with the configuration management
server (cfgmgr) and kernel subsystems. The configuration
management library provides the following services: Adding
and removing configurable subsystems from the kernel Displaying
or modifying the value of kernel subsystem parameters
Displaying information about the available subsystems
and their states Accessing system-specific entries in the
kernel, such as performing subsystem-defined operations
For example, you might use the library to create an application
that manages a loadable device driver. Another
example that uses the routines in libcfg is the sysconfig
command. This command calls libcfg routines to allow system
administrators to manage dynamically configurable kernel
subsystems. (For more information, see sysconfig(8).)
This reference page introduces the library and provides
information about the following topics: The purpose of the
routines in the library The cfg_attr_t data type, which
you need to understand in order to use the library How to
handle error codes returned from the library
For information about creating configurable kernel subsystems,
see the Programmer's Guide and Writing Device
Drivers.
Routines in the Configuration Management Library [Toc] [Back]
The library includes routines that allow you to perform
the following tasks on local and remote systems: Connect
to the configuration management server on a remote host
(cfg_connect()) Determine the state of a subsystem
(cfg_subsys_state()) Obtain a list of subsystems and their
states (cfg_subsys_list()) Configure the specified subsystem
for use (cfg_subsys_config()) Determine the value of
all attributes for a specified subsystem (cfg_subsys_query_all())
Determine the value of a specified subsystem
attribute or list of attributes (cfg_subsys_query())
Modify the value of a specified subsystem
attribute or list of attributes (cfg_subsys_reconfig())
Determine the /etc/sysconfigtab value for all attributes
of a subsystem (cfg_subsys_defaults_all()) Determine the
/etc/sysconfigtab value for selected attributes of a subsystem
(cfg_subsys_defaults()) Perform an operation that
is specific to and defined by the subsystem (cfg_subsys_op())
Unconfigure the specified subsystem (cfg_subsys_unconfig())
Remove the connection to the remote host
(cfg_disconnect())
Sending and Receiving Subsystem Attribute Data [Toc] [Back]
When you call one of the routines that manipulate subsystem
attributes, you communicate with the system using an
attribute list. The <sys/sysconfig.h> header file declares
the cfg_attr_t data type specifically for passing information
about attributes. As shown in the example that follows,
each element of this list carries information about
one subsystem attribute:
typedef struct cfg_attr {
char name[CFG_ATTR_NAME_SZ];
uchar type;
uchar operation;
uint status;
long index;
union {
struct {
caddr_t val;
ulong min_len;
ulong max_len;
void (*disposal)();
}str;
struct {
caddr_t val;
ulong min_size;
ulong max_size;
void (*disposal)();
ulong val_size;
}bin;
struct {
ulong val;
ulong min_val;
ulong max_val;
}num;
}attr; }cfg_attr_t;
The following list describes the elements of the
cfg_attr_t data type: The name field specifies the name of
the attribute. The name is defined by the subsystem and is
a string of alphabetic characters, at least two characters
long and no longer than the value stored in the
CFG_ATTR_NAME_SZ constant. This constant is defined in
the <sys/sysconfig.h> header file. The type field specifies
the data type of the attribute, as shown in the following
table:
---------------------------------------------------------
Data Type Name Description
---------------------------------------------------------
CFG_ATTR_STRTYPE Null-terminated array of characters
(char*)
CFG_ATTR_INTTYPE 32-bit signed number (int)
CFG_ATTR_UINTTYPE 32-bit unsigned number (unsigned
int)
CFG_ATTR_LONGTYPE 64-bit signed number (long)
CFG_ATTR_ULONGTYPE 64-bit unsigned number (unsigned
long)
CFG_ATTR_BINTYPE Array of bytes
---------------------------------------------------------
The status field contains one of the predefined
status codes listed in the following table:
----------------------------------------------------------
Status Code Meaning
----------------------------------------------------------
CFG_ATTR_EEXISTS Attribute does not exist
CFG_ATTR_EINDEX Invalid attribute index
CFG_ATTR_ELARGE Attribute value or size is too
large
CFG_ATTR_EMEM No memory available for the
attribute
CFG_ATTR_EOP Attribute does not support the
requested operation
CFG_ATTR_ESMALL Attribute value or size is too
small
CFG_ATTR_ESUBSYS Subsystem failure (Code within the
subsystem returned an error)
CFG_ATTR_ETYPE Invalid attribute type or mismatched
attribute type
CFG_ATTR_SUCCESS Successful operation
CFG_ATTR_ENOTNUMBER Attribute value cannot be converted
to a number
----------------------------------------------------------
The operation field contains one of the operation
codes listed in the following table:
-----------------------------------------------------------
Request Code Meaning
-----------------------------------------------------------
CFG_OP_QUERY The application requests a query of
the current value of the attribute
CFG_OP_RECONFIGURE The application requests a change to
the value of the current value of the
attribute
-----------------------------------------------------------
The index field is an index into a structured
attribute. The attr union contains the value of
the attribute and its maximum and minimum values.
For attributes with the CFG_ATTR_STRTYPE data type,
the val variable contains the pointer to the string
data. The minimum and maximum values are the minimum
and maximum lengths allowed for the string.
The disposal variable is used internally by subsystems.
For attributes with the CFG_ATTR_BINTYPE data
type, the val field contains a pointer to the
binary value. The minimum and maximum values are
the minimum number of bytes allowed for the binary
data. The disposal variable is used internally by
subsystems. For numerical data types, the val variable
contains an integer value. The minimum and
maximum values specify the range of values that is
allowed for the attribute.
Handling Error Return Values [Toc] [Back]
All configuration management library routines return a
status of type cfg_status_t. To determine whether a call
was successful, you compare this status to the CFG_SUCCESS
constant.
If a routine returns an error, the error might have
occurred during the execution of kernel subsystem code,
configuration management code, or both. You can use the
CFG_STATUS_SUBSYS() and CFG_STATUS_FRAME() macros to
extract the subsystem status and framework status, respectively,
from the return value. All framework errors are
defined in the <sys/sysconfig.h> header file as
CFG_FRAME_???
The following example shows an error handler that determines
and reports errors that occur during the execution
of a configuration management library routine:
#include <errno.h> #include <sys/sysconfig.h> void
print_error(
cfg_status_t status)
{
int subsys_status=CFG_STATUS_SUBSYS(status);
/*****************************************************************/
/* Report the status of configuration management software
*/
/*
*/
switch (CFG_STATUS_FRAME(status)){
case CFG_FRAME_SUCCESS:
break;
case CFG_FRAME_EEXISTS:
printf("framework error: subsystem not
loaded/found\n");
break
.
.
.
case CFG_FRAM_EATTRLIST:
printf("framework error: bad attribute
list\n");
break;
default:
printf("framework error: unknown %d\n" \
CFG_STATUS_FRAME(status))
break;
}
/****************************************************************/
/* Report the status of the kernel subsystem
*/
/*
*/
if (subsys_status != ESUCCESS) {
if (subsys_status > 0 && subsys_status < \
sys_nerr && sys_errlist [subsys_status])
printf("subsystem error: %s\n"
,sys_errlist[subsys_status]);
else
printf("subsystem error %d: unknown status\n"
\
subsys_status);
} }
In this example, the configuration manager status is supplied
as the controlling expression for the switch statement.
The various status constants shown are defined in
the <sys/sysconfig.h> file. The example omits some constants,
but you should include them all in your error handling
routine. To see an example routine for displaying
errors, refer to the /usr/examples/cfgmgr/sample_app.c
file.
The subsystem status is included in an if statement and
the body of the if statement is executed for error
returns. If the subsystem status is equal to a system
status defined in <sys/errno.h>, the message associated
with that status is displayed. Otherwise, the unknown
status message is displayed. If the subsystem defines its
own error codes, those error codes should be included.
Note that the absolute value of a subsystem error must be
less than 2^15-1 or 32767.
Commands: cfgmgr(8), sysconfig(8)
Routines: cfg_connect(3), cfg_disconnect(3), cfg_subsys_config(3), cfg_subsys_defaults(3), cfg_subsys_defaults_all(3), cfg_subsys_list(3), cfg_subsys_op(3),
cfg_subsys_query(3), cfg_subsys_query_all(3), cfg_subsys_reconfig(3), cfg_subsys_state(3), cfg_subsys_unconfig(3), knlist(3)
Files: sysconfigtab(4)
Programmer's Guide
Writing Device Drivers
libcfg(3)
[ Back ] |
