1.\" $NetBSD: core.5,v 1.33 2019/12/06 18:03:49 kamil 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 December 6, 2019 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.<pid>.corename 91(where <pid> 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 142.Dv ELF_NOTE_NETBSD_CORE_PROCINFO ( 1 ) , 143and contains the following 144structure: 145.Bd -literal 146struct netbsd_elfcore_procinfo { 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 int32_t cpi_siglwp; /* LWP target of killing signal */ 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.It cpi_siglwp 229LWP target of killing signal. 230.El 231.Pp 232The second note with name 233.Dq NetBSD-CORE 234is a note type of 235.Dv ELF_NOTE_NETBSD_CORE_AUXV ( 2 ) , 236and contains an array of AuxInfo structures. 237.Pp 238The note section also contains additional notes for each 239kernel-visible execution context of the process (LWP). 240These notes have names of the form 241.Dq NetBSD-CORE@nn 242where 243.Dq nn 244is the LWP ID of the execution context, for example: 245.Dq NetBSD-CORE@1 . 246These notes contain register and other per-execution context 247data in the same format as is used by the 248.Xr ptrace 2 249system call. 250The note types correspond to the 251.Xr ptrace 2 252request numbers that return the same data. 253For example, 254a note with a note type of PT_GETREGS would contain a 255.Fa struct reg 256with the register contents of the execution context. 257For a complete list of available 258.Xr ptrace 2 259request types for a given architecture, refer to that architecture's 260.Aq Pa machine/ptrace.h 261header file. 262.Ss A.OUT CORE FORMAT 263The core file consists of a core header followed by a number of 264segments. 265Each segment is preceded by a core segment header. 266Both the core header and core segment header are defined in 267.In sys/core.h . 268.Pp 269The core header, 270.Fa struct core , 271specifies the lengths of the core header itself and 272each of the following core segment headers to allow for any machine 273dependent alignment requirements. 274.Bd -literal 275struct core { 276 uint32_t c_midmag; /* magic, id, flags */ 277 uint16_t c_hdrsize; /* Size of this header (machdep algn) */ 278 uint16_t c_seghdrsize; /* Size of a segment header */ 279 uint32_t c_nseg; /* # of core segments */ 280 char c_name[MAXCOMLEN+1]; /* Copy of p->p_comm */ 281 uint32_t c_signo; /* Killing signal */ 282 u_long c_ucode; /* Signal code */ 283 u_long c_cpusize; /* Size of machine dependent segment */ 284 u_long c_tsize; /* Size of traditional text segment */ 285 u_long c_dsize; /* Size of traditional data segment */ 286 u_long c_ssize; /* Size of traditional stack segment */ 287}; 288.Ed 289.Pp 290The fields of 291.Fa struct core 292are as follows: 293.Bl -tag -width XXXc_seghdrsize 294.It c_midmag 295Core file machine ID, magic value, and flags. 296These values may be extracted with the 297.Fn CORE_GETMID , 298.Fn CORE_GETMAGIC , 299and 300.Fn CORE_GETFLAG 301macros. 302The machine ID values are listed in 303.In sys/exec_aout.h . 304For a valid core file, the magic value in the header must be 305.Dv COREMAGIC . 306No flags are defined for the core header. 307.It c_hdrsize 308Size of this data structure. 309.It c_seghdrsize 310Size of a segment header. 311.It c_nseg 312Number of segments that follow this header. 313.It c_name 314Process name, copied from the p_comm field of 315.Fa struct proc . 316.It c_signo 317Signal that caused the process to dump core. 318.It c_ucode 319Code associated with the signal. 320.It c_cpusize 321Size of the segment containing CPU-specific information. 322This segment will have the 323.Dv CORE_CPU 324flag set. 325.It c_tsize 326Size of the segment containing the program text. 327.It c_dsize 328Size of the segment containing the program's traditional data area. 329.It c_ssize 330Size of the segment containing the program's traditional stack area. 331This segment will have the 332.Dv CORE_STACK 333flag set. 334.El 335The header is followed by 336.Fa c_nseg 337segments, each of which is preceded with a segment header, 338.Fa struct coreseg : 339.Bd -literal 340struct coreseg { 341 uint32_t c_midmag; /* magic, id, flags */ 342 u_long c_addr; /* Virtual address of segment */ 343 u_long c_size; /* Size of this segment */ 344}; 345.Ed 346.Pp 347The fields of 348.Fa struct coreseg 349are as follows: 350.Bl -tag -width XXXc_midmag 351.It c_midmag 352Core segment magic value and flags. 353These values may be extracted with the 354.Fn CORE_GETMAGIC 355and 356.Fn CORE_GETFLAG 357macros. 358The magic value in the segment header must be 359.Dv CORESEGMAGIC . 360Exactly one of the flags 361.Dv CORE_CPU , 362.Dv CORE_DATA , 363or 364.Dv CORE_STACK 365will be set to indicate the segment type. 366.It c_addr 367Virtual address of the segment in the program image. 368Meaningless if the segment type is 369.Dv CORE_CPU . 370.It c_size 371Size of the segment, not including this header. 372.El 373.Sh SEE ALSO 374.Xr gdb 1 , 375.Xr setrlimit 2 , 376.Xr sysctl 3 , 377.Xr a.out 5 , 378.Xr elf 5 , 379.Xr signal 7 , 380.Xr sysctl 8 381.Sh HISTORY 382A 383.Nm core 384file format appeared in 385.At v1 . 386The 387.Nx 388a.out core file format was introduced in 389.Nx 1.0 . 390The 391.Nx 392ELF core file format was introduced in 393.Nx 1.6 . 394.Pp 395In releases previous to 396.Nx 1.6 , 397ELF program images produced a.out-format core files. 398.Pp 399The 400.Dv cpi_siglwp 401member of the 402.Dv netbsd_elfcore_procinfo 403structure first appeared in 404.Nx 2.0 . 405However it retained the procinfo version 1, 406stored in 407.Dv cpi_version . 408.Pp 409.Dv ELF_NOTE_NETBSD_CORE_AUXV 410was added in 411.Nx 8.0 . 412.Sh BUGS 413There is no standard location or name for the 414CPU-dependent data structure stored in the 415.Dv CORE_CPU 416segment. 417