The Operating System writes out a core image of a terminated process when
various errors occur.
See
sigaction(S)
for a list of reasons;
the most common errors are memory violations,
illegal instructions,
and user-generated quit signals.
The core image is called
core
and is written in the process' working directory (provided it can be;
normal access controls apply).
Use the
file(C)
command to report the command line
that produced the core file
and the time that command line was invoked.
A process with an effective user (group) ID different
from the real user (group) ID will not produce a core image.
If a file named core
already exists in the process' working directory
and is not a regular file or has links,
no core image is produced.
The core image contains all mutable portions of the process'
virtual address space plus information from the system about
the state of the process.
If the text segment is read-only and shared,
or separated from data space,
it is not dumped.
Attached shared memory,
shared data,
and shared library data are dumped.
The core file
is logically divided into a series of sections.
A section either describes the core file,
contains a copy of the contents of a kernel data structure,
or contains a copy of the contents of the process' memory
at the time of the dump.
Each section consists of a header describing the section,
optional additional information about the section's contents,
and the section's contents.
Consecutive sections may not be physically adjacent.
Whilst any optional information physically follows the header,
the contents may not.
The header contains the size and offset of its contents.
The headers themselves form a chain.
The section header is defined in
<sys/paccess.h>:
struct coresecthead {
uchar_t cs_stype; /* Type of section (CORES_xxx) */
uchar_t cs_hsize; /* Size (bytes) of section header */
ushort cs_osize; /* Size (bytes) of optional info */
union {
struct {
short csxp_rflg; /* Associated pregion's p_flags */
short csxp_rtyp; /* Associated pregion's p_type */
} csx_preg;
ulong_t csx_magic; /* COREMAGIC_xxx for MAGIC, OFFSETS */
} cs_x;
ulong_t cs_vaddr; /* Virtual address of contents */
ulong_t cs_vsize; /* Size (bytes) of contents */
long cs_sseek; /* Offset of this section's contents */
long cs_hseek; /* Offset of next section's header */
};
Each coresecthead structure
in a core file contains:
cs_stype
The type of section dumped (see list below).
cs_hsize
The size,
in bytes,
of this core section header
(coresecthead
structure)
including this size field itself.
cs_x
The format and contents of this union depend on the section's type
as described below.
cs_osize
The size,
in bytes,
of the optional information about this core section's contents.
The format of this optional additional information depends on
the type of information contained in the section.
The optional information starts immediately after this
coresecthead structure in the core file.
cs_vaddr
The virtual address of this section's contents in the appropriate
address space.
cs_vsize
The size,
in bytes,
of this section's contents.
cs_sseek
The offset (from zero) in the core file
of this section's contents.
A section's contents may not be physically adjacent to
its header and additional information.
cs_hseek
The offset (from zero) in the core file
of the ``next'' section.
A zero or negative offset ends the chain.
The logical order of sections in a core file
is unrelated to the numerical values of the section header offsets.
Should a future release or update of the system require an expanded
coresecthead structure,
the additional fields will be added at the end of the structure.
Programs should therefore not assume that
sizeof(struct coresecthead)
bytes were written to the core file;
the cs_hsize field contains
the number of bytes that were written.
The defined cs_stype section types include:
CORES_MAGIC
If this section is dumped,
it is always at offset zero.
This section is always dumped unless the
CORES_UAREA
section (described below) could not be dumped.
The
cs_x.csx_magic
field is either
COREMAGIC_NUMBER
(this
core
file is believed valid) or
COREMAGIC_INVALID
(the core file may be corrupt).
This section always heads the chain,
and the ``next'' section in the chain for valid
core files is always the
CORES_OFFSETS section (described below).
The additional information is a byte containing the last error
encountered when writing the core file
(as defined in <sys/errno.h>),
and the contents of this section are always
the null terminated name of the core file
(which is always `` core ''
in current releases of the Operating System).
CORES_UAREA
The system's user structure (defined in
<sys/user.h>) for the process.
This section is always present in a valid core file.
No additional information is currently defined for this section.
The cs_x union is reserved for possible future use.
CORES_PREGION
Memory attached to the process' virtual address space.
The cs_x.csx_preg.csxp_rtyp
and cs_x.csx_preg.csxp_rflg fields contain the
pregion structure's p_type
and p_flags fields (respectively)
for the memory attached to the
process at virtual address
cs_vaddr.
Those fields are defined in
<sys/region.h>.
The type of memory is given by
cs_x.csx_preg.csxp_rtyp
and includes
PT_STACK
(the process' stack),
PT_DATA
(the process' data),
PT_SHMEM
(an attached shared memory segment),
and
PT_LIBDAT
(data associated with a shared library).
Text
(PT_TEXT
and
PT_LIBTXT)
are never dumped.
Only
PT_SHMEM
memory has additional information -- the
shmds_id
structure associated with this shared memory
(defined in
<sys/shm.h>).
No other additional information is currently defined for this section.
CORES_PROC
The system's
proc
structure as defined in
<sys/proc.h>
for this process.
There is at most one such section in a valid core file.
No additional information is currently defined for this section.
The cs_x union is reserved for possible future use.
CORES_ITIMER
The process' interval timer values as an array of
itimerval
structures (defined in
<sys/itimer.h>).
There is at most one such section in a valid core file.
No additional information is currently defined for this section.
The
cs_x
union is reserved for possible future use.
CORES_SCOUTSNAME
The system's
scoutsname
structure defined in
<sys/utsname.h>.
There is at most one such section in a valid core file.
No additional information is currently defined for this section.
The cs_x union is reserved for possible future use.
CORES_OFFSETS
Always the physically last section in a valid core file,
this section contains the process'
coreoffsets structure defined in
<sys/paccess.h>.
The additional information's size is always an exact number of longwords.
The last longword is always the core file offset
(from zero) of this section's header,
and the next-to-last longword is the number of sections in the chain
(excluding the
CORES_MAGIC
section but including this
CORES_OFFSET
section itself).
Only the
coresecthead
section may preceed this section in the chain,
so this section may be considered the head of the chain.
No additional longwords are currently defined.
Immediately following these longwords is the
coreoffsets
structure (also defined in
<sys/paccess.h>).
That structure is always at the very end of a valid core file.
The
cs_x.csx_magic
field is either
COREMAGIC_NUMBER
(the
core
file is believed valid) or
COREMAGIC_INVALID
(the
core
file may be corrupt).
The last longword of the
coreoffsets
structure is always the size of that structure itself
(including that last longword):
struct coreoffsets {
uoff u_info; /* interface version (C_VERSION) */
uoff u_user; /* offset of upage in core file */
uoff u_ldt; /* offset of ldt in core file */
uoff u_data; /* offset of data in core file */
uoff u_stack; /* offset of stack in core file */
uoff u_usize; /* size of uarea */
uoff u_uaddr; /* kernel virtual address of uarea */
uoff u_ar0; /* user register save area pointer */
uoff u_fps; /* floating point save area */
uoff u_fper; /* 2.3 field */
uoff u_fpemul; /* separate emulator save area */
uoff u_fpvalid; /* valid save fpstate */
uoff u_weitek; /* flag indicating weitek usage */
uoff u_weitek_reg; /* weitek save area */
uoff u_ssize; /* stack size */
uoff u_dsize; /* data size */
uoff u_tsize; /* text size */
uoff u_comm; /* name of executable */
uoff u_ldtlimit; /* size of ldt */
uoff u_sub; /* stack upper bound */
uoff u_sdata; /* 3.2 u_exdata.ux_datorg */
uoff u_mag; /* u_exdata.ux_mag */
uoff u_sigreturn;
uoff u_signal;
uoff uvstack; /* virtual address of stack top */
uoff uvtext; /* virtual address of text */
uoff size; /* size of this structure */
};
Some of these fields contain information about the
core file's layout:
u_info
Format version number.
The current version is
C_VERSION,
which is 2.
This manual page describes the version 2 format.
u_user
Offset (from zero) in the
core file of the process' user structure,
which is the contents of the
CORES_UAREA section.
This field is identical to that section's
cs_sseek
u_ldt
Offset from the beginning of the
CORES_UAREA
section's contents (that is,
from the beginning of the dumped
user
structure) of the process' LDT.
The number of entries in the table varies and is given by the
u_ldtlimit
field in the
user
structure,
whose offset is given by the
u_ldtlimit
field of the
coreoffsets
structure.
u_data
Offset (from zero) in the core file of the
PT_DATACORES_PREGION
section containing the data and
BSS
loaded from the process' executable file.
This field is identical to that section's
cs_sseek.
u_stack
Offset (from zero) in the
core file of the process' stack,
which is the contents of the
PT_STACKCORES_PREGION
section.
This field is identical to that section's
cs_sseek.
u_usize
The size,
in bytes,
of the process'
user
-area.
This field is identical to the
CORES_UAREA
section's
cs_vsize.
u_uaddr
The kernel's virtual address of the process'
user structure.
This field is identical to the
CORES_UAREA section's cs_vaddr.
u_fper
Obsolete; always zero.
uvstack
The numerically highest virtual address of the process' stack.
For historical reasons this does not include the last
longword of the stack.
uvtext
The numerically lowest virtual address of the process' text.
The other fields in the
coreoffsets
structure are the offset (in bytes) from the beginning of the
USERS_UAREA
contents of the similarly-named fields in the dumped
user
structure:
Structure
coreoffsets
field
user
offset
Comments
u_ar0
u_ar0
Kernel virtual address of process' registers
u_fps
u_fps
Saved FPU hardware state
u_fpemul
u_fps
Saved FPU emulator state
u_fpvalid
u_fpvalid
FPU state saved?
u_weitek
u_weitek
u_weitek_reg
u_weitek_reg
u_ssize
u_ssize
Pages of process' stack in core
u_dsize
u_dsize
Pages of process' data in core
u_tsize
u_tsize
Pages of process' separate/shared text
u_comm
u_comm
Executable file's basename
u_ldtlimit
u_ldtlimit
u_sub
u_sub
Lowest address in process' stack
u_sdata
u_exdata.ux_datorg
Process' data virtual address
u_mag
u_exdata.ux_mag
Executable's magic number
u_sigreturn
u_sigreturn
u_signal
u_signal[0]
The size of the
core
file never exceeds the process'
ulimit(S)
in effect at the time of the core dump.
If the
ulimit
is insufficient to contain the entire
user
and
coreoffsets
structures plus their corresponding
coresecthead
headers,
nothing is written to the core file.
If the
ulimit
is too small to contain both the process' stack
(PT_STACK)
and data
(PT_DATA)
memory,
only the stack is written (plus the
user
and
coreoffsets
structures);
if the
ulimit
is too small to contain the stack,
then only the
user
and
coreoffsets
sections are written.
Other sections are squeezed in as the
ulimit
permits.
Notes
Version 1
core files contain only the first two pages of the
user structure (always at offset zero),
the process' stack and data memory,
and the coreoffsets structure
(always at the end of the core file).
No other memory or information are present,
and no coresecthead structures are dumped.
In particular,
there is no CORES_MAGIC section
in a genuine version 1 core file.
The u_ldt field of the coreoffsets structure
in a genuine version 1 core file
may point to memory which was not actually dumped,
or which was only partially dumped.
The version 2 core file format
is designed so most programs expecting a version 1
core file should continue to work unchanged,
although they will not be able to access the additional
information present in version 2 files.
However,
some utilities require version 1 core files.
The
corex(C)
command converts a version 2
core file into its version 1 equivalent.
The LDT in the converted core file
may -- like genuine version 1 core files
-- either not be dumped or be only partially dumped.
The
CORES_MAGIC
section actually overlays the beginning of the
CORES_UAREA
section's contents so that,
like version 1 core files,
the user structure in version 2
core files starts at offset zero.
There is no data of consequence in the overlaid bytes,
being the furthermost extent of the kernel's stack.
The u_comm string in the
user structure is not necessarily null-terminated.
The
u_ar0
field in the
coreoffsets
structure is the offset in the
CORES_UAREA
section of the kernel's virtual address which
in turn points to the process' registers.
That offset is not the offset of the saved registers themselves.
The dumped
u_ar0
kernel virtual address refers to core dumped someplace in the
CORES_UAREA
section;
the pointed to dumped core is arranged as described in
<sys/regs.h>.