1config_admin(3CFGCAoDnMf)iguration Administration Library Functcioonnfsig_admin(3CFGADM)
2
6 config_admin, config_change_state, config_private_func, config_test,
7 config_stat, config_list, config_list_ext, config_ap_id_cmp, con‐
8 fig_unload_libs, config_strerror - configuration administration inter‐
9 face
10
12 cc [ flag... ] file... -lcfgadm [ library... ]
13 #include <config_admin.h>
14 #include <sys/param.h>
15 cfga_err_t config_change_state(cfga_cmd_t state_change_cmd,
17 int num_ap_ids, char * const *ap_ids, const char *options,
18 struct cfga_confirm *confp, struct cfga_msg *msgp,
19 char **errstring, cfga_flags_t flags);
20 cfga_err_t config_private_func(const char *function, int num_ap_ids,
23 char * const *ap_ids, const char *options,
24 struct cfga_confirm *confp, msgp, char **errstring,
25 cfga_flags_t flags);
26 cfga_err_t config_test(int num_ap_ids, char * const *ap_ids,
29 const char *options, struct cfga_msg *msgp,
30 char **errstring, cfga_flags_t flags);
31 cfga_err_t config_list_ext(int num_ap_ids, char * const *ap_ids,
34 struct cfga_list_data **ap_id_list, int *nlist,
35 const char *options, const char *listops,
36 char **errstring, cfga_flags_t flags);
37 int config_ap_id_cmp(const cfga_ap_id_t ap_id1,
40 const cfga_ap_id_t ap_id2);
41 void config_unload_libs(void);
44 const char *config_strerror(cfga_err_t cfgerrnum);
47 Deprecated Interfaces
50 The following interfaces have been deprecated and their use is strongly
51 discouraged:
52 cfga_err_t config_stat(int num_ap_ids, char * const *ap_ids,
54 struct cfga_stat_data *buf, const char *options, char **errstring);
55 cfga_err_t config_list(struct cfga_stat_data **ap_id_list,
58 int *nlist, const char *options, char **errstring);
59
62 The config_admin library is a generic interface that is used for
63 dynamic configuration, (DR). Each piece of hardware that supports DR
64 must supply a hardware-specific plugin library that contains the entry
65 points listed in this subsection. The generic library will locate and
66 link to the appropriate library to effect DR operations. The interfaces
67 specified in this subsection are really "hidden" from users of the
68 generic libraries. It is, however, necessary that writers of the hard‐
69 ware-specific plug in libraries know what these interfaces are.
70 cfga_err_t cfga_change_state(cfga_cmd_t state_change_cmd,
72 const char *ap_id, const char *options, struct cfga_confirm *confp,
73 struct cfga_msg *msgp, char **errstring, cfga_flags_t flags);
74 cfga_err_t cfga_private_func(const char *function,
77 const char *ap_id, const char *options, struct cfga_confirm *confp,
78 struct cfga_msg *msgp, char **errstring, cfga_flags_t flags);
79 cfga_err_t cfga_test(const char *ap_id, const char *options,
82 struct cfga_msg *msgp, char **errstring, cfga_flags_t flags);
83 cfga_err_t cfga_list_ext(const char *ap_id,
86 struct cfga_list_data **ap_id_list, nlist, const char *options,
87 const char *listopts, char **errstring, cfga_flags_t flags);
88 cfga_err_t cfga_help(struct cfga_msg *msgp, const char *options,
91 cfga_flags_t flags);
92 int cfga_ap_id_cmp(const cfga_ap_id_t ap_id1, const cfga_ap_id_t ap_id2);
95 Deprecated Interfaces
98 The following interfaces have been deprecated and their use is strongly
99 discouraged:
100 cfga_err_t cfga_stat(const char *ap_id, struct cfga_stat_data *buf,
102 const char *options, char **errstring);
103 cfga_err_t cfga_list(const char *ap_id,
106 struct cfga_stat_data **ap_id_list, int *nlist, const char *options,
107 char **errstring);
108
111 The config_*() functions provide a hardware independent interface to
112 hardware-specific system configuration administration functions. The
113 cfga_*() functions are provided by hardware-specific libraries that are
114 dynamically loaded to handle configuration administration functions in
115 a hardware-specific manner.
116 The libcfgadm library is used to provide the services of the cfgadm(1M)
119 command. The hardware-specific libraries are located in /usr/plat‐
120 form/${machine}/lib/cfgadm, /usr/platform/${arch}/lib/cfgadm, and
121 /usr/lib/cfgadm. The hardware-specific library names are derived from
122 the driver name or from class names in device tree nodes that identify
123 attachment points.
124 The config_change_state() function performs operations that change the
127 state of the system configuration. The state_change_cmd argument can be
128 one of the following: CFGA_CMD_INSERT, CFGA_CMD_REMOVE, CFGA_CMD_DIS‐
129 CONNECT, CFGA_CMD_CONNECT, CFGA_CMD_CONFIGURE, or CFGA_CMD_UNCONFIGURE.
130 The state_change_cmd CFGA_CMD_INSERT is used to prepare for manual
131 insertion or to activate automatic hardware insertion of an occupant.
132 The state_change_cmd CFGA_CMD_REMOVE is used to prepare for manual
133 removal or activate automatic hardware removal of an occupant. The
134 state_change_cmd CFGA_CMD_DISCONNECT is used to disable normal communi‐
135 cation to or from an occupant in a receptacle. The state_change_cmd
136 CFGA_CMD_CONNECT is used to enable communication to or from an occupant
137 in a receptacle. The state_change_cmd CFGA_CMD_CONFIGURE is used to
138 bring the hardware resources contained on, or attached to, an occupant
139 into the realm of Solaris, allowing use of the occupant's hardware
140 resources by the system. The state_change_cmd CFGA_CMD_UNCONFIGURE is
141 used to remove the hardware resources contained on, or attached to, an
142 occupant from the realm of Solaris, disallowing further use of the
143 occupant's hardware resources by the system.
144 The flags argument may contain one or both of the defined flags,
147 CFGA_FLAG_FORCE and CFGA_FLAG_VERBOSE. If the CFGA_FLAG_FORCE flag is
148 asserted certain safety checks will be overridden. For example, this
149 may not allow an occupant in the failed condition to be configured, but
150 might allow an occupant in the failing condition to be configured.
151 Acceptance of a force is hardware dependent. If the CFGA_FLAG_VERBOSE
152 flag is asserted hardware-specific details relating to the operation
153 are output utilizing the cfga_msg mechanism.
154 The config_private_func() function invokes private hardware-specific
157 functions.
158 The config_test() function is used to initiate testing of the specified
161 attachment point.
162 The num_ap_ids argument specifies the number of ap_ids in the ap_ids
165 array. The ap_ids argument points to an array of ap_ids.
166 The ap_id argument points to a single ap_id.
169 The function and options strings conform to the getsubopt(3C) syntax
172 convention and are used to supply hardware-specific function or option
173 information. No generic hardware-independent functions or options are
174 defined.
175 The cfga_confirm structure referenced by confp provides a call-back
178 interface to get permission to proceed should the requested operation
179 require, for example, a noticeable service interruption. The cfga_con‐
180 firm structure includes the following members:
181 int (*confirm)(void *appdata_ptr, const char *message);
183 void *appdata_ptr;
184 The confirm() function is called with two arguments: the generic
188 pointer appdata_ptr and the message detailing what requires confirma‐
189 tion. The generic pointer appdata_ptr is set to the value passed in in
190 the cfga_confirm structure member appdata_ptr and can be used in a
191 graphical user interface to relate the confirm function call to the
192 config_*() call. The confirm() function should return 1 to allow the
193 operation to proceed and 0 otherwise.
194 The cfga_msg structure referenced by msgp provides a call-back inter‐
197 face to output messages from a hardware-specific library. In the pres‐
198 ence of the CFGA_FLAG_VERBOSE flag, these messages can be informa‐
199 tional; otherwise they are restricted to error messages. The cfga_msg
200 structure includes the following members:
201 int (*message_routine)(void *appdata_ptr, const char *message);
203 void *appdata_ptr;
204 The message_routine() function is called with two arguments: the
208 generic pointer appdata_ptr and the message. The generic pointer app‐
209 data_ptr is set to the value passed in in the cfga_confirm structure
210 member appdata_ptr and can be used in a graphical user interface to
211 relate the message_routine() function call to the config_*() call. The
212 messages must be in the native language specified by the LC_MESSAGES
213 locale category; see setlocale(3C).
214 For some generic errors a hardware-specific error message can be
217 returned. The storage for the error message string, including the ter‐
218 minating null character, is allocated by the config_* functions using
219 malloc(3C) and a pointer to this storage returned through errstring. If
220 errstring is NULL no error message will be generated or returned. If
221 errstring is not NULL and no error message is generated, the pointer
222 referenced by errstring will be set to NULL. It is the responsibility
223 of the function calling config_*() to deallocate the returned storage
224 using free(3C). The error messages must be in the native language spec‐
225 ified by the LC_MESSAGES locale category; see setlocale(3C).
226 The config_list_ext() function provides the listing interface. When
229 supplied with a list of ap_ids through the first two arguments, it
230 returns an array of cfga_list_data_t structures for each attachment
231 point specified. If the first two arguments are 0 and NULL respec‐
232 tively, then all attachment points in the device tree will be listed.
233 Additionally, dynamic expansion of an attachment point to list dynamic
234 attachment points may also be requested by passing the
235 CFGA_FLAG_LIST_ALL flag through the flags argument. Storage for the
236 returned array of stat structures is allocated by the config_list_ext()
237 function using malloc(3C). This storage must be freed by the caller of
238 config_list_ext() by using free(3C).
239 The cfga_list_data structure includes the following members:
242 cfga_log_ext_t ap_log_id; /* Attachment point logical id */
244 cfga_phys_ext_t ap_phys_id; /* Attachment point physical id */
245 cfga_class_t ap_class; /* Attachment point class */
246 cfga_stat_t ap_r_state; /* Receptacle state */
247 cfga_stat_t ap_o_state; /* Occupant state */
248 cfga_cond_t ap_cond; /* Attachment point condition */
249 cfga_busy_t ap_busy; /* Busy indicator */
250 time_t ap_status_time; /* Attachment point last change*/
251 cfga_info_t ap_info; /* Miscellaneous information */
252 cfga_type_t ap_type; /* Occupant type */
253 The types are defined as follows:
257 typedef char cfga_log_ext_t[CFGA_LOG_EXT_LEN];
259 typedef char cfga_phys_ext_t[CFGA_PHYS_EXT_LEN];
260 typedef char cfga_class_t[CFGA_CLASS_LEN];
261 typedef char cfga_info_t[CFGA_INFO_LEN];
262 typedef char cfga_type_t[CFGA_TYPE_LEN];
263 typedef enum cfga_cond_t;
264 typedef enum cfga_stat_t;
265 typedef int cfga_busy_t;
266 typedef int cfga_flags_t;
267 The listopts argument to config_list_ext() conforms to the getsub‐
271 opt(3C) syntax and is used to pass listing sub-options. Currently, only
272 the sub-option class=class_name is supported. This list option
273 restricts the listing to attachment points of class class_name.
274 The listopts argument to cfga_list_ext() is reserved for future use.
277 Hardware-specific libraries should ignore this argument if it is NULL.
278 If listopts is not NULL and is not supported by the hardware-specific
279 library, an appropriate error code should be returned.
280 The ap_log_id and the ap_phys_id members give the hardware-specific
283 logical and physical names of the attachment point. The ap_busy memberd
284 indicates activity is present that may result in changes to state or
285 condition. The ap_status_time member provides the time at which either
286 the ap_r_state, ap_o_state, or ap_cond field of the attachment point
287 last changed. The ap_info member is available for the hardware-specific
288 code to provide additional information about the attachment point. The
289 ap_class member contains the attachment point class (if any) for an
290 attachment point. The ap_class member is filled in by the generic
291 library. If the ap_log_id and ap_phys_id members are not filled in by
292 the hardware-specific library, the generic library will fill in these
293 members using a generic format. The remaining members are the responsi‐
294 bility of the corresponding hardware-tospecific library.
295 All string members in the cfga_list_data structure are null-terminated.
298 The config_stat(), config_list(), cfga_stat(), and cfga_list() func‐
301 tions and the cfga_stat_data data structure are deprecated interfaces
302 and are provided solely for backward compatibility. Use of these
303 interfaces is strongly discouraged.
304 The config_ap_id_cmp function performs a hardware dependent comparison
307 on two ap_ids, returning an equal to, less than or greater than indi‐
308 cation in the manner of strcmp(3C). Each argument is either a
309 cfga_ap_id_t or can be a null-terminated string. This function can be
310 used when sorting lists of ap_ids, for example with qsort(3C), or when
311 selecting entries from the result of a config_list function call.
312 The config_unload_libs function unlinks all previously loaded hardware-
315 specific libraries.
316 The config_strerror function can be used to map an error return value
319 to an error message string. See RETURN VALUES. The returned string
320 should not be overwritten. config_strerror returns NULL if cfgerrnum is
321 out-of-range.
322 The cfga_help function can be used request that a hardware-specific
325 library output it's localized help message.
326
328 The config_*() and cfga_*() functions return the following values.
329 Additional error information may be returned through errstring if the
330 return code is not CFGA_OK. See DESCRIPTION for details.
331 CFGA_BUSY
333 The command was not completed due to an element of the system con‐
335 figuration administration system being busy.
336 CFGA_ATTR_INVAL
339 No attachment points with the specified attributes exists
341 CFGA_ERROR
344 An error occurred during the processing of the requested operation.
346 This error code includes validation of the command arguments by the
347 hardware-specific code.
348 CFGA_INSUFFICIENT_CONDITION
351 Operation failed due to attachment point condition.
353 CFGA_INVAL
356 The system configuration administration operation requested is not
358 supported on the specified attachment point.
359 CFGA_LIB_ERROR
362 A procedural error occurred in the library, including failure to
364 obtain process resources such as memory and file descriptors.
365 CFGA_NACK
368 The command was not completed due to a negative acknowledgement
370 from the confp->confirm function.
371 CFGA_NO_LIB
374 A hardware-specific library could not be located using the supplied
376 ap_id.
377 CFGA_NOTSUPP
380 System configuration administration is not supported on the speci‐
382 fied attachment point.
383 CFGA_OK
386 The command completed as requested.
388 CFGA_OPNOTSUPP
391 System configuration administration operation is not supported on
393 this attachment point.
394 CFGA_PRIV
397 The caller does not have the required process privileges. For exam‐
399 ple, if configuration administration is performed through a device
400 driver, the permissions on the device node would be used to control
401 access.
402 CFGA_SYSTEM_BUSY
405 The command required a service interruption and was not completed
407 due to a part of the system that could not be quiesced.
408
411 Many of the errors returned by the system configuration administration
412 functions are hardware-specific. The strings returned in errstring may
413 include the following:
414 attachment point ap_id not known
416 The attachment point detailed in the error message does not exist.
418 unknown hardware option option foroperation
421 An unknown option was encountered in the options string.
423 hardware option option requires a value
426 An option in the options string should have been of the form
428 option=value.
429 listing option list_option requires a value
432 An option in the listopts string should have been of the form
434 option=value.
435 hardware option option does not require a value
438 An option in the options string should have been a simple option.
440 attachment point ap_id is not configured
443 A config_change_state command to CFGA_CMD_UNCONFIGURE an occupant
445 was made to an attachment point whose occupant was not in the
446 CFGA_STAT_CONFIGURED state.
447 attachment point ap_id is not unconfigured
450 A config_change_state command requiring an unconfigured occupant
452 was made to an attachment point whose occupant was not in the
453 CFGA_STAT_UNCONFIGURED state.
454 attachment point ap_id condition not satisfactory
457 A config_change_state command was made to an attachment point
459 whose condition prevented the operation.
460 attachment point ap_id in condition condition cannot be used
463 A config_change_state operation with force indicated was directed
465 to an attachment point whose condition fails the hardware dependent
466 test.
467
470 See attributes(5) for descriptions of the following attributes:
471 ┌─────────────────────────────┬─────────────────────────────┐
476 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
477 ├─────────────────────────────┼─────────────────────────────┤
478 │Availability │SUNWcsu, SUNWkvm │
479 ├─────────────────────────────┼─────────────────────────────┤
480 │MT-Level │Safe │
481 └─────────────────────────────┴─────────────────────────────┘
482
484 cfgadm(1M), devinfo(1M), dlopen(3C), dlsym(3C), free(3C), getsub‐
485 opt(3C), malloc(3C), qsort(3C), setlocale(3C), strcmp(3C), libcf‐
486 gadm(3LIB), attributes(5)
487
489 Applications using this library should be aware that the underlying
490 implementation may use system services which alter the contents of the
491 external variable errno and may use file descriptor resources.
492 The following code shows the intended error processing when config_*()
495 returns a value other than CFGA_OK:
496 void
498 emit_error(cfga_err_t cfgerrnum, char *estrp)
499 {
500 const char *ep;
501 ep = config_strerror(cfgerrnum);
502 if (ep == NULL)
503 ep = gettext("configuration administration unknown error");
504 if (estrp != NULL && *estrp != '\0') {
505 (void) fprintf(stderr, "%s: %s\n", ep, estrp);
506 } else {
507 (void) fprintf(stderr, "%s\n", ep);
508 }
509 if (estrp != NULL)
510 free((void *)estrp);
511 }
512 Reference should be made to the Hardware Specific Guide for details of
516 System Configuration Administration support.
517SunOS 5.11 1 Sep 2004 config_admin(3CFGADM)