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