1.\" $NetBSD: core.5,v 1.16 2002/02/13 08:18:10 ross Exp $ 2.\" 3.\" Copyright (c) 1980, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by the University of 17.\" California, Berkeley and its contributors. 18.\" 4. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" @(#)core.5 8.3 (Berkeley) 12/11/93 35.\" 36.Dd October 7, 2000 37.Dt CORE 5 38.Os 39.Sh NAME 40.Nm core 41.Nd memory image file format 42.Sh SYNOPSIS 43.Fd #include \*[Lt]sys/param.h\*[Gt] 44.Sh DESCRIPTION 45A small number of signals which cause abnormal termination of a process 46also cause a record of the process's in-core state to be written 47to disk for later examination by one of the available debuggers 48(see 49.Xr signal 7 ) . 50.Pp 51This memory image is written to a file named from a per-process template; 52provided the terminated process had write permission, and provided the 53abnormality did not cause a system crash. 54(In this event, the decision to save the core file is arbitrary, see 55.Xr savecore 8 . ) 56The file is named from a per-process template, mapped to the sysctl 57variable 58.Em proc.\*[Lt]pid\*[Gt].corename 59(where \*[Lt]pid\*[Gt] has to be replaced by the pid in decimal format of the 60process). 61This template is either an absolute or relative path name, in which format 62characters can be used, preceded by the percent character 63.Pq Dq \&% . 64The following characters are recognised as format and substituted: 65.Bl -tag -width 4n -offset indent -compact 66.It Sy n 67The process's name 68.It Sy p 69The PID of the process (in decimal) 70.It Sy t 71The process's creation date (a la 72.Xr time 3 , 73in decimal) 74.It Sy u 75The login name, as returned by 76.Xr getlogin 2 77.El 78.Pp 79By default, the per-process template string points to the default core name 80template, which is mapped to the sysctl variable 81.Em kern.defcorename . 82Changing this value on a live system will change the core name template for 83all processes which didn't have a per-process template set. 84The default value of the default core name template is 85.Nm %n.core 86and can be changed at compile-time with the kernel configuration option 87.Cd options DEFCORENAME 88(see 89.Xr options 4 ) 90.Pp 91The per-process template string is inherited on process creation, but is reset 92to point to the default core name template on execution of a set-id binary. 93.Pp 94The maximum size of a core file is limited by 95.Xr setrlimit 2 . 96Files which would be larger than the limit are not created. 97.Pp 98The core file contains of a core header followed by a number of 99segments. Each segment is preceded by a core segment header. 100Both the core header and core segment header are defined in 101.Aq Pa sys/core.h . 102.Pp 103The core header, 104.Fa struct core , 105specifies the lengths of the core header itself and 106each of the following core segment headers to allow for any machine 107dependent alignment requirements. 108.Bd -literal 109struct core { 110 u_int32_t c_midmag; /* magic, id, flags */ 111 u_int16_t c_hdrsize; /* Size of this header (machdep algn) */ 112 u_int16_t c_seghdrsize; /* Size of a segment header */ 113 u_int32_t c_nseg; /* # of core segments */ 114 char c_name[MAXCOMLEN+1]; /* Copy of p-\*[Gt]p_comm */ 115 u_int32_t c_signo; /* Killing signal */ 116 u_long c_ucode; /* Signal code */ 117 u_long c_cpusize; /* Size of machine dependent segment */ 118 u_long c_tsize; /* Size of traditional text segment */ 119 u_long c_dsize; /* Size of traditional data segment */ 120 u_long c_ssize; /* Size of traditional stack segment */ 121}; 122.Ed 123.Pp 124The fields of 125.Fa struct core 126are as follows: 127.Bl -tag -width XXXc_seghdrsize 128.It c_midmag 129Core file machine ID, magic value, and flags. 130These values may be extracted with the 131.Fn CORE_GETMID , 132.Fn CORE_GETMAGIC , 133and 134.Fn CORE_GETFLAG 135macros. The machine ID values are listed in 136.Aq Pa sys/exec_aout.h . 137For a valid core file, the magic value in the header must be 138.Dv COREMAGIC . 139No flags are defined for the core header. 140.It c_hdrsize 141Size of this data structure. 142.It c_seghdrsize 143Size of a segment header. 144.It c_nseg 145Number of segments that follow this header. 146.It c_name 147Process name, copied from the p_comm field of 148.Fa struct proc . 149.It c_signo 150Signal that caused the process to dump core. 151.It c_ucode 152Code associated with the signal. 153.It c_cpusize 154Size of the segment containing CPU-specific information. 155This segment will have the 156.Dv CORE_CPU 157flag set. 158.It c_tsize 159Size of the segment containing the program text. 160.It c_dsize 161Size of the segment containing the program's traditional data area. 162.It c_ssize 163Size of the segment containing the program's traditional stack area. 164This segment will have the 165.Dv CORE_STACK 166flag set. 167.El 168The header is followed by 169.Fa c_nseg 170segments, each of which is preceded with a segment header, 171.Fa struct coreseg : 172.Bd -literal 173struct coreseg { 174 u_int32_t c_midmag; /* magic, id, flags */ 175 u_long c_addr; /* Virtual address of segment */ 176 u_long c_size; /* Size of this segment */ 177}; 178.Ed 179.Pp 180The fields of 181.Fa struct coreseg 182are as follows: 183.Bl -tag -width XXXc_midmag 184.It c_midmag 185Core segment magic value and flags. 186These values may be extracted with the 187.Fn CORE_GETMAGIC 188and 189.Fn CORE_GETFLAG 190macros. 191The magic value in the segment header must be 192.Dv CORESEGMAGIC . 193Exactly one of of the flags 194.Dv CORE_CPU , 195.Dv CORE_DATA , 196or 197.Dv CORE_STACK 198will be set to indicate the segment type. 199.It c_addr 200Virtual address of the segment in the program image. 201Meaningless if the segment type is 202.Dv CORE_CPU . 203.It c_size 204Size of the segment, not including this header. 205.El 206.Sh SEE ALSO 207.Xr gdb 1 , 208.Xr setrlimit 2 , 209.Xr sysctl 3 , 210.Xr signal 7 , 211.Xr sysctl 8 212.Sh HISTORY 213A 214.Nm core 215file format appeared in 216.At v6 . 217.Sh BUGS 218There is no standard location or name for the 219CPU-dependent data structure stored in the 220.Dv CORE_CPU 221segment. 222