crashconf(2) crashconf(2)
NAME [Toc] [Back]
crashconf() - configure system crash dumps
SYNOPSIS [Toc] [Back]
#include <sys/crashconf.h>
int crashconf(
int operation,
int includeClasses,
int excludeClasses,
int deviceCount,
char **devices,
int *deviceReturn
);
DESCRIPTION [Toc] [Back]
crashconf() changes the current system crash dump configuration. The
crash dump configuration consists of:
+ The crash dump device list. This list identifies all devices that
can be used to store a crash dump. The devices are used in reverse
order, last specified to first.
+ The included class list. This list identifies all system memory
classes that must be included in any crash dump.
+ The excluded class list. This list identifies all system memory
classes that should not be included in a crash dump.
+ The compression mode selection. This selection is used to turn
compression, ON or OFF, before dumping.
Most system memory classes are in neither the included class list nor
the excluded class list. Instead, the system determines whether or
not to dump those classes of memory based on the type of crash that
occurs.
Note the system operator may request a full crash dump at the time the
dump is taken. In this case, a full dump will be performed regardless
of the contents of the excluded class list.
Turning compression mode ON will result in smaller and faster dumps.
Copying of compressed dump from the dump device over to the filesystem
will also be faster using savecrash(1M).
Since compressed dump requires additional processors and memory to do
the compression, the system may fall back on uncompressed dump if it
is not able to identify the processing resources required to do
compressed dump after a system crash.
Hewlett-Packard Company - 1 - HP-UX 11i Version 2: Sep 2004
crashconf(2) crashconf(2)
Configuration changes made using crashconf() take effect immediately
and remain in effect until the next system reboot, or until changed
with a subsequent call to crashconf().
Parameters [Toc] [Back]
operation is a bitmask specifying what crashconf() should do. It must
have at least one of the following flags set:
DC_INCLUDE crashconf() will change the contents of the
included class list. The includeClasses
parameter is valid.
DC_EXCLUDE crashconf() will change the contents of the
excluded class list. The excludeClasses
parameter is valid.
DC_DEVICES crashconf() will change the contents of the
crash dump device list. The deviceCount,
devices and deviceReturn parameters are valid.
DC_SETCOMPRESS crashconf() will set the compression mode ON.
DC_SETNOCOMPRESS crashconf() will set the compression mode OFF.
operation may also have the following flag set:
DC_REPLACE Changes to any of the lists will replace the
current contents of those lists. Without this
flag, changes will add to the current contents
of those lists.
includeClasses is a bitmask of classes that must be dumped. If it is
set to DT_ALL, all dumps will be full dumps. Other allowed values are
described under Classes, below.
excludeClasses is a bitmask of classes that may not be dumped unless a
full dump is required (due to the cause of the dump, or by explicit
operator request). If it is set to DT_ALL, dumps will be disabled.
Other allowed values are described under Classes, below.
devices is an array of deviceCount pathnames of block device files for
crash dump devices. To be valid, a device must be accessible and must
not contain a file system. Where LVM partitions are in use, the
device number must be for a partition, not the physical disk that
contains it, and must represent a partition that is strictly
contiguous on the physical disk. (LVM bad-block reallocation, and
striping features may not be in use on the partition.) Depending on
the disk type, the dump space may be restricted to the first 2GB or
4GB of the physical disk.
Hewlett-Packard Company - 2 - HP-UX 11i Version 2: Sep 2004
crashconf(2) crashconf(2)
deviceReturn is an array of deviceCount integers for returning the
results of attempting to configure the corresponding device from the
devices array. Upon return, each element is set to a numeric value
indicating the result of configuring the corresponding device as
follows:
0 Successfully configured the corresponding device as a
dump device.
< 0 Failed to configure the corresponding device as a dump
device. The absolute value of the returned number can be
used as an index into an array of error messages. The
error message strings are defined in CCERR_STRINGS (see
below).
> 0 Warning, The corresponding device has been configured but
there is one or more notes or warnings associated with
the device. The returned value is a bitmap of warnings.
the warning message strings are defined in CCWARN_STRINGS
(see below).
Any parameters which are not used for the given operation should be
set to zero. Note that both devices and deviceReturn must be
specified if DC_DEVICES is specified.
Classes [Toc] [Back]
The following system memory classes have been defined as of this
writing. Refer to the output of crashconf(1M) or to
/usr/include/sys/crashconf.h for definitions of any classes added
since publication. The memory page size is 4Kb.
DT_UNUSED Unused physical memory pages
DT_KCODE Kernel code pages
DT_BCACHE Buffer cache data pages
DT_KSDATA Kernel static data pages
DT_KDDATA Kernel dynamic data pages
DT_FSDATA File system metadata pages
DT_USTACK User process stack pages
DT_SUPERPG Unused Superpage pool pages
DT_USERPG User process pages
EXAMPLES [Toc] [Back]
The following examples demonstrate the usage of crashconf().
Example 1: Adding a Crash Dump Device
char *device_to_add[1];
int device_return[1];
...
Hewlett-Packard Company - 3 - HP-UX 11i Version 2: Sep 2004
crashconf(2) crashconf(2)
crashconf(DC_DEVICES, 0, 0, 1, device_to_add, device_return);
Example 2: Force Dumping of Buffer Cache
crashconf(DC_INCLUDE, DT_BCACHE, 0, 0, NULL, NULL);
Example 3: Disable Dumps
crashconf(DC_EXCLUDE | DC_REPLACE, 0, DT_ALL, 0, NULL, NULL);
Example 4: Using CCERR_STRINGS and CCWARN_STRINGS
Assume only one device, devices[0], is being added to the dump
configuration. The following code will check the device_return[0]
value and print corresponding error or warning messages.
char *ccerrs[] = {
CCERR_STRINGS
};
int num_ccerrs = sizeof(ccerrs)/sizeof(*ccerrs);
char *ccwarns[] = {
CCWARN_STRINGS
};
int num_ccwarns = sizeof(ccwarns)/sizeof(*ccwarns);
char *device_to_add[1];
int device_return[1];
...
crashconf(DC_DEVICES, 0, 0, 1, device_to_add, device_return);
if (device_return[0] < 0) {
if (device_return[0] > -num_ccerrs)
fprintf(stderr, "%s: error: %s", device_to_add[0],
ccerrs[-device_return[0]]);
} else if (device_return[0] > 0) {
int warn_num;
for (warn_num = 0; warn_num < NUM_CCWARNS; warn_num++)
if (device_return[0] & (1 << warn_num))
fprintf(stderr,"%s: warning: %s",
device_to_add[0], ccwarns[warn_num]);
}
Example 5: Setting Compressed Dump ON, Excluding Unused Pages
crashconf(DC_SETCOMPRESS | DC_EXCLUDE, DT_UNUSED, 0, NULL, NULL);
RETURN VALUE [Toc] [Back]
Upon successful completion, zero is returned. Otherwise, a value of
-1 is returned and errno is set to indicate the error. If DC_DEVICES
is set, a one (1) may be returned to indicate that at least one device
has been configured but one or more devices failed to configure.
ERRORS [Toc] [Back]
crashconf() fails if one or more of the following is true:
[EPERM] The calling process does not have appropriate
privileges.
Hewlett-Packard Company - 4 - HP-UX 11i Version 2: Sep 2004
crashconf(2) crashconf(2)
[EINVAL] operation does not have at least one of
DC_INCLUDE, DC_EXCLUDE, DC_SETCOMPRESS,
DC_SETNOCOMPRESS, or DC_DEVICES set.
[EINVAL] operation has both DC_INCLUDE and DC_EXCLUDE set,
and the same class (bit) is specified in both
includeClasses and excludeClasses.
[EINVAL] operation has both DC_SETCOMPRESS and
DC_SETNOCOMPRESS set.
[EINVAL] operation has DC_DEVICES set, and deviceCount is
less than zero or greater than DC_MAXDEVICES.
WARNINGS [Toc] [Back]
On systems running VxVM 3.5, the swap volumes to be configured for
system crash dumps should be created with the usage type as swap
during the creation of the swap volume. Not doing so will cause dump
corruption. You could use the -U option of vxassist(1M) to do the
same.
SEE ALSO [Toc] [Back]
crashconf(1M), vxassist(1M), pstat_getcrashinfo(2),
pstat_getcrashdev(2).
Hewlett-Packard Company - 5 - HP-UX 11i Version 2: Sep 2004 [ Back ] |
