NAME
core —
memory image file format
SYNOPSIS
#include <sys/param.h>
For a.out-format core files:
#include <sys/core.h>
For ELF-format core files:
#include <sys/exec.h>
#include <sys/exec_elf.h>
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
signal(7)).
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
savecore(8).) The file is
named from a per-process template, mapped to the sysctl variable
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 (“%”). The following characters
are recognized as format and substituted:
- n
- The process's name
- p
- The PID of the process (in decimal)
- t
- The process's creation date (a la
time(3), in decimal)
- u
- The login name, as returned by
getlogin(2)
By default, the per-process template string points to the default core name
template, which is mapped to the sysctl variable
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
%n.core and can be changed at compile-time with the
kernel configuration option
options DEFCORENAME (see
options(4))
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.
The maximum size of a core file is limited by
setrlimit(2). Files which
would be larger than the limit are not created.
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.
In addition,
NetBSD 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 “NetBSD-CORE” and a
note type of
ELF_NOTE_NETBSD_CORE_PROCINFO
(
1
), and contains the following structure:
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 */
};
The fields of
struct netbsd_elfcore_procinfo are as
follows:
-
-
- cpi_version
- The version of this structure. The current version is
defined by the
NETBSD_ELFCORE_PROCINFO_VERSION
constant.
-
-
- cpi_cpisize
- The size of this structure.
-
-
- cpi_signo
- Signal that caused the process to dump core.
-
-
- cpi_sigcode
- Signal-specific code, if any, corresponding to
cpi_signo.
-
-
- cpi_sigpend
- A mask of signals pending delivery to the process. This may
be examined by copying it to a sigset_t.
-
-
- cpi_sigmask
- The set of signals currently blocked by the process. This
may be examined by copying it to a sigset_t.
-
-
- cpi_sigignore
- The set of signals currently being ignored by the process.
This may be examined by copying it to a
sigset_t.
-
-
- cpi_sigcatch
- The set of signals with registers signals handlers for the
process. This may be examined by copying it to a
sigset_t.
-
-
- cpi_pid
- Process ID of the process.
-
-
- cpi_ppid
- Process ID of the parent process.
-
-
- cpi_pgrp
- Process group ID of the process.
-
-
- cpi_sid
- Session ID of the process.
-
-
- cpi_ruid
- Real user ID of the process.
-
-
- cpi_euid
- Effective user ID of the process.
-
-
- cpi_svuid
- Saved user ID of the process.
-
-
- cpi_rgid
- Real group ID of the process.
-
-
- cpi_egid
- Effective group ID of the process.
-
-
- cpi_svgid
- Saved group ID of the process.
-
-
- cpi_nlwps
- Number of kernel-visible execution contexts (LWPs) of the
process.
-
-
- cpi_name
- Process name, copied from the p_comm field of
struct proc.
-
-
- cpi_siglwp
- LWP target of killing signal.
The second note with name “NetBSD-CORE” is a note type of
ELF_NOTE_NETBSD_CORE_AUXV
(
2
),
and contains an array of AuxInfo structures.
The note section also contains additional notes for each kernel-visible
execution context of the process (LWP). These notes have names of the form
“NetBSD-CORE@nn” where “nn” is the LWP ID of the
execution context, for example: “NetBSD-CORE@1”. These notes
contain register and other per-execution context data in the same format as is
used by the
ptrace(2) system
call. The note types correspond to the
ptrace(2) request numbers that
return the same data. For example, a note with a note type of PT_GETREGS would
contain a
struct reg with the register contents of the
execution context. For a complete list of available
ptrace(2) request types for a
given architecture, refer to that architecture's
⟨
machine/ptrace.h⟩ header file.
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
<sys/core.h>.
The core header,
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.
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 */
};
The fields of
struct core are as follows:
-
-
- c_midmag
- Core file machine ID, magic value, and flags. These values
may be extracted with the CORE_GETMID(),
CORE_GETMAGIC(), and CORE_GETFLAG()
macros. The machine ID values are listed in
<sys/exec_aout.h>. For a valid
core file, the magic value in the header must be
COREMAGIC
. No flags are defined for the core
header.
-
-
- c_hdrsize
- Size of this data structure.
-
-
- c_seghdrsize
- Size of a segment header.
-
-
- c_nseg
- Number of segments that follow this header.
-
-
- c_name
- Process name, copied from the p_comm field of
struct proc.
-
-
- c_signo
- Signal that caused the process to dump core.
-
-
- c_ucode
- Code associated with the signal.
-
-
- c_cpusize
- Size of the segment containing CPU-specific information.
This segment will have the
CORE_CPU
flag set.
-
-
- c_tsize
- Size of the segment containing the program text.
-
-
- c_dsize
- Size of the segment containing the program's traditional
data area.
-
-
- c_ssize
- Size of the segment containing the program's traditional
stack area. This segment will have the
CORE_STACK
flag set.
The header is followed by
c_nseg segments, each of which
is preceded with a segment header,
struct coreseg:
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 */
};
The fields of
struct coreseg are as follows:
-
-
- c_midmag
- Core segment magic value and flags. These values may be
extracted with the CORE_GETMAGIC() and
CORE_GETFLAG() macros. The magic value in the segment
header must be
CORESEGMAGIC
. Exactly one of the
flags CORE_CPU
, CORE_DATA
,
or CORE_STACK
will be set to indicate the segment
type.
-
-
- c_addr
- Virtual address of the segment in the program image.
Meaningless if the segment type is
CORE_CPU
.
-
-
- c_size
- Size of the segment, not including this header.
SEE ALSO
gdb(1),
setrlimit(2),
sysctl(3),
a.out(5),
elf(5),
signal(7),
sysctl(8)
HISTORY
A
core file format appeared in
Version 6
AT&T UNIX. The
NetBSD a.out core file
format was introduced in
NetBSD 1.0. The
NetBSD ELF core file format was introduced in
NetBSD 1.6.
In releases previous to
NetBSD 1.6, ELF program images
produced a.out-format core files.
The
cpi_siglwp
member of the
netbsd_elfcore_procinfo
structure first appeared in
NetBSD 2.0. However it retained the procinfo version
1, stored in
cpi_version
.
ELF_NOTE_NETBSD_CORE_AUXV
was added in
NetBSD 8.0.
BUGS
There is no standard location or name for the CPU-dependent data structure
stored in the
CORE_CPU
segment.