Configuration Administration Library Functions
config_admin(3CFGADM)
NAME
config_admin, config_change_state, config_private_func,
config_test, config_stat, config_list, config_list_ext,
config_ap_id_cmp, config_unload_libs, config_strerror - con-
figuration administration interfaceSYNOPSIS
cc [ flag... ] file... -lcfgadm [ library... ]
#include
#include
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_confirm *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, 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);
SunOS 5.11 Last change: 1 Sep 2004 1
Configuration Administration Library Functionsconfig_admin(3CFGADM)
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 thatsupports 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 interfaces specified inthis subsection are really "hidden" from users of the gen-
eric libraries. It is, however, necessary that writers ofthe 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, 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);SunOS 5.11 Last change: 1 Sep 2004 2
Configuration Administration Library Functionsconfig_admin(3CFGADM)
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 adminis-
tration functions. The cfga_*() functions are provided by
hardware-specific libraries that are dynamically loaded to
handle configuration administration functions in ahardware-specific manner.
The libcfgadm library is used to provide the services of thecfgadm(1M) command. The hardware-specific libraries are
located in /usr/platform/${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. Thestate_change_cmd argument can be one of the following:
CFGA_CMD_INSERT, CFGA_CMD_REMOVE, CFGA_CMD_DISCONNECT,
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. Thestate_change_cmd CFGA_CMD_REMOVE is used to prepare for
manual removal or activate automatic hardware removal of anoccupant. The state_change_cmd CFGA_CMD_DISCONNECT is used
to disable normal communication to or from an occupant in areceptacle. 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'shardware 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 definedflags, 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 occupantSunOS 5.11 Last change: 1 Sep 2004 3
Configuration Administration Library Functionsconfig_admin(3CFGADM)
in the failed condition to be configured, but might allow anoccupant in the failing condition to be configured. Accep-
tance of a force is hardware dependent. If theCFGA_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 supplyhardware-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 ser-
vice interruption. The cfga_confirm structure includes the
following members:int (*confirm)(void *appdata_ptr, const char *message);
void *appdata_ptr;
The confirm() function is called with two arguments: thegeneric pointer appdata_ptr and the message detailing what
requires confirmation. 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 con-
fig_*() call. The confirm() function should return 1 to
allow the operation to proceed and 0 otherwise.SunOS 5.11 Last change: 1 Sep 2004 4
Configuration Administration Library Functionsconfig_admin(3CFGADM)
The cfga_msg structure referenced by msgp provides a call-
back interface to output messages from a hardware-specific
library. In the presence of the CFGA_FLAG_VERBOSE flag,
these messages can be informational; otherwise they are res-
tricted 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 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 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 terminating null character, is allocated bythe config_* functions using malloc(3C) and a pointer to
this storage returned through errstring. If errstring isNULL no error message will be generated or returned. If err-
string is not NULL and no error message is generated, the pointer referenced by errstring will be set to NULL. It isthe responsibility of the function calling config_*() to
deallocate the returned storage using free(3C). The error messages must be in the native language specified by theLC_MESSAGES locale category; see setlocale(3C).
The config_list_ext() function provides the listing inter-
face. 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 firsttwo arguments are 0 and NULL respectively, then all attach-
ment 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 theCFGA_FLAG_LIST_ALL flag through the flags argument. Storage
for the returned array of stat structures is allocated bythe config_list_ext() function using malloc(3C). This
storage must be freed by the caller of config_list_ext() by
using free(3C).SunOS 5.11 Last change: 1 Sep 2004 5
Configuration Administration Library Functionsconfig_admin(3CFGADM)
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 toattachment 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 notsupported 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 theSunOS 5.11 Last change: 1 Sep 2004 6
Configuration Administration Library Functionsconfig_admin(3CFGADM)
attachment point. The ap_class member contains the attach-
ment point class (if any) for an attachment point. Theap_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 membersare the responsibility 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() functions and the cfga_stat_data data structure
are deprecated interfaces and are provided solely for back-
ward 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 indication in the manner of strcmp(3C). Eachargument is either a cfga_ap_id_t or can be a null-
terminated string. This function can be used when sortinglists of ap_ids, for example with qsort(3C), or when select-
ing 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 througherrstring if the return code is not CFGA_OK. See DESCRIP-
TION for details.CFGA_BUSY
SunOS 5.11 Last change: 1 Sep 2004 7
Configuration Administration Library Functionsconfig_admin(3CFGADM)
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 existsCFGA_ERROR
An error occurred during the processing of the requested operation. This error code includes validation of thecommand 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 ack-
nowledgement 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 onSunOS 5.11 Last change: 1 Sep 2004 8
Configuration Administration Library Functionsconfig_admin(3CFGADM)
the specified attachment 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 performed through a device driver, the permissions on the device node would be used to control access.CFGA_SYSTEM_BUSY
The command required a service interruption 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 configurationadministration 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 foroperation 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.SunOS 5.11 Last change: 1 Sep 2004 9
Configuration Administration Library Functionsconfig_admin(3CFGADM)
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 valueAn option in the options string should have been a sim-
ple 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 occu-
pant 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 occupantwas 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 attri-
butes:SunOS 5.11 Last change: 1 Sep 2004 10
Configuration Administration Library Functionsconfig_admin(3CFGADM)
_________________________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|________________________________|
| Availability | SUNWcs, system/library/platform||_____________________________|________________________________|
| MT-Level | Safe |
|_____________________________|________________________________|
SEE ALSO
cfgadm(1M), devinfo(1M), dlopen(3C), dlsym(3C), free(3C), getsubopt(3C), malloc(3C), qsort(3C), setlocale(3C), strcmp(3C), libcfgadm(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 whenconfig_*() returns a value other than CFGA_OK:
voidemit_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.11 Last change: 1 Sep 2004 11
Configuration Administration Library Functionsconfig_admin(3CFGADM)
SunOS 5.11 Last change: 1 Sep 2004 12