libcfg(3)libcfg(3)NAMElibcfg - introduction to the Configuration Management Library
DESCRIPTION
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 configura‐
tion management server (cfgmgr) and kernel subsystems. The configura‐
tion management library provides the following services: Adding and
removing configurable subsystems from the kernel Displaying or modify‐
ing the value of kernel subsystem parameters Displaying information
about the available subsystems and their states Accessing system-spe‐
cific entries in the kernel, such as performing subsystem-defined oper‐
ations
For example, you might use the library to create an application that
manages a loadable device driver. Another example that uses the rou‐
tines in libcfg is the sysconfig command. This command calls libcfg
routines to allow system administrators to manage dynamically config‐
urable 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
The library includes routines that allow you to perform the following
tasks on local and remote systems: Connect to the configuration manage‐
ment 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 spec‐
ified subsystem (cfg_subsys_query_all()) Determine the value of a spec‐
ified 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 sub‐
system (cfg_subsys_defaults()) Perform an operation that is specific
to and defined by the subsystem (cfg_subsys_op()) Unconfigure the spec‐
ified subsystem (cfg_subsys_unconfig()) Remove the connection to the
remote host (cfg_disconnect())
Sending and Receiving Subsystem Attribute Data
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 specif‐
ically for passing information about attributes. As shown in the exam‐
ple 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 mis‐
matched 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 maxi‐
mum 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 vari‐
able 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
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, respec‐
tively, 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 man‐
agement 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 associ‐
ated with that status is displayed. Otherwise, the unknown status mes‐
sage is displayed. If the subsystem defines its own error codes, those
error codes should be included. Note that the absolute value of a sub‐
system error must be less than 2^15-1 or 32767.
SEE ALSO
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)
