Index for Section 3

Alphabetical listing for C

Bottom of page

cfg_subsys_query(3)
NAME
  cfg_subsys_query - Determine the value of selected subsystem attributes

LIBRARY
  Configuration Management Library (libcfg.a)

SYNOPSIS
  #include <cfg.h>
  cfg_status_t cfg_subsys_query(
	  cfg_handle_t *handle,
	  caddr_t subsys,
	  cfg_attr_t *attributes,
	  int nattributes);

PARAMETERS
  handle    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.

  subsys    Specifies the name of the subsystem for which you are getting
	    attribute values.

  attributes
	    On input, names the attributes for which you are requesting a
	    value.

	    On return, contains information about the named attributes.	 The
	    information includes the data type of the attribute, the list of
	    operations supported by that attribute, the attribute-specific
	    status of the query operation, the minimum and maximum allowed
	    values for the attribute, and the current value of the attribute.
	    For binary data items, the information includes the size of the
	    attribute's current value.

  nattributes
	    An integer value specifying the number of attributes for which
	    you are requesting information.

DESCRIPTION
  Use the cfg_subsys_query() routine to get information about a list of
  subsystem attributes.	 You can get information about one or more
  attributes.

  When your application calls the cfg_subsys_query() routine, it passes the
  subsystem name and a list of attribute names to the system.  The system
  reads this information and finds and collects the information about the
  named attributes. The system then returns the attribute information to your
  application.

  The information returned from the cfg_subsys_query() routine is passed in a
  structure of type cfg_attr_t.	 If your application requests information
  about more than one attribute, an array of structures is returned. For
  information about this structure, see libcfg(3).

  The following list describes the information returned to your application
  when it calls the cfg_subsys_query() routine:

  Attribute data type
	    Attributes can be integer, string, or binary data. As defined in
	    <sys/sysconfig.h>, the integer data types can be CFG_ATTR_INTTYPE
	    (int), CFG_ATTR_UINTTYPE (uint), CFG_ATTR_LONGTYPE (long), or
	    CFG_ATTR_ULONGTYPE (ulong).	 The string data type is a character
	    string type named CFG_ATTR_STRTYPE and the binary data type is
	    CFG_ATTR_BINTYPE.

  Attribute operations
	    The definition of each attribute in the subsystem code determines
	    what operations you can perform on the attribute.  The possible
	    operation code are CFG_OP_QUERY (you can request information
	    about the attribute), CFG_OP_CONFIGURE (you can set the attribute
	    value when the subsystem is initially configured), and
	    CFG_OP_RECONFIGURE (you can modify the value of the attribute).

  Attribute status
	    During a query request, the system assigns a status to each
	    attribute. The following table describes the status values that
	    your application might receive from the cfg_subsys_query()
	    routine:
	    _________________________________________________________________
	    Status Code	       Meaning
	    _________________________________________________________________
	    CFG_ATTR_SUCCESS   Successful operation
	    CFG_ATTR_EEXISTS   No attribute by that name exists
	    CFG_ATTR_EOP       Attribute does not support the query operation
	    CFG_ATTR_ESUBSYS

			       Subsystem failure (code within the subsystem
			       returned an error)
	    CFG_ATTR_EINDEX

			       The index for an indexed attribute is out of
			       range
	    CFG_ATTR_EMEM

			       Unable to allocate memory to return the
			       attribute value
	    _________________________________________________________________

  Attribute value
	    The value of each attribute is returned in a structure.  In
	    addition to the attribute value, this structure returns the
	    minimum and maximum value for the attribute, the disposal
	    routine, if any, to be called once the attribute value is
	    returned, and for binary attributes, the length of the current
	    value of the attribute.  (The disposal routine is used to free
	    kernel memory occupied by string and binary data.)

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

       cfg_attr_t	       attributes[2];
       cfg_status_t	       retval;
       cfg_handle_t	       handle;
       int		       i;

       /*****************************************************/
       /*  Initialize attribute names for the query	    */

       strcpy (attributes[0].name, "bufcache");
       strcpy (attributes[1].name, "max-vnodes");

       /***************************************************/
       /*   Call the cfg_subsys_query() routine		    */

       retval = cfg_subsys_query(&handle, "vfs", attributes, 2);

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

       else {
	    /*	Use data returned from the query	  */

	    for (i=0; i<2; i++) {
		printf ("%s", attributes[i].name);
		if (attributes[i].status != CFG_ATTR_SUCCESS) {
		    switch (attributes[i].status){
		    case CFG_ATTR_EEXISTS:
		      printf("unknown attribute\n");
		      break;
		    case CFG_ATTR_EOP:
		      printf("attribute does not allow this operation\n");
		      break;
		    .
		    .
		    .
		    default:
		      printf("unknown error\n");
		      break;
		    }
		    continue;
		}


	  /*	 Display attribute value to application user   */

		switch (attributes[i].type){
		case CFG_ATTR_INTTYPE:
		  printf ("%d\n", (int) attributes[i].attr.num.val);
		  break;
		.
		.
		.
		case CFG_ATTR_STRTYPE:
		  printf ("%s\n", (int) attributes[i].attr.str.val);
		  free(attributes[i].attr.str.val);
		  break;

		case CFG_ATTR_BINTYPE:
		  printf ("%d bytes of binary data received\n",
			   (int) attributes[i].attr.bin.val_size);
		  free(attributes[i].attr.str.val);
		  break;
		}
	      }
	   }


  In this example, the application requests information about two attributes,
  bufcache and max-vnodes.  When the cfg_subsys_query() routine returns
  information about those attributes, the application tests the return status
  of the routine.  The application reports any errors returned.	 If
  cfg_subsys_query() routine returns CFG_SUCCESS, the status for each
  attribute is tested and any errors are reported.  The application displays
  to the user the value of attributes that return CFG_ATTR_SUCCESS.

RETURN VALUES
  Upon successful completion, cfg_subsys_query() returns CFG_SUCCESS. Other
  return values indicate that an error has occurred.  For information about
  handling return values from routines in the configuration management
  library, see libcfg(3).

RELATED INFORMATION
  Commands: cfgmgr(8), sysconfig(8)

  Routines: cfg_connect(3), cfg_subsys_query_all(3), libcfg(3)

Index for Section 3

Alphabetical listing for C

Top of page