cfg_subsys_list(3)					     Library Functions Manual						cfg_subsys_list(3)

NAME

       cfg_subsys_list - Determine the names and states of all subsystems registered on the system

LIBRARY

       Configuration Management Library (libcfg.a)

SYNOPSIS

       #include <cfg.h> cfg_status_t cfg_subsys_list(
	       cfg_handle_t *handle,
	       caddr_t **subsys,
	       unsigned int **state,
	       int *nsubsys);

PARAMETERS

       Structure  identifying  the  means  of communication between your application 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.  Returns the names of subsystems
       currently  registered on the system. The system allocates memory for this array, which you should free when the information in the array is
       no longer needed.  Returns an array of bit flags, defined in <sys/sysconfig.h>, representing the state of the subsystems. The system  allo-
       cates  memory  for  this  array, which you should free when the information in the array is no longer needed.  The following flags are cur-
       rently defined: loaded and configured.  Returns an integer designating how many subsystem names and states are being returned.

DESCRIPTION

       Use the cfg_subsys_list() routine to determine the names of subsystems available on the system and the current state of those subsystems.

       The subsys array returns NULL terminated subsystem names of length CFG_SUBSYS_NAME_SZ.  (CFG_SUBSYS_NAME_SZ is defined in the  <sys/syscon-
       fig.h> header file.)

       The  value  returned  in the state parameter is an array containing integer representations of binary values.  The least significant bit in
       each binary value designates whether or not the subsystem is loaded.  If this bit is set, the subsystem is  loaded.   If  the  next  higher
       order bit is set,  the subsystem is configured.

       You  can  determine  the  state	of  a subsystem by using one of the values returned in the state parameter in a bitwise AND operation. The
       <sys/sysconfig.h> header file defines constants for this purpose.  See the EXAMPLES section for more information  about	using  these  con-
       stants.

       The  array of subsystems states and the array of subsystem names are parallel arrays.  In other words, the first element of the state array
       contains the state of the subsystem named in the first element of the subsys array.  The second element of the state array gives the  state
       of the second element in the subsys array, and so on.

EXAMPLES

       The following example illustrates the use of the cfg_subsys_list() library routine:

       cfg_status_t		retval;  cfg_handle_t		  handle;  caddr_t		    *subsys;  unsigned	int	       *state; int
       nsubsys; int			i;

       retval = cfg_subsys_list(&handle, &subsys, &state, &nsubsys);

       if (retval != CFG_SUCCESS)
	  print_error(retval); else {

	    /*	 Walk through the array of subsystem names and the array    */
	    /*	 of subsystem states.  Display each name and state.	    */

	   for (i=0; i<nsubsys; i++){
	    if (state[i] & CFG_STATE_LOADED) {
	       if (state[i] & CFG_STATE_CONFIGURED)
		  printf("Subsystem '%s' is loaded and configured.
",
			  subsys[i]);
	       else
		  printf("Subsystem '%s' is loaded.
", subsys[i]);
	    else
		  printf("Subsystem '%s' is unloaded.
", subsys[i]);
	    }
	   }
	   free(subsys);
	   free(state); }

       In this example, the cfg_subsys_list() routine returns an array of subsystem names and an  array  of  subsystem	states.   The  application
       determines whether the call to the routine was successful.  If the call was successful, the application displays the name and state of each
       subsystem available on the system.

       The system allocates memory in which to return the state and subsys arrays. Once the application is finished  using  the  values  in  those
       arrays, it calls the free() routine to make that memory available for use by other applications.

RETURN VALUES

       Upon  successful  completion, cfg_subsys_list() 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_subsys_state(3), libcfg(3) delim off

																cfg_subsys_list(3)