config_admin(3X)

NAME | SYNOPSIS | HARDWARE DEPENDENT LIBRARY SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | ATTRIBUTES | SEE ALSO | NOTES

NAME

config_admin, config_change_state, config_private_func, config_test, config_stat, config_list, config_ap_id_cmp, config_unload, config_strerror- configuration administration interface

SYNOPSIS

cc [ flag ] file -lcfgadm -ldevinfo -ldl [ library... ]
#include <config_admin.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_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, 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_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);
int config_ap_id_cmp(const cfga_ap_id_t ap_id1, const cfga_ap_id_t ap_id2);
void config_unload_libs();
const char *config_strerror(cfga_err_t cfgerrnum);

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 interfaces 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_stat(const char *ap_id, struct cfga_stat_data *buf, const char *options, char **errstring);
cfga_err_t cfga_lib(const char *ap_id, struct cfga_stat_data **ap_id_list, int *nlist, const char *options, char **errstring);
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);

DESCRIPTION

The config_* routines provide a hardware independent interface to hardware specific system configuration administration functions. The cfga_* routines 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/platform/${machine}/lib/cfgadm, /usr/platform/${arch}/lib/cfgadm, and /usr/lib/cfgadm. The hardware specific library names are derived from the nodename and driver name in device tree nodes that identify attachment points (DDI_NT_ATTACHMENT_POINT).

The config_change_state routine performs functions that change the state of the system configuration. The state_change_cmd 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. 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 communication 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 routine invokes private hardware specific functions.

The config_test routine 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_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: The generic 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 config_* call. The confirm function should return one (1) to allow the operation to proceed and zero (0) otherwise.

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 restricted to error messages. The cfga_msg structure includes the following members:

void	(*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 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 de-allocate the returned storage using free(3C). The error messages must be in the native language specified by the LC_MESSAGES locale category; see setlocale(3C).

The config_stat routine provides a way of getting status for an attachment point. The cfga_stat_data structure includes the following members:

cfga_ap_id_t       ap_log_id;        /* Attachment point logical id */
cfga_ap_id_t       ap_phys_id;       /* Attachment point physical id */
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_ap_id_t[CFGA_AP_ID_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 enum cfga_busy_t;
typedef int cfga_flags_t;

The ap_log_id and the ap_phys_id fields give the hardware specific logical and physical names of the attachment point. The ap_busy field indicates activity is present that may result in changes to state or condition. The ap_status_time field gives the time at which either the ap_r_state, ap_o_state or ap_cond fields of the attachment point, last changed. The field ap_info is available for the hardware specific code to provide additional information about the attachment point.

The fields ap_log_id, ap_phys_id, cfga_info_t and cfga_type_t are null terminated strings. When printing these fields the following format is suggested:

---

printf("%.*s", sizeof(p->ap_log_id), p->ap_log_id);

---

The config_list routine provides a way of obtaining the status of all attachment points in the system. The function returns an array of cfga_stat_data structures, one for each attachment point in the system. The storage for the array is allocated by the config_list function using malloc(3C) and a pointer to this storage returned through ap_id_list. The number of array elements is returned through nlist. It is the responsibility of the function calling config_list to de-allocate the returned storage using free(3C).

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). 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_* routines return the following possible 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_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 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 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.

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(3X), dlsym(3X), free(3C), getsubopt (3C), malloc(3C), qsort(3C), setlocale(3C), strcmp(3C), libcfgadm( 4), 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(int 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.7  Last Revised 20 Feb 1998

NAME | SYNOPSIS | HARDWARE DEPENDENT LIBRARY SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | ATTRIBUTES | SEE ALSO | NOTES