config_admin man page on Solaris

Man page or keyword search:  
man Server   20652 pages
apropos Keyword Search (all sections)
Output format
Solaris logo
[printable version]

config_admin(3CFConfiguration Administration Library Funcconfig_admin(3CFGADM)

NAME
       config_admin,  config_change_state,  config_private_func,  config_test,
       config_stat,  config_list,  config_list_ext,   config_ap_id_cmp,	  con‐
       fig_unload_libs,	 config_strerror - configuration administration inter‐
       face

SYNOPSIS
       cc [ flag... ] file... -lcfgadm [ library... ]
       #include <config_admin.h>
       #include <sys/param.h>

       cfga_err_t   config_change_state(cfga_cmd_t    state_change_cmd,	   int
       num_ap_ids, char * const *ap_ids, const char *options, struct cfga_con‐
       firm *confp, struct  cfga_msg  *msgp,  char  **errstring,  cfga_flags_t
       flags);

       cfga_err_t  config_private_func(const  char  *function, int num_ap_ids,
       char * const *ap_ids, const char *options, struct cfga_confirm  *confp,
       struct cfga_msg *msgp, char **errstring, cfga_flags_t flags);

       cfga_err_t config_test(int num_ap_ids, char * const *ap_ids, const char
       *options, struct cfga_msg *msgp, char **errstring, cfga_flags_t flags);

       cfga_err_t config_list_ext(int num_ap_ids, char * const *ap_ids, struct
       cfga_list_data  **ap_id_list,  int  *nlist,  const char *options, const
       char *listops, char **errstring, cfga_flags_t flags);

       int  config_ap_id_cmp(const  cfga_ap_id_t  ap_id1,  const  cfga_ap_id_t
       ap_id2);

       void config_unload_libs(void);

       const char *config_strerror(cfga_err_t cfgerrnum);

   Deprecated Interfaces
       The following interfaces have been deprecated and their use is strongly
       discouraged:

       cfga_err_t config_stat(int num_ap_ids, char  *  const  *ap_ids,	struct
       cfga_stat_data *buf, const char *options, char **errstring);

       cfga_err_t  config_list(struct cfga_stat_data **ap_id_list, int *nlist,
       const char *options, char **errstring);

HARDWARE DEPENDENT LIBRARY SYNOPSIS
       The  config_admin library is a  generic	interface  that	 is  used  for
       dynamic	configuration,	(DR).  Each piece of hardware that supports DR
       must supply a hardware-specific	plugin library that contains the entry
       points  listed  in this subsection. The generic library will locate and
       link to the appropriate library to effect  DR operations.   The	inter‐
       faces  specified in   this subsection are really "hidden" from users of
       the generic libraries. It is, however, necessary that  writers  of  the
       hardware-specific plug in libraries know what these interfaces are.

       cfga_err_t  cfga_change_state(cfga_cmd_t	 state_change_cmd,  const char
       *ap_id,	const  char  *options,	struct	cfga_confirm  *confp,	struct
       cfga_msg *msgp, char **errstring, cfga_flags_t flags);

       cfga_err_t  cfga_private_func(const  char *function, const char *ap_id,
       const char *options, struct cfga_confirm *confp, struct cfga_msg *msgp,
       char **errstring, cfga_flags_t flags);

       cfga_err_t  cfga_test(const  char  *ap_id,  const char *options, struct
       cfga_msg *msgp, char **errstring, cfga_flags_t flags);

       cfga_err_t  cfga_list_ext(const	char  *ap_id,  struct	cfga_list_data
       **ap_id_list,  int  *nlist,  const char *options, const char *listopts,
       char **errstring, cfga_flags_t flags);

       cfga_err_t  cfga_help(struct  cfga_msg  *msgp,  const  char   *options,
       cfga_flags_t flags);

       int   cfga_ap_id_cmp(const   cfga_ap_id_t  ap_id1,  const  cfga_ap_id_t
       ap_id2);

   Deprecated Interfaces
       The following interfaces have been deprecated and their use is strongly
       discouraged:

       cfga_err_t  cfga_stat(const  char  *ap_id,  struct cfga_stat_data *buf,
       const char *options, char **errstring);

       cfga_err_t   cfga_list(const   char   *ap_id,   struct	cfga_stat_data
       **ap_id_list, int *nlist, const char *options, char **errstring);

DESCRIPTION
       The  config_*()	functions  provide a hardware independent interface to
       hardware-specific system configuration administration  functions.   The
       cfga_*() functions are provided by hardware-specific libraries that are
       dynamically loaded to handle configuration administration functions  in
       a hardware-specific manner.

       The libcfgadm library is used to provide the services of the cfgadm(1M)
       command. The hardware-specific  libraries  are  located	in  /usr/plat‐
       form/${machine}/lib/cfgadm,    /usr/platform/${arch}/lib/cfgadm,	   and
       /usr/lib/cfgadm. The hardware-specific library names are	 derived  from
       the  driver name or from class names in device tree nodes that identify
       attachment points.

       The config_change_state() function performs operations that change  the
       state of the system configuration. The state_change_cmd argument can be
       one of the following: CFGA_CMD_INSERT,  CFGA_CMD_REMOVE,	 CFGA_CMD_DIS‐
       CONNECT, CFGA_CMD_CONNECT, CFGA_CMD_CONFIGURE, or CFGA_CMD_UNCONFIGURE.
       The state_change_cmd CFGA_CMD_INSERT is	used  to  prepare  for	manual
       insertion  or  to activate automatic hardware insertion of an occupant.
       The state_change_cmd  CFGA_CMD_REMOVE is used  to  prepare  for	manual
       removal	or  activate  automatic	 hardware  removal of an occupant. The
       state_change_cmd CFGA_CMD_DISCONNECT is used to disable normal communi‐
       cation  to  or  from  an occupant in a receptacle. The state_change_cmd
       CFGA_CMD_CONNECT is used to enable communication to or from an occupant
       in  a  receptacle.  The	state_change_cmd CFGA_CMD_CONFIGURE is used to
       bring the hardware resources contained on, or attached to, an  occupant
       into  the  realm	 of  Solaris,  allowing use of the occupant's hardware
       resources by the system. The state_change_cmd  CFGA_CMD_UNCONFIGURE  is
       used  to remove the hardware resources contained on, or attached to, an
       occupant from the realm of Solaris,  disallowing	 further  use  of  the
       occupant's hardware resources by the system.

       The  flags  argument  may  contain  one	or  both of the defined flags,
       CFGA_FLAG_FORCE and CFGA_FLAG_VERBOSE. If the CFGA_FLAG_FORCE  flag  is
       asserted	 certain  safety  checks will be overridden. For example, this
       may not allow an occupant in the failed condition to be configured, but
       might  allow  an	 occupant  in  the failing condition to be configured.
       Acceptance of a force is hardware dependent. If	the  CFGA_FLAG_VERBOSE
       flag  is	 asserted  hardware-specific details relating to the operation
       are output utilizing the cfga_msg mechanism.

       The config_private_func() function  invokes  private  hardware-specific
       functions.

       The config_test() function is used to initiate testing of the specified
       attachment point.

       The num_ap_ids argument specifies the number of ap_ids  in  the	ap_ids
       array. The ap_ids argument points to an array of ap_ids.

       The ap_id argument points to a single ap_id.

       The  function  and  options strings conform to the getsubopt(3C) syntax
       convention and are used to supply hardware-specific function or	option
       information.  No	 generic hardware-independent functions or options are
       defined.

       The cfga_confirm structure referenced by	 confp	provides  a  call-back
       interface  to  get permission to proceed should the requested operation
       require, for example, a noticeable service interruption. The  cfga_con‐
       firm structure includes the following members:

       int  (*confirm)(void *appdata_ptr, const char *message);
       void *appdata_ptr;

       The  confirm()  function	 is  called  with  two	arguments: the generic
       pointer appdata_ptr and the message detailing what  requires  confirma‐
       tion.  The generic pointer appdata_ptr is set to the value passed in in
       the cfga_confirm structure member appdata_ptr and  can  be  used	 in  a
       graphical  user	interface  to  relate the confirm function call to the
       config_*() call.	 The confirm() function should return 1 to  allow  the
       operation to proceed and 0 otherwise.

       The  cfga_msg  structure referenced by msgp provides a call-back inter‐
       face to output messages from a hardware-specific library.  In the pres‐
       ence  of	 the  CFGA_FLAG_VERBOSE	 flag,	these messages can be informa‐
       tional; otherwise they are restricted to error messages.	 The  cfga_msg
       structure includes the following members:

       int  (*message_routine)(void *appdata_ptr, const char *message);
       void *appdata_ptr;

       The  message_routine()  function	 is  called  with  two	arguments: the
       generic pointer appdata_ptr and the message.  The generic pointer  app‐
       data_ptr	 is  set  to the value passed in in the cfga_confirm structure
       member appdata_ptr and can be used in a	graphical  user	 interface  to
       relate  the message_routine() function call to the config_*() call. The
       messages must be in the native language specified  by  the  LC_MESSAGES
       locale category; see setlocale(3C).

       For  some  generic  errors  a  hardware-specific	 error	message can be
       returned. The storage for the error message string, including the  ter‐
       minating	 null  character, is allocated by the config_* functions using
       malloc(3C) and a pointer to this storage returned through errstring. If
       errstring  is  NULL  no error message will be generated or returned. If
       errstring is not NULL and no error message is  generated,  the  pointer
       referenced  by  errstring will be set to NULL. It is the responsibility
       of the function calling config_*() to deallocate the  returned  storage
       using free(3C). The error messages must be in the native language spec‐
       ified by the LC_MESSAGES locale category; see setlocale(3C).

       The config_list_ext() function provides	the  listing  interface.  When
       supplied	 with  a  list	of  ap_ids through the first two arguments, it
       returns an array of cfga_list_data_t  structures	 for  each  attachment
       point  specified.  If  the  first  two arguments are 0 and NULL respec‐
       tively, then all attachment points in the device tree will  be  listed.
       Additionally,  dynamic expansion of an attachment point to list dynamic
       attachment   points   may   also	  be   requested   by	passing	   the
       CFGA_FLAG_LIST_ALL  flag	 through  the  flags argument. Storage for the
       returned array of stat structures is allocated by the config_list_ext()
       function	 using malloc(3C). This storage must be freed by the caller of
       config_list_ext() by using free(3C).

       The cfga_list_data structure includes the following members:

       cfga_log_ext_t	  ap_log_id;	    /* Attachment point logical id */
       cfga_phys_ext_t	  ap_phys_id;	    /* Attachment point physical id */
       cfga_class_t	  ap_class;	    /* Attachment point class */
       cfga_stat_t	  ap_r_state;	    /* Receptacle state */
       cfga_stat_t	  ap_o_state;	    /* Occupant state */
       cfga_cond_t	  ap_cond;	    /* Attachment point condition */
       cfga_busy_t	  ap_busy;	    /* Busy indicator */
       time_t		  ap_status_time;   /* Attachment point last change*/
       cfga_info_t	  ap_info;	    /* Miscellaneous information */
       cfga_type_t	  ap_type;	    /* Occupant type */

       The types are defined as follows:

       typedef char cfga_log_ext_t[CFGA_LOG_EXT_LEN];
       typedef char cfga_phys_ext_t[CFGA_PHYS_EXT_LEN];
       typedef char cfga_class_t[CFGA_CLASS_LEN];
       typedef char cfga_info_t[CFGA_INFO_LEN];
       typedef char cfga_type_t[CFGA_TYPE_LEN];
       typedef enum cfga_cond_t;
       typedef enum cfga_stat_t;
       typedef int  cfga_busy_t;
       typedef int cfga_flags_t;

       The listopts argument to config_list_ext() conforms to  the   getsubopt
       (3C)  syntax  and  is used to pass listing sub-options. Currently, only
       the  sub-option	class=class_name  is  supported.  This	 list	option
       restricts the listing  to attachment points of class class_name.

       The  listopts  argument to cfga_list_ext() is reserved  for future use.
       Hardware-specific  libraries should ignore this argument if it is NULL.
       If  listopts  is not NULL and is not supported by the hardware-specific
       library, an appropriate error code should be returned.

       The ap_log_id and the ap_phys_id	 members  give	the  hardware-specific
       logical and physical names of the attachment point. The ap_busy memberd
       indicates activity is present that may result in changes	 to  state  or
       condition. The ap_status_time  member provides the time at which either
       the ap_r_state, ap_o_state, or ap_cond field of	the  attachment	 point
       last changed. The ap_info member is available for the hardware-specific
       code to provide additional information about the attachment point.  The
       ap_class	 member	 contains  the	attachment point class (if any) for an
       attachment point. The  ap_class member is  filled  in  by  the  generic
       library.	 If  the ap_log_id and ap_phys_id members are not filled in by
       the hardware-specific library, the generic library will fill  in	 these
       members using a generic format. The remaining members are the responsi‐
       bility of the corresponding hardware-tospecific library.

       All string members in the cfga_list_data structure are null-terminated.

       The config_stat(), config_list(), cfga_stat(),  and  cfga_list()	 func‐
       tions  and  the cfga_stat_data data structure are deprecated interfaces
       and are provided solely	for  backward	compatibility.	Use  of	 these
       interfaces is strongly discouraged.

       The  config_ap_id_cmp function performs a hardware dependent comparison
       on two  ap_ids, returning an equal to, less than or greater than	 indi‐
       cation  in  the	manner	of  strcmp(3C).	 Each  argument	 is  either  a
       cfga_ap_id_t or can be a null-terminated string. This function  can  be
       used  when sorting lists of ap_ids, for example with qsort(3C), or when
       selecting entries from the result of a config_list function call.

       The config_unload_libs function unlinks all previously loaded hardware-
       specific libraries.

       The  config_strerror  function can be used to map an error return value
       to an error message string. See	RETURN	VALUES.	 The  returned	string
       should not be overwritten. config_strerror returns NULL if cfgerrnum is
       out-of-range.

       The cfga_help function can be used  request  that  a  hardware-specific
       library output it's localized help message.

RETURN VALUES
       The  config_*()	and  cfga_*()  functions  return the following values.
       Additional error information may be returned through errstring  if  the
       return code is not CFGA_OK. See	DESCRIPTION for details.

       CFGA_BUSY		       The command was not completed due to an
				       element	of  the	 system	 configuration
				       administration system being busy.

       CFGA_ATTR_INVAL		       No attachment points with the specified
				       attributes exists

       CFGA_ERROR		       An error occurred during the processing
				       of  the requested operation. This error
				       code includes validation of the command
				       arguments   by	the  hardware-specific
				       code.

       CFGA_INSUFFICIENT_CONDITION     Operation  failed  due  to   attachment
				       point condition.

       CFGA_INVAL		       The system configuration administration
				       operation requested is not supported on
				       the specified attachment point.

       CFGA_LIB_ERROR		       A  procedural  error  occurred  in  the
				       library, including  failure  to	obtain
				       process	resources  such	 as memory and
				       file descriptors.

       CFGA_NACK		       The command was not completed due to  a
				       negative	  acknowledgement   from   the
				       confp->confirm function.

       CFGA_NO_LIB		       A hardware-specific library  could  not
				       be located using the supplied ap_id.

       CFGA_NOTSUPP		       System  configuration administration is
				       not supported on the specified  attach‐
				       ment point.

       CFGA_OK			       The command completed as requested.

       CFGA_OPNOTSUPP		       System	configuration	administration
				       operation  is  not  supported  on  this
				       attachment point.

       CFGA_PRIV		       The  caller  does not have the required
				       process	privileges.  For  example,  if
				       configuration  administration  is  per‐
				       formed through  a  device  driver,  the
				       permissions on the device node would be
				       used to control access.

       CFGA_SYSTEM_BUSY		       The command required a  service	inter‐
				       ruption	and was not completed due to a
				       part of the system that	could  not  be
				       quiesced.

ERRORS
       Many  of the errors returned by the system configuration administration
       functions are hardware-specific. The strings returned in errstring  may
       include the following:

       attachment point ap_id not known

	   The attachment point detailed in the error message does not exist.

       unknown hardware option option for operation

	   An unknown option was encountered in the options string.

       hardware option option requires a value

	   An  option  in  the	options	 string	 should	 have been of the form
	   option=value.

       listing option list_option requires a value

	   An option in the listopts string should  have   been	 of  the  form
	   option=value.

       hardware option option does not require a value

	   An option in the options string should have been a simple option.

       attachment point ap_id is not configured

	   A  config_change_state command to  CFGA_CMD_UNCONFIGURE an occupant
	   was made to an attachment point  whose  occupant  was  not  in  the
	   CFGA_STAT_CONFIGURED state.

       attachment point ap_id is not unconfigured

	   A  config_change_state  command  requiring an unconfigured occupant
	   was made to an attachment point  whose  occupant  was  not  in  the
	   CFGA_STAT_UNCONFIGURED state.

       attachment point ap_id condition not satisfactory

	   A  config_change_state  command  was	 made  to  an attachment point
	   whose condition prevented the operation.

       attachment point ap_id in condition condition cannot be used

	   A  config_change_state operation with force indicated was  directed
	   to an attachment point whose condition fails the hardware dependent
	   test.

ATTRIBUTES
       See  attributes(5) for descriptions of the following attributes:

       ┌─────────────────────────────┬─────────────────────────────┐
       │      ATTRIBUTE TYPE	     │	    ATTRIBUTE VALUE	   │
       ├─────────────────────────────┼─────────────────────────────┤
       │Availability		     │SUNWcsu, SUNWkvm		   │
       ├─────────────────────────────┼─────────────────────────────┤
       │MT-Level		     │Safe			   │
       └─────────────────────────────┴─────────────────────────────┘

SEE ALSO
       cfgadm(1M),  devinfo(1M),  dlopen(3C),  dlsym(3C),  free(3C),   getsub‐
       opt(3C),	  malloc(3C),  qsort(3C),  setlocale(3C),  strcmp(3C),	libcf‐
       gadm(3LIB), attributes(5)

NOTES
       Applications using this library should be  aware	 that  the  underlying
       implementation  may use system services which alter the contents of the
       external variable errno and may use file descriptor resources.

       The following code shows the intended error processing when  config_*()
       returns a value other than CFGA_OK:

       void
       emit_error(cfga_err_t cfgerrnum, char *estrp)
       {
	   const char *ep;
	   ep = config_strerror(cfgerrnum);
	   if (ep == NULL)
	       ep = gettext("configuration administration unknown error");
	   if (estrp != NULL && *estrp != '\0') {
	       (void) fprintf(stderr, "%s: %s\n", ep, estrp);
	   } else {
	       (void) fprintf(stderr, "%s\n", ep);
	   }
	   if (estrp != NULL)
	       free((void *)estrp);
       }

       Reference  should be made to the Hardware Specific Guide for details of
       System Configuration Administration support.

SunOS 5.10			  1 Sep 2004		 config_admin(3CFGADM)
[top]

List of man pages available for Solaris

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net