.\"	$NetBSD: core.5,v 1.31 2017/07/03 21:30:59 wiz Exp $
.\"
.\" Copyright (c) 2002 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Jason R. Thorpe.
.\"
.\" 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.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. 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 FOUNDATION 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.
.\"
.\" 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 March 27, 2017
.Dt CORE 5
.Os
.Sh NAME
.Nm core
.Nd memory image file format
.Sh SYNOPSIS
.In sys/param.h
.Pp
For a.out-format core files:
.Pp
.In sys/core.h
.Pp
For ELF-format core files:
.Pp
.In sys/exec.h
.In sys/exec_elf.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 signal 7 ) .
.Pp
This memory image is written to a file named from a per-process template;
provided the terminated process had write permission, 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 . )
The file is named from a per-process template, mapped to the sysctl
variable
.Em proc.<pid>.corename
(where <pid> has to be replaced by the pid in decimal format of the
process).
This template is either an absolute or relative path name, in which format
characters can be used, preceded by the percent character
.Pq Dq \&% .
The following characters are recognized as format and substituted:
.Bl -tag -width 4n -offset indent -compact
.It Sy n
The process's name
.It Sy p
The PID of the process (in decimal)
.It Sy t
The process's creation date (a la
.Xr time 3 ,
in decimal)
.It Sy u
The login name, as returned by
.Xr getlogin 2
.El
.Pp
By default, the per-process template string points to the default core name
template, which is mapped to the sysctl variable
.Em kern.defcorename .
Changing this value on a live system will change the core name template for
all processes which didn't have a per-process template set.
The default value of the default core name template is
.Nm %n.core
and can be changed at compile-time with the kernel configuration option
.Cd options DEFCORENAME
(see
.Xr options 4 )
.Pp
The per-process template string is inherited on process creation, but is reset
to point to the default core name template on execution of a set-id binary.
.Pp
The maximum size of a core file is limited by
.Xr setrlimit 2 .
Files which would be larger than the limit are not created.
.Ss ELF CORE FORMAT
ELF-format core files are described by a standard ELF exec header and
a series of ELF program headers.
Each program header describes a range
of the virtual address space of the process.
.Pp
In addition,
.Nx
ELF core files include an ELF note section which provides additional
information about the process.
The first note in the note section has a note name of
.Dq NetBSD-CORE
and a note type of
.Dv ELF_NOTE_NETBSD_CORE_PROCINFO ( 1 ) ,
and contains the following
structure:
.Bd -literal
struct netbsd_elfcore_procinfo {
   /* Version 1 fields start here. */
    uint32_t cpi_version;      /* netbsd_elfcore_procinfo version */
    uint32_t cpi_cpisize;      /* sizeof(netbsd_elfcore_procinfo) */
    uint32_t cpi_signo;        /* killing signal */
    uint32_t cpi_sigcode;      /* signal code */
    uint32_t cpi_sigpend[4];   /* pending signals */
    uint32_t cpi_sigmask[4];   /* blocked signals */
    uint32_t cpi_sigignore[4]; /* blocked signals */
    uint32_t cpi_sigcatch[4];  /* blocked signals */
    int32_t  cpi_pid;          /* process ID */
    int32_t  cpi_ppid;         /* parent process ID */
    int32_t  cpi_pgrp;         /* process group ID */
    int32_t  cpi_sid;          /* session ID */
    uint32_t cpi_ruid;         /* real user ID */
    uint32_t cpi_euid;         /* effective user ID */
    uint32_t cpi_svuid;        /* saved user ID */
    uint32_t cpi_rgid;         /* real group ID */
    uint32_t cpi_egid;         /* effective group ID */
    uint32_t cpi_svgid;        /* saved group ID */
    uint32_t cpi_nlwps;        /* number of LWPs */
    int8_t   cpi_name[32];     /* copy of p->p_comm */
    /* Add version 2 fields below here. */
    int32_t         cpi_siglwp;     /* LWP target of killing signal */
};
.Ed
.Pp
The fields of
.Fa struct netbsd_elfcore_procinfo
are as follows:
.Bl -tag -width cpi_sigignoreXX
.It cpi_version
The version of this structure.
The current version is defined by the
.Dv NETBSD_ELFCORE_PROCINFO_VERSION
constant.
.It cpi_cpisize
The size of this structure.
.It cpi_signo
Signal that caused the process to dump core.
.It cpi_sigcode
Signal-specific code, if any, corresponding to
.Va cpi_signo .
.It cpi_sigpend
A mask of signals pending delivery to the process.
This may be examined by copying it to a
.Fa sigset_t .
.It cpi_sigmask
The set of signals currently blocked by the process.
This may be examined by copying it to a
.Fa sigset_t .
.It cpi_sigignore
The set of signals currently being ignored by the process.
This may be examined by copying it to a
.Fa sigset_t .
.It cpi_sigcatch
The set of signals with registers signals handlers for the process.
This may be examined by copying it to a
.Fa sigset_t .
.It cpi_pid
Process ID of the process.
.It cpi_ppid
Process ID of the parent process.
.It cpi_pgrp
Process group ID of the process.
.It cpi_sid
Session ID of the process.
.It cpi_ruid
Real user ID of the process.
.It cpi_euid
Effective user ID of the process.
.It cpi_svuid
Saved user ID of the process.
.It cpi_rgid
Real group ID of the process.
.It cpi_egid
Effective group ID of the process.
.It cpi_svgid
Saved group ID of the process.
.It cpi_nlwps
Number of kernel-visible execution contexts (LWPs) of the process.
.It cpi_name
Process name, copied from the p_comm field of
.Fa struct proc .
.It cpi_siglwp
LWP target of killing signal.
.El
.Pp
The second note with name
.Dq NetBSD-CORE
is a note type of
.Dv ELF_NOTE_NETBSD_CORE_AUXV ( 2 ) ,
and contains an array of AuxInfo structures.
.Pp
The note section also contains additional notes for each
kernel-visible execution context of the process (LWP).
These notes have names of the form
.Dq NetBSD-CORE@nn
where
.Dq nn
is the LWP ID of the execution context, for example:
.Dq NetBSD-CORE@1 .
These notes contain register and other per-execution context
data in the same format as is used by the
.Xr ptrace 2
system call.
The note types correspond to the
.Xr ptrace 2
request numbers that return the same data.
For example,
a note with a note type of PT_GETREGS would contain a
.Fa struct reg
with the register contents of the execution context.
For a complete list of available
.Xr ptrace 2
request types for a given architecture, refer to that architecture's
.Aq Pa machine/ptrace.h
header file.
.Ss A.OUT CORE FORMAT
The core file consists of a core header followed by a number of
segments.
Each segment is preceded by a core segment header.
Both the core header and core segment header are defined in
.In sys/core.h .
.Pp
The core header,
.Fa struct core ,
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 -literal
struct core {
    uint32_t c_midmag;         /* magic, id, flags */
    uint16_t c_hdrsize;        /* Size of this header (machdep algn) */
    uint16_t c_seghdrsize;     /* Size of a segment header */
    uint32_t c_nseg;           /* # of core segments */
    char      c_name[MAXCOMLEN+1];	/* Copy of p->p_comm */
    uint32_t c_signo;          /* Killing signal */
    u_long    c_ucode;          /* Signal code */
    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 fields of
.Fa struct core
are as follows:
.Bl -tag -width XXXc_seghdrsize
.It c_midmag
Core file machine ID, magic value, and flags.
These values may be extracted with the
.Fn CORE_GETMID ,
.Fn CORE_GETMAGIC ,
and
.Fn CORE_GETFLAG
macros.
The machine ID values are listed in
.In sys/exec_aout.h .
For a valid core file, the magic value in the header must be
.Dv COREMAGIC .
No flags are defined for the core header.
.It c_hdrsize
Size of this data structure.
.It c_seghdrsize
Size of a segment header.
.It c_nseg
Number of segments that follow this header.
.It c_name
Process name, copied from the p_comm field of
.Fa struct proc .
.It c_signo
Signal that caused the process to dump core.
.It c_ucode
Code associated with the signal.
.It c_cpusize
Size of the segment containing CPU-specific information.
This segment will have the
.Dv CORE_CPU
flag set.
.It c_tsize
Size of the segment containing the program text.
.It c_dsize
Size of the segment containing the program's traditional data area.
.It c_ssize
Size of the segment containing the program's traditional stack area.
This segment will have the
.Dv CORE_STACK
flag set.
.El
The header is followed by
.Fa c_nseg
segments, each of which is preceded with a segment header,
.Fa struct coreseg :
.Bd -literal
struct coreseg {
   uint32_t c_midmag;  /* magic, id, flags */
   u_long    c_addr;    /* Virtual address of segment */
   u_long    c_size;    /* Size of this segment */
};
.Ed
.Pp
The fields of
.Fa struct coreseg
are as follows:
.Bl -tag -width XXXc_midmag
.It c_midmag
Core segment magic value and flags.
These values may be extracted with the
.Fn CORE_GETMAGIC
and
.Fn CORE_GETFLAG
macros.
The magic value in the segment header must be
.Dv CORESEGMAGIC .
Exactly one of the flags
.Dv CORE_CPU ,
.Dv CORE_DATA ,
or
.Dv CORE_STACK
will be set to indicate the segment type.
.It c_addr
Virtual address of the segment in the program image.
Meaningless if the segment type is
.Dv CORE_CPU .
.It c_size
Size of the segment, not including this header.
.El
.Sh SEE ALSO
.Xr gdb 1 ,
.Xr setrlimit 2 ,
.Xr sysctl 3 ,
.Xr a.out 5 ,
.Xr elf 5 ,
.Xr signal 7 ,
.Xr sysctl 8
.Sh HISTORY
A
.Nm core
file format appeared in
.At v6 .
The
.Nx
a.out core file format was introduced in
.Nx 1.0 .
The
.Nx
ELF core file format was introduced in
.Nx 1.6 .
.Pp
In releases previous to
.Nx 1.6 ,
ELF program images produced a.out-format core files.
.Pp
The
.Dv cpi_siglwp
member of the
.Dv netbsd_elfcore_procinfo
structure first appeared in
.Nx 2.0 .
However it retained the procinfo version 1,
stored in
.Dv cpi_version .
.Pp
.Dv ELF_NOTE_NETBSD_CORE_AUXV
was added in
.Nx 8.0 .
.Sh BUGS
There is no standard location or name for the
CPU-dependent data structure stored in the
.Dv CORE_CPU
segment.