1.\" $NetBSD: core.5,v 1.28 2014/10/27 16:21:59 wiz 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. 132Each program header describes a range 133of the virtual address space of the process. 134.Pp 135In addition, 136.Nx 137ELF core files include an ELF note section which provides additional 138information about the process. 139The first note in the note section has a note name of 140.Dq NetBSD-CORE 141and a note type of 142ELF_NOTE_NETBSD_CORE_PROCINFO (1), and contains the following 143structure: 144.Bd -literal 145struct netbsd_elfcore_procinfo { 146 /* Version 1 fields start here. */ 147 uint32_t cpi_version; /* netbsd_elfcore_procinfo version */ 148 uint32_t cpi_cpisize; /* sizeof(netbsd_elfcore_procinfo) */ 149 uint32_t cpi_signo; /* killing signal */ 150 uint32_t cpi_sigcode; /* signal code */ 151 uint32_t cpi_sigpend[4]; /* pending signals */ 152 uint32_t cpi_sigmask[4]; /* blocked signals */ 153 uint32_t cpi_sigignore[4]; /* blocked signals */ 154 uint32_t cpi_sigcatch[4]; /* blocked signals */ 155 int32_t cpi_pid; /* process ID */ 156 int32_t cpi_ppid; /* parent process ID */ 157 int32_t cpi_pgrp; /* process group ID */ 158 int32_t cpi_sid; /* session ID */ 159 uint32_t cpi_ruid; /* real user ID */ 160 uint32_t cpi_euid; /* effective user ID */ 161 uint32_t cpi_svuid; /* saved user ID */ 162 uint32_t cpi_rgid; /* real group ID */ 163 uint32_t cpi_egid; /* effective group ID */ 164 uint32_t cpi_svgid; /* saved group ID */ 165 uint32_t cpi_nlwps; /* number of LWPs */ 166 int8_t cpi_name[32]; /* copy of p->p_comm */ 167 /* Add version 2 fields below here. */ 168}; 169.Ed 170.Pp 171The fields of 172.Fa struct netbsd_elfcore_procinfo 173are as follows: 174.Bl -tag -width cpi_sigignoreXX 175.It cpi_version 176The version of this structure. 177The current version is defined by the 178.Dv NETBSD_ELFCORE_PROCINFO_VERSION 179constant. 180.It cpi_cpisize 181The size of this structure. 182.It cpi_signo 183Signal that caused the process to dump core. 184.It cpi_sigcode 185Signal-specific code, if any, corresponding to 186.Va cpi_signo . 187.It cpi_sigpend 188A mask of signals pending delivery to the process. 189This may be examined by copying it to a 190.Fa sigset_t . 191.It cpi_sigmask 192The set of signals currently blocked by the process. 193This may be examined by copying it to a 194.Fa sigset_t . 195.It cpi_sigignore 196The set of signals currently being ignored by the process. 197This may be examined by copying it to a 198.Fa sigset_t . 199.It cpi_sigcatch 200The set of signals with registers signals handlers for the process. 201This may be examined by copying it to a 202.Fa sigset_t . 203.It cpi_pid 204Process ID of the process. 205.It cpi_ppid 206Process ID of the parent process. 207.It cpi_pgrp 208Process group ID of the process. 209.It cpi_sid 210Session ID of the process. 211.It cpi_ruid 212Real user ID of the process. 213.It cpi_euid 214Effective user ID of the process. 215.It cpi_svuid 216Saved user ID of the process. 217.It cpi_rgid 218Real group ID of the process. 219.It cpi_egid 220Effective group ID of the process. 221.It cpi_svgid 222Saved group ID of the process. 223.It cpi_nlwps 224Number of kernel-visible execution contexts (LWPs) of the process. 225.It cpi_name 226Process name, copied from the p_comm field of 227.Fa struct proc . 228.El 229.Pp 230The note section also contains additional notes for each 231kernel-visible execution context of the process (LWP). 232These notes have names of the form 233.Dq NetBSD-CORE@nn 234where 235.Dq nn 236is the LWP ID of the execution context, for example: 237.Dq NetBSD-CORE@1 . 238These notes contain register and other per-execution context 239data in the same format as is used by the 240.Xr ptrace 2 241system call. 242The note types correspond to the 243.Xr ptrace 2 244request numbers that return the same data. 245For example, 246a note with a note type of PT_GETREGS would contain a 247.Fa struct reg 248with the register contents of the execution context. 249For a complete list of available 250.Xr ptrace 2 251request types for a given architecture, refer to that architecture's 252.Aq Pa machine/ptrace.h 253header file. 254.Ss A.OUT CORE FORMAT 255The core file consists of a core header followed by a number of 256segments. 257Each segment is preceded by a core segment header. 258Both the core header and core segment header are defined in 259.In sys/core.h . 260.Pp 261The core header, 262.Fa struct core , 263specifies the lengths of the core header itself and 264each of the following core segment headers to allow for any machine 265dependent alignment requirements. 266.Bd -literal 267struct core { 268 uint32_t c_midmag; /* magic, id, flags */ 269 uint16_t c_hdrsize; /* Size of this header (machdep algn) */ 270 uint16_t c_seghdrsize; /* Size of a segment header */ 271 uint32_t c_nseg; /* # of core segments */ 272 char c_name[MAXCOMLEN+1]; /* Copy of p-\*[Gt]p_comm */ 273 uint32_t c_signo; /* Killing signal */ 274 u_long c_ucode; /* Signal code */ 275 u_long c_cpusize; /* Size of machine dependent segment */ 276 u_long c_tsize; /* Size of traditional text segment */ 277 u_long c_dsize; /* Size of traditional data segment */ 278 u_long c_ssize; /* Size of traditional stack segment */ 279}; 280.Ed 281.Pp 282The fields of 283.Fa struct core 284are as follows: 285.Bl -tag -width XXXc_seghdrsize 286.It c_midmag 287Core file machine ID, magic value, and flags. 288These values may be extracted with the 289.Fn CORE_GETMID , 290.Fn CORE_GETMAGIC , 291and 292.Fn CORE_GETFLAG 293macros. 294The machine ID values are listed in 295.In sys/exec_aout.h . 296For a valid core file, the magic value in the header must be 297.Dv COREMAGIC . 298No flags are defined for the core header. 299.It c_hdrsize 300Size of this data structure. 301.It c_seghdrsize 302Size of a segment header. 303.It c_nseg 304Number of segments that follow this header. 305.It c_name 306Process name, copied from the p_comm field of 307.Fa struct proc . 308.It c_signo 309Signal that caused the process to dump core. 310.It c_ucode 311Code associated with the signal. 312.It c_cpusize 313Size of the segment containing CPU-specific information. 314This segment will have the 315.Dv CORE_CPU 316flag set. 317.It c_tsize 318Size of the segment containing the program text. 319.It c_dsize 320Size of the segment containing the program's traditional data area. 321.It c_ssize 322Size of the segment containing the program's traditional stack area. 323This segment will have the 324.Dv CORE_STACK 325flag set. 326.El 327The header is followed by 328.Fa c_nseg 329segments, each of which is preceded with a segment header, 330.Fa struct coreseg : 331.Bd -literal 332struct coreseg { 333 uint32_t c_midmag; /* magic, id, flags */ 334 u_long c_addr; /* Virtual address of segment */ 335 u_long c_size; /* Size of this segment */ 336}; 337.Ed 338.Pp 339The fields of 340.Fa struct coreseg 341are as follows: 342.Bl -tag -width XXXc_midmag 343.It c_midmag 344Core segment magic value and flags. 345These values may be extracted with the 346.Fn CORE_GETMAGIC 347and 348.Fn CORE_GETFLAG 349macros. 350The magic value in the segment header must be 351.Dv CORESEGMAGIC . 352Exactly one of the flags 353.Dv CORE_CPU , 354.Dv CORE_DATA , 355or 356.Dv CORE_STACK 357will be set to indicate the segment type. 358.It c_addr 359Virtual address of the segment in the program image. 360Meaningless if the segment type is 361.Dv CORE_CPU . 362.It c_size 363Size of the segment, not including this header. 364.El 365.Sh SEE ALSO 366.Xr gdb 1 , 367.Xr setrlimit 2 , 368.Xr sysctl 3 , 369.Xr a.out 5 , 370.Xr elf 5 , 371.Xr signal 7 , 372.Xr sysctl 8 373.Sh HISTORY 374A 375.Nm core 376file format appeared in 377.At v6 . 378The 379.Nx 380a.out core file format was introduced in 381.Nx 1.0 . 382The 383.Nx 384ELF core file format was introduced in 385.Nx 1.6 . 386.Pp 387In releases previous to 388.Nx 1.6 , 389ELF program images produced a.out-format core files. 390.Sh BUGS 391There is no standard location or name for the 392CPU-dependent data structure stored in the 393.Dv CORE_CPU 394segment. 395