share/man/man5/core.5

   1 .\"     $OpenBSD: core.5,v 1.14 2012/08/30 15:57:13 deraadt Exp $
   2 .\"     $NetBSD: core.5,v 1.4 1994/11/30 19:31:11 jtc Exp $
   3 .\"
   4 .\" Copyright (c) 1980, 1991, 1993
   5 .\"     The Regents of the University of California.  All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\" 3. Neither the name of the University nor the names of its contributors
  16 .\"    may be used to endorse or promote products derived from this software
  17 .\"    without specific prior written permission.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  22 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  23 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  28 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  29 .\" SUCH DAMAGE.
  30 .\"
  31 .\"     @(#)core.5      8.3 (Berkeley) 12/11/93
  32 .\"
  33 .Dd $Mdocdate: August 30 2012 $
  34 .Dt CORE 5
  35 .Os
  36 .Sh NAME
  37 .Nm core
  38 .Nd memory image file format
  39 .Sh SYNOPSIS
  40 .Fd #include <sys/param.h>
  41 .Fd #include <sys/core.h>
  42 .Sh DESCRIPTION
  43 A small number of signals which cause abnormal termination of a process
  44 also cause a record of the process's in-core state to be written
  45 to disk for later examination by one of the available debuggers (see
  46 .Xr sigaction 2 ) .
  47 This memory image is written to a file named
  48 .Pa programname.core
  49 in the working directory, provided the terminated process had write
  50 permission in the directory, and provided the abnormality did not cause
  51 a system crash.
  52 (In this event, the decision to save the core file is arbitrary, see
  53 .Xr savecore 8 . )
  54 .Pp
  55 The maximum size of a
  56 .Pa programname.core
  57 file is limited by
  58 .Xr setrlimit 2 .
  59 Files which would be larger than the limit are not created.
  60 .Pp
  61 The
  62 .Pa programname.core
  63 file consists of the u-area, whose size (in pages) is defined by the
  64 .Dv UPAGES
  65 manifest in the
  66 .Aq Pa machine/param.h
  67 file.
  68 The u-area starts with a
  69 .Fa user
  70 structure as given in
  71 .Aq Pa sys/user.h .
  72 The remainder of the
  73 .Pa programname.core
  74 file consists of the data pages followed by the stack pages of the
  75 process image.
  76 The amount of data space image in the
  77 .Pa programname.core
  78 file is given (in pages) by the variable
  79 .Fa u_dsize
  80 in the u-area.
  81 The amount of stack image in the core file is given (in pages) by the variable
  82 .Fa u_ssize
  83 in the u-area.
  84 The size of a
  85 .Dq page
  86 is given by the constant
  87 .Dv PAGE_SIZE ,
  88 defined in
  89 .Aq Pa machine/param.h .
  90 The
  91 .Fa user
  92 structure is defined as:
  93 .Bd -unfilled -offset indent
  94 struct  user {
  95         struct  pcb u_pcb;
  96
  97         struct  pstats u_stats;
  98
  99         /*
 100          * Remaining fields only for core dump and/or ptrace--
 101          * not valid at other times!
 102          */
 103         struct  kinfo_proc u_kproc;
 104         struct  md_coredump u_md;
 105 };
 106 .Ed
 107 .Pp
 108 .Fa md_coredump
 109 is defined in the header file
 110 .Aq Pa machine/pcb.h .
 111 .Pp
 112 The on-disk core file consists of a header followed by a number of segments.
 113 Each segment is preceded by a
 114 .Fa coreseg
 115 structure giving the segment's type,
 116 the virtual address where the bits resided in process address space
 117 and the size of the segment.
 118 .Pp
 119 The core header specifies the lengths of the core header itself and
 120 each of the following core segment headers to allow for any machine
 121 dependent alignment requirements.
 122 .Bd -unfilled -offset indent
 123 struct coreseg {
 124         u_int32_t c_midmag;             /* magic, id, flags */
 125         u_long  c_addr;         /* Virtual address of segment */
 126         u_long  c_size;         /* Size of this segment */
 127 };
 128 .Ed
 129 .Bd -unfilled -offset indent
 130 struct core {
 131         u_int32_t c_midmag;             /* magic, id, flags */
 132         u_int16_t c_hdrsize;   /* Size of this header (machdep algn) */
 133         u_int16_t c_seghdrsize; /* Size of a segment header */
 134         u_int32_t c_nseg;               /* # of core segments */
 135         char    c_name[MAXCOMLEN+1];    /* Copy of p->p_comm */
 136         u_int32_t c_signo;              /* Killing signal */
 137         u_long  c_ucode;                /* Hmm ? */
 138         u_long  c_cpusize;      /* Size of machine dependent segment */
 139         u_long  c_tsize;                /* Size of traditional text segment */
 140         u_long  c_dsize;                /* Size of traditional data segment */
 141         u_long  c_ssize;                /* Size of traditional stack segment */
 142 };
 143 .Ed
 144 .Pp
 145 The core structure's
 146 .Fa c_midmag field
 147 is an a.out midmag number with a
 148 .Dv COREMAGIC
 149 magic number (see
 150 .Xr a.out 5 )
 151 and flags from the following list:
 152 .Bd -unfilled -offset indent
 153 #define CORE_CPU        1
 154 #define CORE_DATA       2
 155 #define CORE_STACK      4
 156 .Ed
 157 .Sh SEE ALSO
 158 .Xr gdb 1 ,
 159 .Xr setrlimit 2 ,
 160 .Xr sigaction 2 ,
 161 .Xr sysctl 3
 162 .Sh HISTORY
 163 A
 164 .Nm
 165 file format appeared in
 166 .At v3 .
 167 .Sh CAVEATS
 168 Programs with their set-user-ID bit set will not dump core,
 169 to prevent sensitive information from inadvertently ending up on disk.
 170 See
 171 .Li kern.nosuidcoredump
 172 in
 173 .Xr sysctl 3
 174 for more information.