svcadm(8)을 검색하려면 섹션에서 8 을 선택하고, 맨 페이지 이름에 svcadm을 입력하고 검색을 누른다.
config_admin(3cfgadm)
co...n(3CFGADM) Configuration Administration Library Functions co...n(3CFGADM)
NAME
config_admin, config_change_state, config_private_func, config_test,
config_stat, config_list, config_list_ext, config_apinfo_iter, con‐
fig_apinfo_dup, config_apinfo_free, config_ap_id_cmp, config_un‐
load_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_apinfo_iter(const char *ap_id,
int(listcb)(cfga_apinfo_t *ap, void *arg), void *arg
const char *options, const char *listops,
char **errstring, cfga_flags_t flags);
cfga_apinfo_t *config_apinfo_dup(cfga_apinfo_t *ap);
void config_apinfo_free(cfga_aplist_t *ap);
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);
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);
HARDWARE DEPENDENT LIBRARY SYNOPSIS
The config_admin library is a generic interface that is used for dy‐
namic 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 hard‐
ware-specific plugin 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_plugin_apinfo(const char *ap_id, void *cookie,
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);
Plugin Support Interface
Unlike the cfga_list_ext(), cfga_plugin_apinfo() does not take the
ap_id_list argument to store a pointer to an array of information. In‐
stead, the cfga_plugin_apinfo() takes the cookie argument to be able to
supply multiple instances of attachment points. The following interface
can be used from cfga_plugin_apinfo() entry point to add an instance of
attachment point.
cfga_err_t cfga_plugin_apinfo_add(void *cookie, cfga_aplist_t *ap);
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);
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);
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/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 in‐
sertion 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 commu‐
nication 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 re‐
sources 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 oc‐
cupant'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. Ac‐
ceptance 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 in‐
terface to get permission to proceed should the requested operation re‐
quire, 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 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 re‐
late 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 re‐
turned. The storage for the error message string, including the termi‐
nating 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_apinfo_iter() function provides the listing interface. When
supplied with an ap_id through the first argument, it calls back the
function listcb for each attachment points. The listcb function is
called with a pointer to the cfga_apinfo_t structure and the arg argu‐
ment supplied to the config_apinfo_iter(). If the first argument is a
NULL pointer, then listcb will be called for all attachment points in
the device tree. Additionally, dynamic expansion of an attachment point
to the list of dynamic attachment points may also be requested by pass‐
ing the CFGA_FLAG_LIST_ALL flag through the flags argument. Storage for
the cfga_apinfo_t supplied to the listcb function is freed when con‐
fig_apinfo_iter() returns. Therefore, an application must duplicate the
cfga_apinfo_t structure by using the config_apinfo_dup() if it needs to
be saved for later use.
The config_apinfo_dup() function duplicates the given cfga_apinfo_t
structure and the character strings pointed by its structure members.
The config_apinfo_free() function frees given cfga_apinfo_t structure
and its character storage allocated by the config_aplist_dup() func‐
tion.
The cfga_aplist_t structure includes the following members:
char *ap_log_id; /* Attachment point logical id */
char *ap_phys_id; /* Attachment point physical id */
char *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*/
char *ap_info; /* Miscellaneous information */
char *ap_type; /* Occupant type */
The types are defined as follows:
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_aplist_iter() conforms to the getsub‐
opt(3C) syntax and is used to pass listing sub-options. Currently, only
the sub-option class=class_name is supported. This list option re‐
stricts the listing to attachment points of class class_name.
The listopts argument to config_aplist_iter() 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-spe‐
cific 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 at‐
tachment point. The ap_class member is filled in by the generic li‐
brary. 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 mem‐
bers using a generic format. The remaining members are the responsibil‐
ity of the corresponding hardware-specific library.
The config_stat(), config_list(), config_list_ext(), cfga_stat(),
cfga_list(), and cfga_list_ext() functions and the cfga_stat_data and
cfga_list_data data structure are deprecated interfaces and are pro‐
vided 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 indica‐
tion 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_aplist_iter 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 to request that a hardware-specific
library output its localized help message.
RETURN VALUES
The config_*() and cfga_*() functions return the following values. Ad‐
ditional error information may be returned through errstring if the re‐
turn code is not CFGA_OK. See DESCRIPTION for details.
CFGA_BUSY
The command was not completed due to an element of the system con‐
figuration 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 acknowledgment 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 speci‐
fied 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 exam‐
ple, 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 op‐
tion=value.
listing option list_option requires a value
An option in the listopts string should have been of the form op‐
tion=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:
tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) ATTRIBUTE TYPEAT‐
TRIBUTE VALUE _ Availabilitysystem/core-os, system/library/platform _
MT-LevelSafe
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 im‐
plementation 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.
Oracle Solaris 11.4 11 May 2021 co...n(3CFGADM)