Configuration Administration Library Functions
configadmin(3CFGADM)
NAME
configadmin, configchangestate, configprivatefunc,
configtest, configstat, configlist, configlistext,
configapidcmp, configunloadlibs, configstrerror - con-
figuration administration interface
SYNOPSIS
cc [ flag... ] file... -lcfgadm [ library... ]
#include
#include
cfgaerrt configchangestate(cfgacmdt statechangecmd,
int numapids, char * const *apids, const char *options,
struct cfgaconfirm *confp, struct cfgamsg *msgp,
char **errstring, cfgaflagst flags);
cfgaerrt configprivatefunc(const char *function, int numapids,
char * const *apids, const char *options,
struct cfgaconfirm *confp, msgp, char **errstring,
cfgaflagst flags);
cfgaerrt configtest(int numapids, char * const *apids,
const char *options, struct cfgamsg *msgp,
char **errstring, cfgaflagst flags);
cfgaerrt configlistext(int numapids, char * const *apids,
struct cfgalistdata **apidlist, int *nlist,
const char *options, const char *listops,
char **errstring, cfgaflagst flags);
int configapidcmp(const cfgaapidt apid1,
const cfgaapidt apid2);
void configunloadlibs(void);
const char *configstrerror(cfgaerrt cfgerrnum);
Deprecated Interfaces
The following interfaces have been deprecated and their use
is strongly discouraged:
cfgaerrt configstat(int numapids, char * const *apids,
struct cfgastatdata *buf, const char *options, char **errstring);
SunOS 5.11 Last change: 1 Sep 2004 1
Configuration Administration Library Functions
configadmin(3CFGADM)
cfgaerrt configlist(struct cfgastatdata **apidlist,
int *nlist, const char *options, char **errstring);
HARDWARE DEPENDENT LIBRARY SYNOPSIS
The configadmin 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 gen-
eric libraries. It is, however, necessary that writers of
the hardware-specific plug in libraries know what these
interfaces are.
cfgaerrt cfgachangestate(cfgacmdt statechangecmd,
const char *apid, const char *options, struct cfgaconfirm *confp,
struct cfgamsg *msgp, char **errstring, cfgaflagst flags);
cfgaerrt cfgaprivatefunc(const char *function,
const char *apid, const char *options, struct cfgaconfirm *confp,
struct cfgamsg *msgp, char **errstring, cfgaflagst flags);
cfgaerrt cfgatest(const char *apid, const char *options,
struct cfgamsg *msgp, char **errstring, cfgaflagst flags);
cfgaerrt cfgalistext(const char *apid,
struct cfgalistdata **apidlist, nlist, const char *options,
const char *listopts, char **errstring, cfgaflagst flags);
cfgaerrt cfgahelp(struct cfgamsg *msgp, const char *options,
cfgaflagst flags);
int cfgaapidcmp(const cfgaapidt apid1, const cfgaapidt apid2);
Deprecated Interfaces
The following interfaces have been deprecated and their use
is strongly discouraged:
cfgaerrt cfgastat(const char *apid, struct cfgastatdata *buf,
const char *options, char **errstring);
SunOS 5.11 Last change: 1 Sep 2004 2
Configuration Administration Library Functions
configadmin(3CFGADM)
cfgaerrt cfgalist(const char *apid,
struct cfgastatdata **apidlist, int *nlist, const char *options,
char **errstring);
DESCRIPTION
The config*() functions provide a hardware independent
interface to hardware-specific system configuration adminis-
tration 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(1M) 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 configchangestate() function performs operations that
change the state of the system configuration. The
statechangecmd argument can be one of the following:
CFGACMDINSERT, CFGACMDREMOVE, CFGACMDISCONECT,
CFGACMDCONECT, CFGACMDCONFIGURE, or
CFGACMDUNCONFIGURE. The statechangecmd CFGACMDINSERT
is used to prepare for manual insertion or to activate
automatic hardware insertion of an occupant. The
statechangecmd CFGACMDREMOVE is used to prepare for
manual removal or activate automatic hardware removal of an
occupant. The statechangecmd CFGACMDISCONECT is used
to disable normal communication to or from an occupant in a
receptacle. The statechangecmd CFGACMDCONECT is used to
enable communication to or from an occupant in a receptacle.
The statechangecmd CFGACMDCONFIGURE 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 resources by the system. The statechangecmd
CFGACMDUNCONFIGURE is used to remove the hardware
resources contained on, or attached to, an occupant from the
realm of Solaris, disallowing further use of the occupant's
hardware resources by the system.
The flags argument may contain one or both of the defined
flags, CFGAFLAGFORCE and CFGAFLAGVERBOSE. If the
CFGAFLAGFORCE flag is asserted certain safety checks will
be overridden. For example, this may not allow an occupant
SunOS 5.11 Last change: 1 Sep 2004 3
Configuration Administration Library Functions
configadmin(3CFGADM)
in the failed condition to be configured, but might allow an
occupant in the failing condition to be configured. Accep-
tance of a force is hardware dependent. If the
CFGAFLAGVERBOSE flag is asserted hardware-specific details
relating to the operation are output utilizing the cfgamsg
mechanism.
The configprivatefunc() function invokes private
hardware-specific functions.
The configtest() function is used to initiate testing of
the specified attachment point.
The numapids argument specifies the number of apids in
the apids array. The apids argument points to an array of
apids.
The apid argument points to a single apid.
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 cfgaconfirm structure referenced by confp provides a
call-back interface to get permission to proceed should the
requested operation require, for example, a noticeable ser-
vice interruption. The cfgaconfirm structure includes the
following members:
int (*confirm)(void *appdataptr, const char *message);
void *appdataptr;
The confirm() function is called with two arguments: the
generic pointer appdataptr and the message detailing what
requires confirmation. The generic pointer appdataptr is
set to the value passed in in the cfgaconfirm structure
member appdataptr and can be used in a graphical user
interface to relate the confirm function call to the con-
fig*() call. The confirm() function should return 1 to
allow the operation to proceed and 0 otherwise.
SunOS 5.11 Last change: 1 Sep 2004 4
Configuration Administration Library Functions
configadmin(3CFGADM)
The cfgamsg structure referenced by msgp provides a call-
back interface to output messages from a hardware-specific
library. In the presence of the CFGAFLAGVERBOSE flag,
these messages can be informational; otherwise they are res-
tricted to error messages. The cfgamsg structure includes
the following members:
int (*messageroutine)(void *appdataptr, const char *message);
void *appdataptr;
The messageroutine() function is called with two arguments:
the generic pointer appdataptr and the message. The generic
pointer appdataptr is set to the value passed in in the
cfgaconfirm structure member appdataptr and can be used in
a graphical user interface to relate the messageroutine()
function call to the config*() call. The messages must be
in the native language specified by the LCMESAGES 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
NUL no error message will be generated or returned. If err-
string is not NUL and no error message is generated, the
pointer referenced by errstring will be set to NUL. 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
LCMESAGES locale category; see setlocale(3C).
The configlistext() function provides the listing inter-
face. When supplied with a list of apids through the first
two arguments, it returns an array of cfgalistdatat
structures for each attachment point specified. If the first
two arguments are 0 and NUL respectively, then all attach-
ment 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
CFGAFLAGLISTAL flag through the flags argument. Storage
for the returned array of stat structures is allocated by
the configlistext() function using malloc(3C). This
storage must be freed by the caller of configlistext() by
using free(3C).
SunOS 5.11 Last change: 1 Sep 2004 5
Configuration Administration Library Functions
configadmin(3CFGADM)
The cfgalistdata structure includes the following members:
cfgalogextt aplogid; /* Attachment point logical id */
cfgaphysextt apphysid; /* Attachment point physical id */
cfgaclasst apclass; /* Attachment point class */
cfgastatt aprstate; /* Receptacle state */
cfgastatt apostate; /* Occupant state */
cfgacondt apcond; /* Attachment point condition */
cfgabusyt apbusy; /* Busy indicator */
timet apstatustime; /* Attachment point last change*/
cfgainfot apinfo; /* Miscellaneous information */
cfgatypet aptype; /* Occupant type */
The types are defined as follows:
typedef char cfgalogextt[CFGALOGEXTLEN];
typedef char cfgaphysextt[CFGAPHYSEXTLEN];
typedef char cfgaclasst[CFGACLASLEN];
typedef char cfgainfot[CFGAINFOLEN];
typedef char cfgatypet[CFGATYPELEN];
typedef enum cfgacondt;
typedef enum cfgastatt;
typedef int cfgabusyt;
typedef int cfgaflagst;
The listopts argument to configlistext() conforms to the
getsubopt(3C) syntax and is used to pass listing sub-
options. Currently, only the sub-option class=classname is
supported. This list option restricts the listing to
attachment points of class classname.
The listopts argument to cfgalistext() is reserved for
future use. Hardware-specific libraries should ignore this
argument if it is NUL. If listopts is not NUL and is not
supported by the hardware-specific library, an appropriate
error code should be returned.
The aplogid and the apphysid members give the hardware-
specific logical and physical names of the attachment point.
The apbusy memberd indicates activity is present that may
result in changes to state or condition. The apstatustime
member provides the time at which either the aprstate,
apostate, or apcond field of the attachment point last
changed. The apinfo member is available for the hardware-
specific code to provide additional information about the
SunOS 5.11 Last change: 1 Sep 2004 6
Configuration Administration Library Functions
configadmin(3CFGADM)
attachment point. The apclass member contains the attach-
ment point class (if any) for an attachment point. The
apclass member is filled in by the generic library. If the
aplogid and apphysid 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-
tospecific library.
All string members in the cfgalistdata structure are
null-terminated.
The configstat(), configlist(), cfgastat(), and
cfgalist() functions and the cfgastatdata data structure
are deprecated interfaces and are provided solely for back-
ward compatibility. Use of these interfaces is strongly
discouraged.
The configapidcmp function performs a hardware dependent
comparison on two apids, returning an equal to, less than
or greater than indication in the manner of strcmp(3C). Each
argument is either a cfgaapidt or can be a null-
terminated string. This function can be used when sorting
lists of apids, for example with qsort(3C), or when select-
ing entries from the result of a configlist function call.
The configunloadlibs function unlinks all previously
loaded hardware-specific libraries.
The configstrerror 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.
configstrerror returns NUL if cfgerrnum is out-of-range.
The cfgahelp 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 CFGAOK. See DESCRIP-
TION for details.
CFGABUSY
SunOS 5.11 Last change: 1 Sep 2004 7
Configuration Administration Library Functions
configadmin(3CFGADM)
The command was not completed due to an element of the
system configuration administration system being busy.
CFGATRINVAL
No attachment points with the specified attributes
exists
CFGAEROR
An error occurred during the processing of the requested
operation. This error code includes validation of the
command arguments by the hardware-specific code.
CFGAINSUFICIENTCONDITION
Operation failed due to attachment point condition.
CFGAINVAL
The system configuration administration operation
requested is not supported on the specified attachment
point.
CFGALIBEROR
A procedural error occurred in the library, including
failure to obtain process resources such as memory and
file descriptors.
CFGANACK
The command was not completed due to a negative ack-
nowledgement from the confp->confirm function.
CFGANOLIB
A hardware-specific library could not be located using
the supplied apid.
CFGANOTSUP
System configuration administration is not supported on
SunOS 5.11 Last change: 1 Sep 2004 8
Configuration Administration Library Functions
configadmin(3CFGADM)
the specified attachment point.
CFGAOK
The command completed as requested.
CFGAOPNOTSUP
System configuration administration operation is not
supported on this attachment point.
CFGAPRIV
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.
CFGASYSTEMBUSY
The command required a service interruption and was not
completed due to a part of the system that could not be
quiesced.
ERORS
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 apid 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.
SunOS 5.11 Last change: 1 Sep 2004 9
Configuration Administration Library Functions
configadmin(3CFGADM)
listing option listoption 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 sim-
ple option.
attachment point apid is not configured
A configchangestate command to CFGACMDUNCONFIGURE
an occupant was made to an attachment point whose occu-
pant was not in the CFGASTATCONFIGURED state.
attachment point apid is not unconfigured
A configchangestate command requiring an unconfigured
occupant was made to an attachment point whose occupant
was not in the CFGASTATUNCONFIGURED state.
attachment point apid condition not satisfactory
A configchangestate command was made to an attachment
point whose condition prevented the operation.
attachment point apid in condition condition cannot be used
A configchangestate operation with force indicated
was directed to an attachment point whose condition
fails the hardware dependent test.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.11 Last change: 1 Sep 2004 10
Configuration Administration Library Functions
configadmin(3CFGADM)
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWcsu, SUNWkvm
MT-Level Safe
SEE ALSO
cfgadm(1M), devinfo(1M), dlopen(3C), dlsym(3C), free(3C),
getsubopt(3C), malloc(3C), qsort(3C), setlocale(3C),
strcmp(3C), libcfgadm(3LIB), attributes(5)
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 CFGAOK:
void
emiterror(cfgaerrt cfgerrnum, char *estrp)
{
const char *ep;
ep = configstrerror(cfgerrnum);
if (ep == NUL)
ep = gettext("configuration administration unknown error");
if (estrp != NUL && *estrp != '\0') {
(void) fprintf(stderr, "%s: %s\n", ep, estrp);
} else {
(void) fprintf(stderr, "%s\n", ep);
}
if (estrp != NUL)
free((void *)estrp);
}
Reference should be made to the Hardware Specific Guide for
details of System Configuration Administration support.
SunOS 5.11 Last change: 1 Sep 2004 11
Configuration Administration Library Functions
configadmin(3CFGADM)
SunOS 5.11 Last change: 1 Sep 2004 12
|
