1.\" $NetBSD: core.5,v 1.25 2010/03/22 18:58:32 joerg Exp $ 2.\" 3.\" Copyright (c) 2002 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Jason R. Thorpe. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.\" Copyright (c) 1980, 1991, 1993 31.\" The Regents of the University of California. All rights reserved. 32.\" 33.\" Redistribution and use in source and binary forms, with or without 34.\" modification, are permitted provided that the following conditions 35.\" are met: 36.\" 1. Redistributions of source code must retain the above copyright 37.\" notice, this list of conditions and the following disclaimer. 38.\" 2. Redistributions in binary form must reproduce the above copyright 39.\" notice, this list of conditions and the following disclaimer in the 40.\" documentation and/or other materials provided with the distribution. 41.\" 3. Neither the name of the University nor the names of its contributors 42.\" may be used to endorse or promote products derived from this software 43.\" without specific prior written permission. 44.\" 45.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 46.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 47.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 48.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 49.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 50.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 51.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 52.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 53.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 54.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 55.\" SUCH DAMAGE. 56.\" 57.\" @(#)core.5 8.3 (Berkeley) 12/11/93 58.\" 59.Dd July 8, 2002 60.Dt CORE 5 61.Os 62.Sh NAME 63.Nm core 64.Nd memory image file format 65.Sh SYNOPSIS 66.In sys/param.h 67.Pp 68For a.out-format core files: 69.Pp 70.In sys/core.h 71.Pp 72For ELF-format core files: 73.Pp 74.In sys/exec.h 75.In sys/exec_elf.h 76.Sh DESCRIPTION 77A small number of signals which cause abnormal termination of a process 78also cause a record of the process's in-core state to be written 79to disk for later examination by one of the available debuggers 80(see 81.Xr signal 7 ) . 82.Pp 83This memory image is written to a file named from a per-process template; 84provided the terminated process had write permission, and provided the 85abnormality did not cause a system crash. 86(In this event, the decision to save the core file is arbitrary, see 87.Xr savecore 8 . ) 88The file is named from a per-process template, mapped to the sysctl 89variable 90.Em proc.\*[Lt]pid\*[Gt].corename 91(where \*[Lt]pid\*[Gt] has to be replaced by the pid in decimal format of the 92process). 93This template is either an absolute or relative path name, in which format 94characters can be used, preceded by the percent character 95.Pq Dq \&% . 96The following characters are recognized as format and substituted: 97.Bl -tag -width 4n -offset indent -compact 98.It Sy n 99The process's name 100.It Sy p 101The PID of the process (in decimal) 102.It Sy t 103The process's creation date (a la 104.Xr time 3 , 105in decimal) 106.It Sy u 107The login name, as returned by 108.Xr getlogin 2 109.El 110.Pp 111By default, the per-process template string points to the default core name 112template, which is mapped to the sysctl variable 113.Em kern.defcorename . 114Changing this value on a live system will change the core name template for 115all processes which didn't have a per-process template set. 116The default value of the default core name template is 117.Nm %n.core 118and can be changed at compile-time with the kernel configuration option 119.Cd options DEFCORENAME 120(see 121.Xr options 4 ) 122.Pp 123The per-process template string is inherited on process creation, but is reset 124to point to the default core name template on execution of a set-id binary. 125.Pp 126The maximum size of a core file is limited by 127.Xr setrlimit 2 . 128Files which would be larger than the limit are not created. 129.Ss ELF CORE FORMAT 130ELF-format core files are described by a standard ELF exec header and 131a series of ELF program headers. Each program header describes a range 132of the virtual address space of the process. 133.Pp 134In addition, 135.Nx 136ELF core files include an ELF note section which provides additional 137information about the process. The first note in the note section 138has a note name of 139.Dq NetBSD-CORE 140and a note type of 141ELF_NOTE_NETBSD_CORE_PROCINFO (1), and contains the following 142structure: 143.Bd -literal 144struct netbsd_elfcore_procinfo { 145 /* Version 1 fields start here. */ 146 uint32_t cpi_version; /* netbsd_elfcore_procinfo version */ 147 uint32_t cpi_cpisize; /* sizeof(netbsd_elfcore_procinfo) */ 148 uint32_t cpi_signo; /* killing signal */ 149 uint32_t cpi_sigcode; /* signal code */ 150 uint32_t cpi_sigpend[4]; /* pending signals */ 151 uint32_t cpi_sigmask[4]; /* blocked signals */ 152 uint32_t cpi_sigignore[4]; /* blocked signals */ 153 uint32_t cpi_sigcatch[4]; /* blocked signals */ 154 int32_t cpi_pid; /* process ID */ 155 int32_t cpi_ppid; /* parent process ID */ 156 int32_t cpi_pgrp; /* process group ID */ 157 int32_t cpi_sid; /* session ID */ 158 uint32_t cpi_ruid; /* real user ID */ 159 uint32_t cpi_euid; /* effective user ID */ 160 uint32_t cpi_svuid; /* saved user ID */ 161 uint32_t cpi_rgid; /* real group ID */ 162 uint32_t cpi_egid; /* effective group ID */ 163 uint32_t cpi_svgid; /* saved group ID */ 164 uint32_t cpi_nlwps; /* number of LWPs */ 165 int8_t cpi_name[32]; /* copy of p->p_comm */ 166 /* Add version 2 fields below here. */ 167}; 168.Ed 169.Pp 170The fields of 171.Fa struct netbsd_elfcore_procinfo 172are as follows: 173.Bl -tag -width cpi_sigignoreXX 174.It cpi_version 175The version of this structure. The current version is defined by 176the NETBSD_ELFCORE_PROCINFO_VERSION constant. 177.It cpi_cpisize 178The size of this structure. 179.It cpi_signo 180Signal that caused the process to dump core. 181.It cpi_sigcode 182Signal-specific code, if any, corresponding to 183.Va cpi_signo . 184.It cpi_sigpend 185A mask of signals pending delivery to the process. This may be 186examined by copying it to a 187.Fa sigset_t . 188.It cpi_sigmask 189The set of signals currently blocked by the process. This may be 190examined by copying it to a 191.Fa sigset_t . 192.It cpi_sigignore 193The set of signals currently being ignored by the process. This may be 194examined by copying it to a 195.Fa sigset_t . 196.It cpi_sigcatch 197The set of signals with registers signals handlers for the process. This 198may be examined by copying it to a 199.Fa sigset_t . 200.It cpi_pid 201Process ID of the process. 202.It cpi_ppid 203Process ID of the parent process. 204.It cpi_pgrp 205Process group ID of the process. 206.It cpi_sid 207Session ID of the process. 208.It cpi_ruid 209Real user ID of the process. 210.It cpi_euid 211Effective user ID of the process. 212.It cpi_svuid 213Saved user ID of the process. 214.It cpi_rgid 215Real group ID of the process. 216.It cpi_egid 217Effective group ID of the process. 218.It cpi_svgid 219Saved group ID of the process. 220.It cpi_nlwps 221Number of kernel-visible execution contexts (LWPs) of the process. 222.It cpi_name 223Process name, copied from the p_comm field of 224.Fa struct proc . 225.El 226.Pp 227The note section also contains additional notes for each 228kernel-visible execution context of the process (LWP). 229These notes have names of the form 230.Dq NetBSD-CORE@nn 231where 232.Dq nn 233is the LWP ID of the execution context, for example: 234.Dq NetBSD-CORE@1 . 235These notes contain register and other per-execution context 236data in the same format as is used by the 237.Xr ptrace 2 238system call. The note types correspond to the 239.Xr ptrace 2 240request numbers that return the same data. For example, 241a note with a note type of PT_GETREGS would contain a 242.Fa struct reg 243with the register contents of the execution context. 244For a complete list of available 245.Xr ptrace 2 246request types for a given architecture, refer to that architecture's 247.Pa \*[Lt]machine/ptrace.h\*[Gt] 248header file. 249.Ss A.OUT CORE FORMAT 250.Pp 251The core file consists of a core header followed by a number of 252segments. Each segment is preceded by a core segment header. 253Both the core header and core segment header are defined in 254.In sys/core.h . 255.Pp 256The core header, 257.Fa struct core , 258specifies the lengths of the core header itself and 259each of the following core segment headers to allow for any machine 260dependent alignment requirements. 261.Bd -literal 262struct core { 263 uint32_t c_midmag; /* magic, id, flags */ 264 uint16_t c_hdrsize; /* Size of this header (machdep algn) */ 265 uint16_t c_seghdrsize; /* Size of a segment header */ 266 uint32_t c_nseg; /* # of core segments */ 267 char c_name[MAXCOMLEN+1]; /* Copy of p-\*[Gt]p_comm */ 268 uint32_t c_signo; /* Killing signal */ 269 u_long c_ucode; /* Signal code */ 270 u_long c_cpusize; /* Size of machine dependent segment */ 271 u_long c_tsize; /* Size of traditional text segment */ 272 u_long c_dsize; /* Size of traditional data segment */ 273 u_long c_ssize; /* Size of traditional stack segment */ 274}; 275.Ed 276.Pp 277The fields of 278.Fa struct core 279are as follows: 280.Bl -tag -width XXXc_seghdrsize 281.It c_midmag 282Core file machine ID, magic value, and flags. 283These values may be extracted with the 284.Fn CORE_GETMID , 285.Fn CORE_GETMAGIC , 286and 287.Fn CORE_GETFLAG 288macros. The machine ID values are listed in 289.In sys/exec_aout.h . 290For a valid core file, the magic value in the header must be 291.Dv COREMAGIC . 292No flags are defined for the core header. 293.It c_hdrsize 294Size of this data structure. 295.It c_seghdrsize 296Size of a segment header. 297.It c_nseg 298Number of segments that follow this header. 299.It c_name 300Process name, copied from the p_comm field of 301.Fa struct proc . 302.It c_signo 303Signal that caused the process to dump core. 304.It c_ucode 305Code associated with the signal. 306.It c_cpusize 307Size of the segment containing CPU-specific information. 308This segment will have the 309.Dv CORE_CPU 310flag set. 311.It c_tsize 312Size of the segment containing the program text. 313.It c_dsize 314Size of the segment containing the program's traditional data area. 315.It c_ssize 316Size of the segment containing the program's traditional stack area. 317This segment will have the 318.Dv CORE_STACK 319flag set. 320.El 321The header is followed by 322.Fa c_nseg 323segments, each of which is preceded with a segment header, 324.Fa struct coreseg : 325.Bd -literal 326struct coreseg { 327 uint32_t c_midmag; /* magic, id, flags */ 328 u_long c_addr; /* Virtual address of segment */ 329 u_long c_size; /* Size of this segment */ 330}; 331.Ed 332.Pp 333The fields of 334.Fa struct coreseg 335are as follows: 336.Bl -tag -width XXXc_midmag 337.It c_midmag 338Core segment magic value and flags. 339These values may be extracted with the 340.Fn CORE_GETMAGIC 341and 342.Fn CORE_GETFLAG 343macros. 344The magic value in the segment header must be 345.Dv CORESEGMAGIC . 346Exactly one of the flags 347.Dv CORE_CPU , 348.Dv CORE_DATA , 349or 350.Dv CORE_STACK 351will be set to indicate the segment type. 352.It c_addr 353Virtual address of the segment in the program image. 354Meaningless if the segment type is 355.Dv CORE_CPU . 356.It c_size 357Size of the segment, not including this header. 358.El 359.Sh SEE ALSO 360.Xr a.out 5 , 361.Xr elf 5 , 362.Xr gdb 1 , 363.Xr setrlimit 2 , 364.Xr sysctl 3 , 365.Xr signal 7 , 366.Xr sysctl 8 367.Sh HISTORY 368A 369.Nm core 370file format appeared in 371.At v6 . 372The 373.Nx 374a.out core file format was introduced in 375.Nx 1.0 . 376The 377.Nx 378ELF core file format was introduced in 379.Nx 1.6 . 380.Pp 381In releases previous to 382.Nx 1.6 , 383ELF program images produced a.out-format core files. 384.Sh BUGS 385There is no standard location or name for the 386CPU-dependent data structure stored in the 387.Dv CORE_CPU 388segment. 389