| blob | f299c72ff33bbb0fc50ecccfbe5bd6732aee74f5 |
1 '\" te
2 .\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH CONFIG_ADMIN 3CFGADM "Sep 1, 2004"
7 .SH NAME
8 config_admin, config_change_state, config_private_func, config_test,
9 config_stat, config_list, config_list_ext, config_ap_id_cmp,
10 config_unload_libs, config_strerror \- configuration administration interface
11 .SH SYNOPSIS
12 .LP
13 .nf
14 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lcfgadm\fR [ \fIlibrary\fR... ]
15 #include <config_admin.h>
16 #include <sys/param.h>
18 \fBcfga_err_t\fR \fBconfig_change_state\fR(\fBcfga_cmd_t\fR \fIstate_change_cmd\fR,
19 \fBint\fR \fInum_ap_ids\fR, \fBchar * const *\fR\fIap_ids\fR, \fBconst char *\fR\fIoptions\fR,
20 \fBstruct cfga_confirm *\fR\fIconfp\fR, \fBstruct cfga_msg *\fR\fImsgp\fR,
21 \fBchar **\fR\fIerrstring\fR, \fBcfga_flags_t\fR \fIflags\fR);
22 .fi
24 .LP
25 .nf
26 \fBcfga_err_t\fR \fBconfig_private_func\fR(\fBconst char *\fR\fIfunction\fR, \fBint\fR \fInum_ap_ids\fR,
27 \fBchar * const *\fR\fIap_ids\fR, \fBconst char *\fR\fIoptions\fR,
28 \fBstruct cfga_confirm *\fR\fIconfp\fR, \fImsgp\fR, \fBchar **\fR\fIerrstring\fR,
29 \fBcfga_flags_t\fR \fIflags\fR);
30 .fi
32 .LP
33 .nf
34 \fBcfga_err_t\fR \fBconfig_test\fR(\fBint\fR \fInum_ap_ids\fR, \fBchar * const *\fR\fIap_ids\fR,
35 \fBconst char *\fR\fIoptions\fR, \fBstruct cfga_msg *\fR\fImsgp\fR,
36 \fBchar **\fR\fIerrstring\fR, \fBcfga_flags_t\fR \fIflags\fR);
37 .fi
39 .LP
40 .nf
41 \fBcfga_err_t\fR \fBconfig_list_ext\fR(\fBint\fR \fInum_ap_ids\fR, \fBchar * const *\fR\fIap_ids\fR,
42 \fBstruct cfga_list_data **\fR\fIap_id_list\fR, \fBint *\fR\fInlist\fR,
43 \fBconst char *\fR\fIoptions\fR, \fBconst char *\fR\fIlistops\fR,
44 \fBchar **\fR\fIerrstring\fR, \fBcfga_flags_t\fR \fIflags\fR);
45 .fi
47 .LP
48 .nf
49 \fBint\fR \fBconfig_ap_id_cmp\fR(\fBconst cfga_ap_id_t\fR \fIap_id1\fR,
50 \fBconst cfga_ap_id_t\fR \fIap_id2\fR);
51 .fi
53 .LP
54 .nf
55 \fBvoid\fR \fBconfig_unload_libs\fR(\fBvoid\fR);
56 .fi
58 .LP
59 .nf
60 \fBconst char *\fR\fBconfig_strerror\fR(\fBcfga_err_t\fR \fIcfgerrnum\fR);
61 .fi
63 .SS "Deprecated Interfaces"
64 .sp
65 .LP
66 The following interfaces have been deprecated and their use is strongly
67 discouraged:
68 .LP
69 .nf
70 \fBcfga_err_t\fR \fBconfig_stat\fR(\fBint\fR \fInum_ap_ids\fR, \fBchar * const *\fR\fIap_ids\fR,
71 \fBstruct cfga_stat_data *\fR\fIbuf\fR, \fBconst char *\fR\fIoptions\fR, \fBchar **\fR\fIerrstring\fR);
72 .fi
74 .LP
75 .nf
76 \fBcfga_err_t\fR \fBconfig_list\fR(\fBstruct cfga_stat_data **\fR\fIap_id_list\fR,
77 \fBint *\fR\fInlist\fR, \fBconst char *\fR\fIoptions\fR, \fBchar **\fR\fIerrstring\fR);
78 .fi
80 .SH HARDWARE DEPENDENT LIBRARY SYNOPSIS
81 .sp
82 .LP
83 The \fBconfig_admin\fR library is a generic interface that is used for dynamic
84 configuration, (DR). Each piece of hardware that supports \fBDR\fR must supply
85 a hardware-specific \fIplugin\fR library that contains the entry points listed
86 in this subsection. The generic library will locate and link to the appropriate
87 library to effect \fBDR\fR operations. The interfaces specified in this
88 subsection are really "hidden" from users of the generic libraries. It is,
89 however, necessary that writers of the hardware-specific plug in libraries know
90 what these interfaces are.
91 .LP
92 .nf
93 \fBcfga_err_t\fR \fBcfga_change_state\fR(\fBcfga_cmd_t\fR \fIstate_change_cmd\fR,
94 \fBconst char *\fR\fIap_id\fR, \fBconst char *\fR\fIoptions\fR, \fBstruct cfga_confirm *\fR\fIconfp\fR,
95 \fBstruct cfga_msg *\fR\fImsgp\fR, \fBchar **\fR\fIerrstring\fR, \fBcfga_flags_t\fR \fIflags\fR);
96 .fi
98 .LP
99 .nf
100 \fBcfga_err_t\fR \fBcfga_private_func\fR(\fBconst char *\fR\fIfunction\fR,
101 \fBconst char *\fR\fIap_id\fR, \fBconst char *\fR\fIoptions\fR, \fBstruct cfga_confirm *\fR\fIconfp\fR,
102 \fBstruct cfga_msg *\fR\fImsgp\fR, \fBchar **\fR\fIerrstring\fR, \fBcfga_flags_t\fR \fIflags\fR);
103 .fi
105 .LP
106 .nf
107 \fBcfga_err_t\fR \fBcfga_test\fR(\fBconst char *\fR\fIap_id\fR, \fBconst char *\fR\fIoptions\fR,
108 \fBstruct cfga_msg *\fR\fImsgp\fR, \fBchar **\fR\fI\fRerrstring, \fBcfga_flags_t\fR \fIflags\fR);
109 .fi
111 .LP
112 .nf
113 \fBcfga_err_t\fR \fBcfga_list_ext\fR(\fBconst char *\fR\fIap_id\fR,
114 \fBstruct cfga_list_data **\fR\fIap_id_list\fR, \fInlist\fR, \fBconst char *\fR\fIoptions\fR,
115 \fBconst char *\fR\fIlistopts\fR, \fBchar **\fR\fIerrstring\fR, \fBcfga_flags_t\fR \fIflags\fR);
116 .fi
118 .LP
119 .nf
120 \fBcfga_err_t\fR \fBcfga_help\fR(\fBstruct cfga_msg *\fR\fImsgp\fR, \fBconst char *\fR\fIoptions\fR,
121 \fBcfga_flags_t\fR \fIflags\fR);
122 .fi
124 .LP
125 .nf
126 \fBint\fR \fBcfga_ap_id_cmp\fR(\fBconst cfga_ap_id_t\fR \fIap_id1\fR, \fBconst cfga_ap_id_t\fR \fIap_id2\fR);
127 .fi
129 .SS "Deprecated Interfaces"
130 .sp
131 .LP
132 The following interfaces have been deprecated and their use is strongly
133 discouraged:
134 .LP
135 .nf
136 \fBcfga_err_t\fR \fBcfga_stat\fR(\fBconst char *\fR\fIap_id\fR, \fBstruct cfga_stat_data *\fR\fIbuf\fR,
137 \fBconst char *\fR\fIoptions\fR, \fBchar **\fR\fIerrstring\fR);
138 .fi
140 .LP
141 .nf
142 \fBcfga_err_t\fR \fBcfga_list\fR(\fBconst char *\fR\fIap_id\fR,
143 \fBstruct cfga_stat_data **\fR\fIap_id_list\fR, \fBint *\fR\fInlist\fR, \fBconst char *\fR\fIoptions\fR,
144 \fBchar **\fR\fIerrstring\fR);
145 .fi
147 .SH DESCRIPTION
148 .sp
149 .LP
150 The \fBconfig_*()\fR functions provide a hardware independent interface to
151 hardware-specific system configuration administration functions. The
152 \fBcfga_*()\fR functions are provided by hardware-specific libraries that are
153 dynamically loaded to handle configuration administration functions in a
154 hardware-specific manner.
155 .sp
156 .LP
157 The \fBlibcfgadm\fR library is used to provide the services of the
158 \fBcfgadm\fR(1M) command. The hardware-specific libraries are located in
159 \fB/usr/platform/${machine}/lib/cfgadm\fR,
160 \fB/usr/platform/${arch}/lib/cfgadm\fR, and \fB/usr/lib/cfgadm\fR. The
161 hardware-specific library names are derived from the driver name or from class
162 names in device tree nodes that identify attachment points.
163 .sp
164 .LP
165 The \fBconfig_change_state()\fR function performs operations that change the
166 state of the system configuration. The \fIstate_change_cmd\fR argument can be
167 one of the following: \fBCFGA_CMD_INSERT\fR, \fBCFGA_CMD_REMOVE\fR,
168 \fBCFGA_CMD_DISCONNECT\fR, \fBCFGA_CMD_CONNECT\fR, \fBCFGA_CMD_CONFIGURE\fR, or
169 \fBCFGA_CMD_UNCONFIGURE\fR. The \fIstate_change_cmd\fR \fBCFGA_CMD_INSERT\fR is
170 used to prepare for manual insertion or to activate automatic hardware
171 insertion of an occupant. The \fIstate_change_cmd\fR \fBCFGA_CMD_REMOVE\fR is
172 used to prepare for manual removal or activate automatic hardware removal of an
173 occupant. The \fIstate_change_cmd\fR \fBCFGA_CMD_DISCONNECT\fR is used to
174 disable normal communication to or from an occupant in a receptacle. The
175 \fIstate_change_cmd\fR \fBCFGA_CMD_CONNECT\fR is used to enable communication
176 to or from an occupant in a receptacle. The \fIstate_change_cmd\fR
177 \fBCFGA_CMD_CONFIGURE\fR is used to bring the hardware resources contained on,
178 or attached to, an occupant into the realm of Solaris, allowing use of the
179 occupant's hardware resources by the system. The \fIstate_change_cmd\fR
180 \fBCFGA_CMD_UNCONFIGURE\fR is used to remove the hardware resources contained
181 on, or attached to, an occupant from the realm of Solaris, disallowing further
182 use of the occupant's hardware resources by the system.
183 .sp
184 .LP
185 The \fIflags\fR argument may contain one or both of the defined flags,
186 \fBCFGA_FLAG_FORCE\fR and \fBCFGA_FLAG_VERBOSE\fR. If the \fBCFGA_FLAG_FORCE\fR
187 flag is asserted certain safety checks will be overridden. For example, this
188 may not allow an occupant in the failed condition to be configured, but might
189 allow an occupant in the failing condition to be configured. Acceptance of a
190 force is hardware dependent. If the \fBCFGA_FLAG_VERBOSE\fR flag is asserted
191 hardware-specific details relating to the operation are output utilizing the
192 \fBcfga_msg\fR mechanism.
193 .sp
194 .LP
195 The \fBconfig_private_func()\fR function invokes private hardware-specific
196 functions.
197 .sp
198 .LP
199 The \fBconfig_test()\fR function is used to initiate testing of the specified
200 attachment point.
201 .sp
202 .LP
203 The \fInum_ap_ids\fR argument specifies the number of \fIap_id\fRs in the
204 \fIap_ids\fR array. The \fIap_ids\fR argument points to an array of
205 \fIap_id\fRs.
206 .sp
207 .LP
208 The \fIap_id\fR argument points to a single \fIap_id\fR.
209 .sp
210 .LP
211 The \fIfunction\fR and \fIoptions\fR strings conform to the \fBgetsubopt\fR(3C)
212 syntax convention and are used to supply hardware-specific function or option
213 information. No generic hardware-independent functions or options are defined.
214 .sp
215 .LP
216 The \fBcfga_confirm\fR structure referenced by \fIconfp\fR provides a call-back
217 interface to get permission to proceed should the requested operation require,
218 for example, a noticeable service interruption. The \fBcfga_confirm\fR
219 structure includes the following members:
220 .sp
221 .in +2
222 .nf
223 int (*confirm)(void *appdata_ptr, const char *message);
224 void *appdata_ptr;
225 .fi
226 .in -2
228 .sp
229 .LP
230 The \fBconfirm()\fR function is called with two arguments: the generic pointer
231 \fIappdata_ptr\fR and the message detailing what requires confirmation. The
232 generic pointer \fIappdata_ptr\fR is set to the value passed in in the
233 \fBcfga_confirm\fR structure member \fBappdata_ptr\fR and can be used in a
234 graphical user interface to relate the \fBconfirm\fR function call to the
235 \fBconfig_*()\fR call. The \fIconfirm\fR() function should return 1 to allow
236 the operation to proceed and 0 otherwise.
237 .sp
238 .LP
239 The \fBcfga_msg\fR structure referenced by \fImsgp\fR provides a call-back
240 interface to output messages from a hardware-specific library. In the presence
241 of the \fBCFGA_FLAG_VERBOSE\fR flag, these messages can be informational;
242 otherwise they are restricted to error messages. The \fBcfga_msg\fR structure
243 includes the following members:
244 .sp
245 .in +2
246 .nf
247 int (*message_routine)(void *appdata_ptr, const char *message);
248 void *appdata_ptr;
249 .fi
250 .in -2
252 .sp
253 .LP
254 The \fBmessage_routine()\fR function is called with two arguments: the generic
255 pointer \fIappdata_ptr\fR and the message. The generic pointer
256 \fIappdata_ptr\fR is set to the value passed in in the \fBcfga_confirm\fR
257 structure member \fBappdata_ptr\fR and can be used in a graphical user
258 interface to relate the \fBmessage_routine()\fR function call to the
259 \fBconfig_*()\fR call. The messages must be in the native language specified by
260 the \fBLC_MESSAGES\fR locale category; see \fBsetlocale\fR(3C).
261 .sp
262 .LP
263 For some generic errors a hardware-specific error message can be returned. The
264 storage for the error message string, including the terminating null character,
265 is allocated by the \fBconfig_\fR\fI*\fR functions using \fBmalloc\fR(3C) and a
266 pointer to this storage returned through \fIerrstring\fR. If \fIerrstring\fR is
267 \fINULL\fR no error message will be generated or returned. If \fIerrstring\fR
268 is not \fINULL\fR and no error message is generated, the pointer referenced by
269 \fIerrstring\fR will be set to \fINULL.\fR It is the responsibility of the
270 function calling \fBconfig_*()\fR to deallocate the returned storage using
271 \fBfree\fR(3C). The error messages must be in the native language specified by
272 the \fBLC_MESSAGES\fR locale category; see \fBsetlocale\fR(3C).
273 .sp
274 .LP
275 The \fBconfig_list_ext()\fR function provides the listing interface. When
276 supplied with a list of \fIap_id\fRs through the first two arguments, it
277 returns an array of \fBcfga_list_data_t\fR structures for each attachment point
278 specified. If the first two arguments are 0 and \fINULL\fR respectively, then
279 all attachment points in the device tree will be listed. Additionally, dynamic
280 expansion of an attachment point to list dynamic attachment points may also be
281 requested by passing the \fBCFGA_FLAG_LIST_ALL\fR flag through the \fIflags\fR
282 argument. Storage for the returned array of \fBstat\fR structures is allocated
283 by the \fBconfig_list_ext()\fR function using \fBmalloc\fR(3C). This storage
284 must be freed by the caller of \fBconfig_list_ext()\fR by using \fBfree\fR(3C).
285 .sp
286 .LP
287 The \fBcfga_list_data\fR structure includes the following members:
288 .sp
289 .in +2
290 .nf
291 cfga_log_ext_t ap_log_id; /* Attachment point logical id */
292 cfga_phys_ext_t ap_phys_id; /* Attachment point physical id */
293 cfga_class_t ap_class; /* Attachment point class */
294 cfga_stat_t ap_r_state; /* Receptacle state */
295 cfga_stat_t ap_o_state; /* Occupant state */
296 cfga_cond_t ap_cond; /* Attachment point condition */
297 cfga_busy_t ap_busy; /* Busy indicator */
298 time_t ap_status_time; /* Attachment point last change*/
299 cfga_info_t ap_info; /* Miscellaneous information */
300 cfga_type_t ap_type; /* Occupant type */
301 .fi
302 .in -2
304 .sp
305 .LP
306 The types are defined as follows:
307 .sp
308 .in +2
309 .nf
310 typedef char cfga_log_ext_t[CFGA_LOG_EXT_LEN];
311 typedef char cfga_phys_ext_t[CFGA_PHYS_EXT_LEN];
312 typedef char cfga_class_t[CFGA_CLASS_LEN];
313 typedef char cfga_info_t[CFGA_INFO_LEN];
314 typedef char cfga_type_t[CFGA_TYPE_LEN];
315 typedef enum cfga_cond_t;
316 typedef enum cfga_stat_t;
317 typedef int cfga_busy_t;
318 typedef int cfga_flags_t;
319 .fi
320 .in -2
322 .sp
323 .LP
324 The \fIlistopts\fR argument to \fBconfig_list_ext()\fR conforms to the
325 \fBgetsubopt\fR(3C) syntax and is used to pass listing sub-options. Currently,
326 only the sub-option \fIclass\fR=\fBclass_name\fR is supported. This list option
327 restricts the listing to attachment points of class \fBclass_name\fR.
328 .sp
329 .LP
330 The \fIlistopts\fR argument to \fBcfga_list_ext()\fR is reserved for future
331 use. Hardware-specific libraries should ignore this argument if it is
332 \fINULL\fR. If \fIlistopts\fR is not \fINULL\fR and is not supported by the
333 hardware-specific library, an appropriate error code should be returned.
334 .sp
335 .LP
336 The \fBap_log_id\fR and the \fBap_phys_id\fR members give the hardware-specific
337 logical and physical names of the attachment point. The \fBap_busy\fR memberd
338 indicates activity is present that may result in changes to state or condition.
339 The \fBap_status_time\fR member provides the time at which either the
340 \fBap_r_state\fR, \fBap_o_state\fR, or \fBap_cond\fR field of the attachment
341 point last changed. The \fBap_info\fR member is available for the
342 hardware-specific code to provide additional information about the attachment
343 point. The \fBap_class\fR member contains the attachment point class (if any)
344 for an attachment point. The \fBap_class\fR member is filled in by the generic
345 library. If the \fBap_log_id\fR and \fBap_phys_id\fR members are not filled in
346 by the hardware-specific library, the generic library will fill in these
347 members using a generic format. The remaining members are the responsibility of
348 the corresponding hardware-tospecific library.
349 .sp
350 .LP
351 All string members in the \fBcfga_list_data\fR structure are null-terminated.
352 .sp
353 .LP
354 The \fBconfig_stat()\fR, \fBconfig_list()\fR, \fBcfga_stat()\fR, and
355 \fBcfga_list()\fR functions and the \fBcfga_stat_data\fR data structure are
356 deprecated interfaces and are provided solely for backward compatibility. Use
357 of these interfaces is strongly discouraged.
358 .sp
359 .LP
360 The \fBconfig_ap_id_cmp\fR function performs a hardware dependent comparison on
361 two \fIap_id\fRs, returning an equal to, less than or greater than indication
362 in the manner of \fBstrcmp\fR(3C). Each argument is either a \fBcfga_ap_id_t\fR
363 or can be a null-terminated string. This function can be used when sorting
364 lists of \fIap_id\fRs, for example with \fBqsort\fR(3C), or when selecting
365 entries from the result of a \fBconfig_list\fR function call.
366 .sp
367 .LP
368 The \fBconfig_unload_libs\fR function unlinks all previously loaded
369 hardware-specific libraries.
370 .sp
371 .LP
372 The \fBconfig_strerror\fR function can be used to map an error return value to
373 an error message string. See \fBRETURN VALUES\fR. The returned string should
374 not be overwritten. \fBconfig_strerror\fR returns \fINULL\fR if \fIcfgerrnum\fR
375 is out-of-range.
376 .sp
377 .LP
378 The \fBcfga_help\fR function can be used request that a hardware-specific
379 library output it's localized help message.
380 .SH RETURN VALUES
381 .sp
382 .LP
383 The \fBconfig_*()\fR and \fBcfga_*()\fR functions return the following values.
384 Additional error information may be returned through \fIerrstring\fR if the
385 return code is not \fBCFGA_OK\fR. See \fBDESCRIPTION\fR for details.
386 .sp
387 .ne 2
388 .na
389 \fB\fBCFGA_BUSY\fR\fR
390 .ad
391 .sp .6
392 .RS 4n
393 The command was not completed due to an element of the system configuration
394 administration system being busy.
395 .RE
397 .sp
398 .ne 2
399 .na
400 \fB\fBCFGA_ATTR_INVAL\fR\fR
401 .ad
402 .sp .6
403 .RS 4n
404 No attachment points with the specified attributes exists
405 .RE
407 .sp
408 .ne 2
409 .na
410 \fB\fBCFGA_ERROR\fR\fR
411 .ad
412 .sp .6
413 .RS 4n
414 An error occurred during the processing of the requested operation. This error
415 code includes validation of the command arguments by the hardware-specific
416 code.
417 .RE
419 .sp
420 .ne 2
421 .na
422 \fB\fBCFGA_INSUFFICIENT_CONDITION\fR\fR
423 .ad
424 .sp .6
425 .RS 4n
426 Operation failed due to attachment point condition.
427 .RE
429 .sp
430 .ne 2
431 .na
432 \fB\fBCFGA_INVAL\fR\fR
433 .ad
434 .sp .6
435 .RS 4n
436 The system configuration administration operation requested is not supported on
437 the specified attachment point.
438 .RE
440 .sp
441 .ne 2
442 .na
443 \fB\fBCFGA_LIB_ERROR\fR\fR
444 .ad
445 .sp .6
446 .RS 4n
447 A procedural error occurred in the library, including failure to obtain process
448 resources such as memory and file descriptors.
449 .RE
451 .sp
452 .ne 2
453 .na
454 \fB\fBCFGA_NACK\fR\fR
455 .ad
456 .sp .6
457 .RS 4n
458 The command was not completed due to a negative acknowledgement from the
459 \fIconfp\fR\fB->confirm\fR function.
460 .RE
462 .sp
463 .ne 2
464 .na
465 \fB\fBCFGA_NO_LIB\fR\fR
466 .ad
467 .sp .6
468 .RS 4n
469 A hardware-specific library could not be located using the supplied
470 \fIap_id\fR.
471 .RE
473 .sp
474 .ne 2
475 .na
476 \fB\fBCFGA_NOTSUPP\fR\fR
477 .ad
478 .sp .6
479 .RS 4n
480 System configuration administration is not supported on the specified
481 attachment point.
482 .RE
484 .sp
485 .ne 2
486 .na
487 \fB\fBCFGA_OK\fR\fR
488 .ad
489 .sp .6
490 .RS 4n
491 The command completed as requested.
492 .RE
494 .sp
495 .ne 2
496 .na
497 \fB\fBCFGA_OPNOTSUPP\fR\fR
498 .ad
499 .sp .6
500 .RS 4n
501 System configuration administration operation is not supported on this
502 attachment point.
503 .RE
505 .sp
506 .ne 2
507 .na
508 \fB\fBCFGA_PRIV\fR\fR
509 .ad
510 .sp .6
511 .RS 4n
512 The caller does not have the required process privileges. For example, if
513 configuration administration is performed through a device driver, the
514 permissions on the device node would be used to control access.
515 .RE
517 .sp
518 .ne 2
519 .na
520 \fB\fBCFGA_SYSTEM_BUSY\fR\fR
521 .ad
522 .sp .6
523 .RS 4n
524 The command required a service interruption and was not completed due to a part
525 of the system that could not be quiesced.
526 .RE
528 .SH ERRORS
529 .sp
530 .LP
531 Many of the errors returned by the system configuration administration
532 functions are hardware-specific. The strings returned in \fIerrstring\fR may
533 include the following:
534 .sp
535 .ne 2
536 .na
537 \fB\fBattachment point\fR \fIap_id\fR \fBnot known\fR\fR
538 .ad
539 .sp .6
540 .RS 4n
541 The attachment point detailed in the error message does not exist.
542 .RE
544 .sp
545 .ne 2
546 .na
547 \fB\fBunknown hardware option\fR \fIoption\fR \fBfor\fR\fIoperation\fR\fR
548 .ad
549 .sp .6
550 .RS 4n
551 An unknown option was encountered in the \fIoptions\fR string.
552 .RE
554 .sp
555 .ne 2
556 .na
557 \fB\fBhardware option\fR \fIoption\fR \fBrequires a value\fR\fR
558 .ad
559 .sp .6
560 .RS 4n
561 An option in the \fIoptions\fR string should have been of the form
562 \fIoption\fR=\fIvalue\fR.
563 .RE
565 .sp
566 .ne 2
567 .na
568 \fB\fBlisting option\fR \fIlist_option\fR \fBrequires a value\fR\fR
569 .ad
570 .sp .6
571 .RS 4n
572 An option in the listopts string should have been of the form
573 \fIoption\fR=\fBvalue\fR.
574 .RE
576 .sp
577 .ne 2
578 .na
579 \fB\fBhardware option\fR \fIoption\fR \fBdoes not require a value\fR\fR
580 .ad
581 .sp .6
582 .RS 4n
583 An option in the \fIoptions\fR string should have been a simple option.
584 .RE
586 .sp
587 .ne 2
588 .na
589 \fB\fBattachment point\fR \fIap_id\fR \fBis not configured\fR\fR
590 .ad
591 .sp .6
592 .RS 4n
593 A \fIconfig_change_state\fR command to \fBCFGA_CMD_UNCONFIGURE\fR an occupant
594 was made to an attachment point whose occupant was not in the
595 \fBCFGA_STAT_CONFIGURED\fR state.
596 .RE
598 .sp
599 .ne 2
600 .na
601 \fB\fBattachment point\fR \fIap_id\fR \fBis not unconfigured\fR\fR
602 .ad
603 .sp .6
604 .RS 4n
605 A \fIconfig_change_state\fR command requiring an unconfigured occupant was made
606 to an attachment point whose occupant was not in the
607 \fBCFGA_STAT_UNCONFIGURED\fR state.
608 .RE
610 .sp
611 .ne 2
612 .na
613 \fB\fBattachment point\fR \fIap_id\fR \fBcondition not satisfactory\fR\fR
614 .ad
615 .sp .6
616 .RS 4n
617 A \fIconfig_change_state\fR command was made to an attachment point whose
618 condition prevented the operation.
619 .RE
621 .sp
622 .ne 2
623 .na
624 \fB\fBattachment point\fR \fIap_id\fR \fBin condition\fR \fIcondition\fR
625 \fBcannot be used\fR\fR
626 .ad
627 .sp .6
628 .RS 4n
629 A \fIconfig_change_state\fR operation with force indicated was directed to an
630 attachment point whose condition fails the hardware dependent test.
631 .RE
633 .SH ATTRIBUTES
634 .sp
635 .LP
636 See \fBattributes\fR(5) for descriptions of the following attributes:
637 .sp
639 .sp
640 .TS
641 box;
642 c | c
643 l | l .
644 ATTRIBUTE TYPE ATTRIBUTE VALUE
645 _
646 MT-Level Safe
647 .TE
649 .SH SEE ALSO
650 .sp
651 .LP
652 \fBcfgadm\fR(1M), \fBdevinfo\fR(1M), \fBdlopen\fR(3C), \fBdlsym\fR(3C),
653 \fBfree\fR(3C), \fBgetsubopt\fR(3C), \fBmalloc\fR(3C), \fBqsort\fR(3C),
654 \fBsetlocale\fR(3C), \fBstrcmp\fR(3C), \fBlibcfgadm\fR(3LIB),
655 \fBattributes\fR(5)
656 .SH NOTES
657 .sp
658 .LP
659 Applications using this library should be aware that the underlying
660 implementation may use system services which alter the contents of the external
661 variable \fBerrno\fR and may use file descriptor resources.
662 .sp
663 .LP
664 The following code shows the intended error processing when \fBconfig_*()\fR
665 returns a value other than \fBCFGA_OK\fR:
666 .sp
667 .in +2
668 .nf
669 void
670 emit_error(cfga_err_t cfgerrnum, char *estrp)
671 {
672 const char *ep;
673 ep = config_strerror(cfgerrnum);
674 if (ep == NULL)
675 ep = gettext("configuration administration unknown error");
676 if (estrp != NULL && *estrp != '\e0') {
677 (void) fprintf(stderr, "%s: %s\en", ep, estrp);
678 } else {
679 (void) fprintf(stderr, "%s\en", ep);
680 }
681 if (estrp != NULL)
682 free((void *)estrp);
683 }
684 .fi
685 .in -2
687 .sp
688 .LP
689 Reference should be made to the Hardware Specific Guide for details of System
690 Configuration Administration support.