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