lib/libkvm/kvm_dump.3

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