1config_admin(3CFGCAoDnMf)iguration Administration Library Functcioonnfsig_admin(3CFGADM)
2
3
4

NAME

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

SYNOPSIS

12       cc [ flag... ] file... -lcfgadm [ library... ]
13       #include <config_admin.h>
14       #include <sys/param.h>
15
16       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
21
22       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
27
28       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
32
33       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
38
39       int config_ap_id_cmp(const cfga_ap_id_t ap_id1,
40            const cfga_ap_id_t ap_id2);
41
42
43       void config_unload_libs(void);
44
45
46       const char *config_strerror(cfga_err_t cfgerrnum);
47
48
49   Deprecated Interfaces
50       The following interfaces have been deprecated and their use is strongly
51       discouraged:
52
53       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
56
57       cfga_err_t config_list(struct cfga_stat_data **ap_id_list,
58             int *nlist, const char *options, char **errstring);
59
60

HARDWARE DEPENDENT LIBRARY SYNOPSIS

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
71       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
75
76       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
80
81       cfga_err_t cfga_test(const char *ap_id, const char *options,
82             struct cfga_msg *msgp, char **errstring, cfga_flags_t flags);
83
84
85       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
89
90       cfga_err_t cfga_help(struct cfga_msg *msgp, const char *options,
91             cfga_flags_t flags);
92
93
94       int cfga_ap_id_cmp(const cfga_ap_id_t ap_id1, const cfga_ap_id_t ap_id2);
95
96
97   Deprecated Interfaces
98       The following interfaces have been deprecated and their use is strongly
99       discouraged:
100
101       cfga_err_t cfga_stat(const char *ap_id, struct cfga_stat_data *buf,
102            const char *options, char **errstring);
103
104
105       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
109

DESCRIPTION

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
117
118       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
125
126       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
145
146       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
155
156       The config_private_func() function  invokes  private  hardware-specific
157       functions.
158
159
160       The config_test() function is used to initiate testing of the specified
161       attachment point.
162
163
164       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
167
168       The ap_id argument points to a single ap_id.
169
170
171       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
176
177       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
182         int  (*confirm)(void *appdata_ptr, const char *message);
183         void *appdata_ptr;
184
185
186
187       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
195
196       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
202         int (*message_routine)(void *appdata_ptr, const char *message);
203         void *appdata_ptr;
204
205
206
207       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
215
216       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
227
228       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
240
241       The cfga_list_data structure includes the following members:
242
243         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
254
255
256       The types are defined as follows:
257
258         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
268
269
270       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
275
276       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
281
282       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
296
297       All string members in the cfga_list_data structure are null-terminated.
298
299
300       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
305
306       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
313
314       The config_unload_libs function unlinks all previously loaded hardware-
315       specific libraries.
316
317
318       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
323
324       The cfga_help function can be used  request  that  a  hardware-specific
325       library output it's localized help message.
326

RETURN VALUES

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
332       CFGA_BUSY
333
334           The  command was not completed due to an element of the system con‐
335           figuration administration system being busy.
336
337
338       CFGA_ATTR_INVAL
339
340           No attachment points with the specified attributes exists
341
342
343       CFGA_ERROR
344
345           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
349
350       CFGA_INSUFFICIENT_CONDITION
351
352           Operation failed due to attachment point condition.
353
354
355       CFGA_INVAL
356
357           The system configuration administration operation requested is  not
358           supported on the specified attachment point.
359
360
361       CFGA_LIB_ERROR
362
363           A  procedural  error  occurred in the library, including failure to
364           obtain process resources such as memory and file descriptors.
365
366
367       CFGA_NACK
368
369           The command was not completed due  to  a  negative  acknowledgement
370           from the confp->confirm function.
371
372
373       CFGA_NO_LIB
374
375           A hardware-specific library could not be located using the supplied
376           ap_id.
377
378
379       CFGA_NOTSUPP
380
381           System configuration administration is not supported on the  speci‐
382           fied attachment point.
383
384
385       CFGA_OK
386
387           The command completed as requested.
388
389
390       CFGA_OPNOTSUPP
391
392           System  configuration  administration operation is not supported on
393           this attachment point.
394
395
396       CFGA_PRIV
397
398           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
403
404       CFGA_SYSTEM_BUSY
405
406           The  command  required a service interruption and was not completed
407           due to a part of the system that could not be quiesced.
408
409

ERRORS

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
415       attachment point ap_id not known
416
417           The attachment point detailed in the error message does not exist.
418
419
420       unknown hardware option option foroperation
421
422           An unknown option was encountered in the options string.
423
424
425       hardware option option requires a value
426
427           An option in the options  string  should  have  been  of  the  form
428           option=value.
429
430
431       listing option list_option requires a value
432
433           An  option  in  the  listopts string should  have  been of the form
434           option=value.
435
436
437       hardware option option does not require a value
438
439           An option in the options string should have been a simple option.
440
441
442       attachment point ap_id is not configured
443
444           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
448
449       attachment point ap_id is not unconfigured
450
451           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
455
456       attachment point ap_id condition not satisfactory
457
458           A config_change_state command was  made  to   an  attachment  point
459           whose condition prevented the operation.
460
461
462       attachment point ap_id in condition condition cannot be used
463
464           A   config_change_state operation with force indicated was directed
465           to an attachment point whose condition fails the hardware dependent
466           test.
467
468

ATTRIBUTES

470       See  attributes(5) for descriptions of the following attributes:
471
472
473
474
475       ┌─────────────────────────────┬─────────────────────────────┐
476       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
477       ├─────────────────────────────┼─────────────────────────────┤
478       │Availability                 │SUNWcsu, SUNWkvm             │
479       ├─────────────────────────────┼─────────────────────────────┤
480       │MT-Level                     │Safe                         │
481       └─────────────────────────────┴─────────────────────────────┘
482

SEE ALSO

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

NOTES

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
493
494       The  following code shows the intended error processing when config_*()
495       returns a value other than CFGA_OK:
496
497         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
513
514
515       Reference should be made to the Hardware Specific Guide for details  of
516       System Configuration Administration support.
517
518
519
520SunOS 5.11                        1 Sep 2004             config_admin(3CFGADM)
Impressum