lib/libkvm/kvm_dump.3

   1 .\"     $NetBSD: kvm_dump.3,v 1.12 2003/04/16 13:35:06 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 1996 Leo Weppelman
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgement:
  16 .\"     This product includes software developed by Leo Weppelman.
  17 .\" 4. Neither the name of the University nor the names of its contributors
  18 .\"    may be used to endorse or promote products derived from this software
  19 .\"    without specific prior written permission.
  20 .\"
  21 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  22 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  23 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  24 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  25 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  26 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  27 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  28 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  29 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  30 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  31 .\"
  32 .\"
  33 .Dd March 17, 1996
  34 .Dt KVM_DUMP 3
  35 .Os
  36 .Sh NAME
  37 .Nm kvm_dump_mkheader ,
  38 .Nm kvm_dump_wrtheader ,
  39 .Nm kvm_dump_inval
  40 .Nd crash dump support functions
  41 .Sh LIBRARY
  42 .Lb libkvm
  43 .Sh SYNOPSIS
  44 .In kvm.h
  45 .br
  46 .Ft int
  47 .Fn kvm_dump_mkheader "kvm_t *kd" "off_t dump_off"
  48 .Ft int
  49 .Fn kvm_dump_wrtheader "kvm_t *kd" "FILE *fp" "int dumpsize"
  50 .Ft int
  51 .Fn kvm_dump_inval "kvm_t *kd"
  52 .Sh DESCRIPTION
  53 First note that the functions described here were designed to be used by
  54 .Xr savecore 8 .
  55 .Pp
  56 The function
  57 .Fn kvm_dump_mkheader
  58 checks if the physical memory file associated with
  59 .Fa kd
  60 contains a valid crash dump header as generated by a dumping kernel.
  61 When a valid header is found,
  62 .Fn kvm_dump_mkheader
  63 initializes the internal kvm data structures as if a crash dump generated by
  64 the
  65 .Xr savecore 8
  66 program was opened.
  67 This has the intentional side effect of enabling the
  68 address translation machinery.
  69 .Pp
  70 A call to
  71 .Fn kvm_dump_mkheader
  72 will most likely be followed by a call to
  73 .Fn kvm_dump_wrtheader .
  74 This function takes care of generating the generic header, the CORE_CPU
  75 section and the section header of the CORE_DATA section.
  76 The data is written to the file pointed at by
  77 .Fa fp .
  78 The
  79 .Fa dumpsize
  80 argument is only used to properly the set the segment size of the CORE_DATA
  81 section.
  82 Note that this function assumes that
  83 .Fa fp
  84 is positioned at file location 0.
  85 This function will not seek and therefore allows
  86 .Fa fp
  87 to be a file pointer obtained by
  88 .Fn zopen .
  89 .Pp
  90 The
  91 .Fn kvm_dump_inval
  92 function clears the magic number in the physical memory file associated with
  93 .Fa kd .
  94 The address translations must be enabled for this to work (thus assuming
  95 that
  96 .Fn kvm_dump_mkheader
  97 was called earlier in the sequence).
  98 .Sh RETURN VALUES
  99 All functions except
 100 .Fn kvm_dump_mkheader
 101 return 0 on success, -1 on failure.
 102 The function
 103 .Fn kvm_dump_mkheader
 104 returns the size of the headers present before the actual dumpdata starts.
 105 If no valid headers were found but no fatal errors occurred, 0 is returned.
 106 On fatal errors the return value is -1.
 107 .Pp
 108 In the case of failure,
 109 .Xr kvm_geterr 3
 110 can be used to retrieve the cause of the error.
 111 .Sh SEE ALSO
 112 .Xr kvm 3 ,
 113 .Xr kvm_open 3
 114 .Sh HISTORY
 115 These functions first appeared in
 116 .Nx 1.2 .