.\"	$OpenBSD: core.5,v 1.13 2010/02/25 17:11:25 jmc Exp $
.\"	$NetBSD: core.5,v 1.4 1994/11/30 19:31:11 jtc Exp $
.\"
.\" Copyright (c) 1980, 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)core.5	8.3 (Berkeley) 12/11/93
.\"
.Dd $Mdocdate: February 25 2010 $
.Dt CORE 5
.Os
.Sh NAME
.Nm core
.Nd memory image file format
.Sh SYNOPSIS
.Fd #include <sys/param.h>
.Fd #include <sys/core.h>
.Sh DESCRIPTION
A small number of signals which cause abnormal termination of a process
also cause a record of the process's in-core state to be written
to disk for later examination by one of the available debuggers (see
.Xr sigaction 2 ) .
This memory image is written to a file named
.Pa programname.core
in the working directory, provided the terminated process had write
permission in the directory, and provided the abnormality did not cause
a system crash.
(In this event, the decision to save the core file is arbitrary, see
.Xr savecore 8 . )
.Pp
The maximum size of a
.Pa programname.core
file is limited by
.Xr setrlimit 2 .
Files which would be larger than the limit are not created.
.Pp
The
.Pa programname.core
file consists of the u-area, whose size (in pages) is defined by the
.Dv UPAGES
manifest in the
.Aq Pa machine/param.h
file.
The u-area starts with a
.Fa user
structure as given in
.Aq Pa sys/user.h .
The remainder of the
.Pa programname.core
file consists of the data pages followed by the stack pages of the
process image.
The amount of data space image in the
.Pa programname.core
file is given (in pages) by the variable
.Fa u_dsize
in the u-area.
The amount of stack image in the core file is given (in pages) by the variable
.Fa u_ssize
in the u-area.
The size of a
.Dq page
is given by the constant
.Dv PAGE_SIZE ,
defined in
.Aq Pa machine/param.h .
The
.Fa user
structure is defined as:
.Bd -unfilled -offset indent
struct	user {
	struct	pcb u_pcb;

	struct	pstats u_stats;

	/*
	 * Remaining fields only for core dump and/or ptrace--
	 * not valid at other times!
	 */
	struct	kinfo_proc u_kproc;
	struct	md_coredump u_md;
};
.Ed
.Pp
.Fa md_coredump
is defined in the header file
.Aq Pa machine/pcb.h .
.Pp
The on-disk core file consists of a header followed by a number of segments.
Each segment is preceded by a
.Fa coreseg
structure giving the segment's type,
the virtual address where the bits resided in process address space
and the size of the segment.
.Pp
The core header specifies the lengths of the core header itself and
each of the following core segment headers to allow for any machine
dependent alignment requirements.
.Bd -unfilled -offset indent
struct coreseg {
	u_int32_t c_midmag;		/* magic, id, flags */
	u_long	c_addr;		/* Virtual address of segment */
	u_long	c_size;		/* Size of this segment */
};
.Ed
.Bd -unfilled -offset indent
struct core {
	u_int32_t c_midmag;		/* magic, id, flags */
	u_int16_t c_hdrsize;   /* Size of this header (machdep algn) */
	u_int16_t c_seghdrsize;	/* Size of a segment header */
	u_int32_t c_nseg;		/* # of core segments */
	char	c_name[MAXCOMLEN+1];	/* Copy of p->p_comm */
	u_int32_t c_signo;		/* Killing signal */
	u_long	c_ucode;		/* Hmm ? */
	u_long	c_cpusize;	/* Size of machine dependent segment */
	u_long	c_tsize;		/* Size of traditional text segment */
	u_long	c_dsize;		/* Size of traditional data segment */
	u_long	c_ssize;		/* Size of traditional stack segment */
};
.Ed
.Pp
The core structure's
.Fa c_midmag field
is an a.out midmag number with a
.Dv COREMAGIC
magic number (see
.Xr a.out 5 )
and flags from the following list:
.Bd -unfilled -offset indent
#define CORE_CPU	1
#define CORE_DATA	2
#define CORE_STACK	4
.Ed
.Sh SEE ALSO
.Xr gdb 1 ,
.Xr pmdb 1 ,
.Xr setrlimit 2 ,
.Xr sigaction 2 ,
.Xr sysctl 3
.Sh HISTORY
A
.Nm
file format appeared in
.At v3 .
.Sh CAVEATS
Programs with their set-user-ID bit set will not dump core,
to prevent sensitive information from inadvertently ending up on disk.
See
.Li kern.nosuidcoredump
in
.Xr sysctl 3
for more information.