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