*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->Tru64 Unix man pages -> libcfg (3)              



NAME    [Toc]    [Back]

       libcfg  -  introduction  to  the  Configuration Management

DESCRIPTION    [Toc]    [Back]

       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

   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

   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)();
                 struct {
                          caddr_t val;
                          ulong   min_size;
                          ulong   max_size;
                          void    (*disposal)();
                          ulong   val_size;
                 struct {
                          ulong   val;
                          ulong   min_val;
                          ulong   max_val;
                      }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

              Data Type Name       Description
              CFG_ATTR_STRTYPE     Null-terminated array of characters
              CFG_ATTR_INTTYPE     32-bit signed number (int)
              CFG_ATTR_UINTTYPE    32-bit  unsigned  number  (unsigned
              CFG_ATTR_LONGTYPE    64-bit signed number (long)
              CFG_ATTR_ULONGTYPE   64-bit  unsigned  number  (unsigned
              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
              CFG_ATTR_EMEM         No   memory   available   for   the
              CFG_ATTR_EOP          Attribute   does  not  support  the
                                    requested operation
              CFG_ATTR_ESMALL       Attribute  value  or  size  is  too
              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
              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

       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

       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
                    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:
                    case CFG_FRAME_EEXISTS:
                      printf("framework   error:   subsystem  not
                   case CFG_FRAM_EATTRLIST:
                     printf("framework   error:   bad   attribute
                     printf("framework error: unknown %d\n" \

         /*     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"
                        printf("subsystem error %d: 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.  To see an example routine  for  displaying
       errors,  refer  to  the  /usr/examples/cfgmgr/sample_app.c

       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.

SEE ALSO    [Toc]    [Back]

       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

[ Back ]
 Similar pages
Name OS Title
OLAR_intro Tru64 Introduction to Online Addition and Removal (OLAR) Management
olar_intro Tru64 Introduction to Online Addition and Removal (OLAR) Management
cfgmgr Tru64 Configuration management server
atmsig Tru64 Allows the configuration and management of the UNI signaling module
cvconfig IRIX WorkShop Configuration Management Specification
usermgmt.conf OpenBSD user management tools configuration file
cfgmgr.auth Tru64 Configuration management server authorization database
gr_sn IRIX NUMA Memory Management Configuration Tool
acpi FreeBSD Advanced Configuration and Power Management support
sn IRIX NUMA Memory Management Configuration Tool
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service