NAME

libcfg − 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.  Using libcfg routines, applications communicate with the configuration management server (cfgmgr) and the kernel. The configuration management server answers requests for the following actions:

       •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. 

The kernel answers requests for the address of kernel parameters. 

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 the 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: Tutorial. 

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 mangement 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())

       •Determine the address of symbols in the currently running kernel (knlist())

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 table.  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 table carries information about one subsystem attribute:

typedef struct cfg_attr {
        char         name[CFG_ATTR_NAME_SZ];
        uint         type;
        uint         status;
        uint         operation;
        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 {
                   caddr_t val;
                   ulong   min_len;
                   ulong   max_len;
                 }num;
               }attr;
}cfg_attr_t;

The following list describes the elements of the cfg_attr_t datatype:

       •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:

       •The status field contains one of the predefined status codes listed in the following table:

       •The operation field contains one of the operation codes listed in the following table:

       •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 string data.  The minimum and maximum values are the minimum and maximum lengths of the string.  The disposal routine is a routine you write to free the kernel memory used by your data once you are finished with that memory.  For attributes with the CFG_ATTR_BINTYPE data type, the val field contains a binary value. The minimum and maximum values are the minimum number of bytes you can modify and the maximum number of bytes you can modify.  The disposal routine is a routine you write to free the kernel memory used by your data once you are finished with that memory. The val_size variable contains the current size of the binary data.  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_FRAME() and CFG_STATUS_SUBSYS() macros to extract the subsystem status and system status from the return value.  All system errors are defined in the <sys/sysconfig.h> header file. 

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>
void
print_error(
             cfg_status_t  status)
{
             uint          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\n")
              break;
            }
  /∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗/
  /∗    Report the status of the kernel subsystem                 ∗/
  /∗                                                              ∗/
            if (subsys_status != ESUCCESS) {
              if (subsys_status > 0 && subsys_status < sys_nerr)
                 printf("subsystem error: %s\n"
                        ,sys_errlist[subsys_status]);
              else
                 printf("subsystem error: unknown status\n");
            }
}

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. 

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. 

RELATED INFORMATION

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: Tutorial