unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (HP-UX-11.11)
Page:
Section:
Apropos / Subsearch:
optional field



 crashconf(2)							crashconf(2)




 NAME
      crashconf() - configure system crash dumps

 SYNOPSIS
      #include <&lt&lt&lt;sys/crashconf.h>&gt&gt&gt;

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

      +	   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.

      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.

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





 Hewlett-Packard Company	    - 1 -   HP-UX Release 11i: November 2000






 crashconf(2)							crashconf(2)




	   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.

      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.

      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.

	   <&lt&lt&lt; 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).

	   >&gt&gt&gt; 0	   Warning, The corresponding device has been configured but
		   there is one or more notes or warnings associated with



 Hewlett-Packard Company	    - 2 -   HP-UX Release 11i: November 2000






 crashconf(2)							crashconf(2)




		   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 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_UAREA	   U-Area pages
	   DT_USERPG	   User process pages

 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);



 Hewlett-Packard Company	    - 3 -   HP-UX Release 11i: November 2000






 crashconf(2)							crashconf(2)




	   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] <&lt&lt&lt; 0) {
	       if (device_return[0] >&gt&gt&gt; -num_ccerrs)
		   fprintf(stderr, "%s: error: %s", device_to_add[0],
			   ccerrs[-device_return[0]]);
	   } else if (device_return[0] >&gt&gt&gt; 0) {
	       int warn_num;
		for (warn_num = 0; warn_num <&lt&lt&lt; NUM_CCWARNS; warn_num++)
		   if (device_return[0] &&amp&amp&amp; (1 <&lt&lt&lt;<&lt&lt&lt; warn_num))
		       fprintf(stderr,"%s: warning: %s",
			       device_to_add[0], ccwarns[warn_num]);
	   }

 RETURN VALUE
      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
      crashconf() fails if one or more of the following is true:

	   [EPERM]	  The calling process does not have appropriate
			  privileges.

	   [EINVAL]	  operation does not have at least one of
			  DC_INCLUDE, DC_EXCLUDE, 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 DC_DEVICES set, and deviceCount is
			  less than zero or greater than DC_MAXDEVICES.

 SEE ALSO
      crashconf(1M), pstat_getcrashinfo(2), pstat_getcrashdev(2).










 Hewlett-Packard Company	    - 4 -   HP-UX Release 11i: November 2000