crashconf(2)

NAME

crashconf() — configure system crash dumps

SYNOPSIS

#include <sys/crashconf.h>

int crashconf(

   int    operation,
   int    includeClasses,
   int    excludeClasses,
   int    deviceCount,
   char **devices,
   int   *deviceReturn

);

DESCRIPTION

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.
The concurrency mode selection. This selection is used to turn concurrency 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.

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.

Turning concurrency mode ON may result in faster dumps depending on the configuration of the dump devices.

Depending on the availability of additional memory and the configuration of dump devices, the system may fall back to non-concurrent dump mode.

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(). Using the DC_PERSISTENT operation, the dump device list can be made persistent across system reboots. Persistent dump devices information is maintained in the kernel registry services (KRS, see krs(5)).

Parameters

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.
DC_SETCONCURRENT: crashconf() will set the concurrency mode ON.
DC_SETNOCONCURRENT: crashconf() will set the concurrency mode OFF.
DC_PERSISTENT: crashconf() will mark the current dump device list as persistent. Once this is used, from the next boot onwards, system will ignore devices marked for dump using lvlnboot, vxvmboot, and /stand/system. Instead, the persistent device list is used.
DC_LEGACY_MODE: crashconf() will change dump configuration mode. From next boot onwards devices marked for dump using lvlnboot, vxvmboot, and /stand/system will be configured as dump devices during boot-up. Marking dump devices using lvlnboot, vxvmboot, and /stand/system will be obsoleted in the next HP-UX release. This operation is only provided to maintain backward compatibility for this release.
DC_REMOVE: crashconf() will remove the list of devices specified in devices from the current dump device list.

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 or character device files (legacy or persistent, see intro(7)) 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 2 GB or 4 GB of the physical disk.

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: 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

The following system memory classes have been defined as of this writing. Refer to the output of the crashconf command or to /usr/include/sys/crashconf.h for definitions of any classes added since publication. The memory page size is 4 Kb.

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

Security Restrictions

The crashconf() system call is restricted to processes owned by superusers or with the DEVOPS privilege. See privileges(5) for more information about privileged access on systems that support fine-grained privileges.

EXAMPLES

The following examples demonstrate the usage of crashconf().

Example 1: Adding a Crash Dump Device

char *device_to_add[1];

int device_return[1];

...

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, 0, DT_UNUSED, 0, NULL, NULL);

Example 6: Marking Dump Device List Persistent

crashconf(DC_PERSISTENT, 0, 0, 0, NULL, NULL);

Example 7: Removing a Crash Dump Device

char *device_to_remove[1];

int device_return[1];

...

crashconf(DC_DEVICES|DC_REMOVE, 0, 0, 1, device_to_remove, 
          device_return); 

Example 8: Setting Concurrent Dump ON, Including Kernel Code Pages

crashconf(DC_SETCONCURRENT | DC_INCLUDE, DT_KCODE, 0, NULL, NULL);

RETURN VALUE

0: Successful completion.
-1: Error. errno is set to indicate the error.
1: If DC_DEVICES is set, 1 indicates that at least one device has been configured but one or more devices failed to configure. If DC_PERSISTENT is set, 1 indicates that at least one of the dump devices is not marked persistent.

ERRORS

crashconf() fails if one or more of the following is true:

EPERM: The calling process is not owned by superuser or not privileged.
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 both DC_SETCONCURRENT and DC_SETNOCONCURRENT set.
EINVAL: operation has DC_DEVICES set, and deviceCount is less than zero or greater than DC_MAXDEVICES.
EINVAL: operation has both DC_REPLACE and DC_REMOVE set.
EINVAL: operation has both DC_LEGACY_MODE and DC_PERSISTENT set.
EIO: operation DC_LEGACY_MODE failed to save the configuration change.
EIO: operation DC_PERSISTENT failed to save the configuration change.

WARNINGS

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. It is also possible to use the -U option of the vxassist command to do the same (see vxassist(1M)).

Marking dump devices using lvlnboot, vxvmboot, and /stand/system will be obsoleted in the next HP-UX release. DC_PERSISTENT operation of crashconf() can be used to mark the dump device list as persistent.