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