CONFIG_ADMIN(3CFGADM) Configuration Administration Library Functions

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 - configuration administration
interface

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_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 *listopts,
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 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_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);


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(8) 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. The state_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. 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
the operating system, 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 the operating system, 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_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 1
to allow the operation to proceed and 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:

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 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 specified 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
respectively, 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
member 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 responsibility of the corresponding
hardware-specific 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 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 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_*() 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 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 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.


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(7) for descriptions of the following attributes:


+---------------+-----------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+-----------------+
|MT-Level | Safe |
+---------------+-----------------+

SEE ALSO

dlopen(3C), dlsym(3C), free(3C), getsubopt(3C), malloc(3C),
qsort(3C), setlocale(3C), strcmp(3C), libcfgadm(3LIB), attributes(7),
cfgadm(8), devinfo(8)

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.

August 2, 2023 CONFIG_ADMIN(3CFGADM)