illumos: manual page: core.5

CORE(5) File Formats and Configurations CORE(5)

NAME

core - process core file

DESCRIPTION

The operating system writes out a core file for a process when the process
is terminated due to receiving certain signals. A core file is a disk copy
of the contents of the process address space at the time the process
received the signal, along with additional information about the state of
the process. This information can be consumed by a debugger. Core files
can also be generated by applying the gcore(1) utility to a running
process.

Typically, core files are produced following abnormal termination of a
process resulting from a bug in the corresponding application. Whatever
the cause, the core file itself provides invaluable information to the
programmer or support engineer to aid in diagnosing the problem. The core
file can be inspected using a debugger such as mdb(1), gdb, dbx, or or by
applying one of the proc(1) tools.

The operating system attempts to create up to two core files for each
abnormally terminating process, using a global core file name pattern and a
per-process core file name pattern. These patterns are expanded to
determine the pathname of the resulting core files, and can be configured
by coreadm(8). By default, the global core file pattern is disabled and
not used, and the per-process core file pattern is set to core. Therefore,
by default, the operating system attempts to create a core file named core
in the process's current working directory.

A process terminates and produces a core file whenever it receives one of
the signals whose default disposition is to cause a core dump or the
upanic(2) system call is used. The list of signals that result in
generating a core file is shown in signal.h(3HEAD). Therefore, a process
might not produce a core file if it has blocked or modified the behavior of
the corresponding signal. Additionally, no core dump can be created under
the following conditions:

+o If normal file and directory access permissions prevent the creation or
modification of the per-process core file pathname by the current
process user and group ID. This test does not apply to the global core
file pathname because, regardless of the UID of the process dumping
core, the attempt to write the global core file is made as the
superuser.

+o Core files owned by the user nobody will not be produced. For example,
core files generated for the superuser on an NFS directory are owned by
nobody and are, therefore, not written.

+o If the core file pattern expands to a pathname that contains
intermediate directory components that do not exist. For example, if
the global pattern is set to /var/core/%n/core.%p, and no directory
/var/core/`uname -n` has been created, no global core files are
produced.

+o If the destination directory is part of a filesystem that is mounted
read-only.

+o If the resource limit RLIMIT_CORE has been set to 0 for the process, no
per-process core file is produced. Refer to setrlimit(2) and ulimit(1)
for more information on resource limits.

+o If the core file name already exists in the destination directory and
is not a regular file (that is, is a symlink, block or character
special-file, and so forth).

+o If the kernel cannot open the destination file O_EXCL, which can occur
if same file is being created by another process simultaneously.

+o If the process's effective user ID is different from its real user ID
or if its effective group ID is different from its real group ID.
Similarly, set-user-ID and set-group-ID programs do not produce core
files as this could potentially compromise system security. These
processes can be explicitly granted permission to produce core files
using coreadm(8), at the risk of exposing secure information.

The core file contains all the process information pertinent to debugging:
contents of hardware registers, process status, and process data. The
format of a core file is object file specific.

For ELF executable programs (see a.out(5)), the core file generated is also
an ELF file, containing ELF program and file headers. The e_type field in
the file header has type ET_CORE. The program header contains an entry for
every segment that was part of the process address space, including shared
library segments. The contents of the mappings specified by coreadm(8) are
also part of the core image. Each program header has its p_memsz field set
to the size of the mapping. The program headers that represent mappings
whose data is included in the core file have their p_filesz field set the
same as p_memsz, otherwise p_filesz is zero.

A mapping's data can be excluded due to the core file content settings (see
coreadm(8)), due to a failure, or due to a signal received after core dump
initiation but before its completion. If the data is excluded because of a
failure, the program header entry will have the PF_SUNW_FAILURE flag set in
its p_flags field; if the data is excluded because of a signal, the
segment's p_flags field will have the PF_SUNW_KILLED flag set.

The program headers of an ELF core file also contain entries for two NOTE
segments, each containing several note entries as described below. The
note entry header and core file note type (n_type) definitions are
contained in <sys/elf.h>. The first NOTE segment exists for binary
compatibility with old programs that deal with core files. It contains
structures defined in <sys/old_procfs.h>. New programs should recognize
and skip this NOTE segment, advancing instead to the new NOTE segment. The
old NOTE segment is deleted from core files in a future release.

The old NOTE segment contains the following entries. Each has entry name
CORE and presents the contents of a system structure:

prpsinfo_t n_type: NT_PRPSINFO. This entry contains information of
interest to the ps(1) command, such as process status, CPU
usage, nice value, controlling terminal, user-ID, process-ID,
the name of the executable, and so forth. The prpsinfo_t
structure is defined in <sys/old_procfs.h>.

char[] n_type: NT_PLATFORM. This entry contains a string describing
the specific model of the hardware platform on which this core
file was created. This information is the same as provided by
sysinfo(2) when invoked with the command SI_PLATFORM.

auxv_t[] n_type: NT_AUXV. This entry contains the array of Bauxv_t
structures that was passed by the operating system as startup
information to the dynamic linker. Auxiliary vector
information is defined in <sys/auxv.h>.

Following these entries, for each active (non-zombie) light-weight process
(LWP) in the process, the old NOTE segment contains an entry with a
prstatus_t structure, plus other optionally-present entries describing the
LWP, as follows:

prstatus_t n_type: NT_PRSTATUS. This structure contains things of
interest to a debugger from the operating system, such as the
general registers, signal dispositions, state, reason for
stopping, process-ID, and so forth. The prstatus_t structure
is defined in <sys/old_procfs.h>.

prfpregset_t n_type: NT_PRFPREG. This entry is present only if the LWP
used the floating-point hardware. It contains the floating-
point registers. The prfpregset_t structure is defined in
<sys/procfs_isa.h>.

gwindows_t n_type: NT_GWINDOWS. This entry is present only on a SPARC
machine and only if the system was unable to flush all of the
register windows to the stack. It contains all of the
unspilled register windows. The gwindows_t structure is
defined in <sys/regset.h>.

prxregset_t n_type: NT_PRXREG. This entry is no longer included in core
files, but is of historical note because in the past it was
included on SPARC-based systems. While since then the
prxregset_t and extended register sets have been defined on
other architectures, they do not emit this in the old note
section because there is no binary compatibility.

The new NOTE segment contains the following entries. Each has entry name
CORE and presents the contents of a system structure:

psinfo_t n_type: NT_PSINFO. This structure contains information of
interest to the ps(1) command, such as process status, CPU
usage, nice value, controlling terminal, user-ID, process-ID,
the name of the executable, and so forth. The psinfo_t
structure is defined in <sys/procfs.h>

pstatus_t n_type: NT_PSTATUS. This structure contains things of
interest to a debugger from the operating system, such as
pending signals, state, process-ID, and so forth. The
pstatus_t structure is defined in <sys/procfs.h>.

char[] n_type: NT_PLATFORM. This entry contains a string describing
the specific model of the hardware platform on which this core
file was created. This information is the same as provided by
sysinfo(2) when invoked with the command SI_PLATFORM.

auxv_t[] n_type: NT_AUXV. This entry contains the array of auxv_t
structures that was passed by the operating system as startup
information to the dynamic linker. Auxiliary vector
information is defined in <sys/auxv.h>.

struct utsname
n_type: NT_UTSNAME. This structure contains the system
information that would have been returned to the process if it
had performed a uname(2) system call prior to dumping core.
The utsname structure is defined in <sys/utsname.h>.

pcred_t n_type: NT_PRCRED. This structure contains the process
credentials, including the real, saved, and effective user and
group IDs. The pcred_t structure is defined in
<sys/procfs.h>. Following the structure is an optional array
of supplementary group IDs. The total number of supplementary
group IDs is given by the pr_ngroups member of the pcred_t
structure, and the structure includes space for one
supplementary group. If pr_ngroups is greater than 1, there
is `pr_ngroups - 1' gid_t items following the structure;
otherwise, there is no additional data.

char[] n_type: NT_ZONENAME. This entry contains a string which
describes the name of the zone in which the process was
running. See zones(7). The information is the same as
provided by getzonenamebyid(3C) when invoked with the
numerical ID returned by getzoneid(3C).

prfdinfo_core_t
n_type: NT_FDINFO. This structure contains information about
any open file descriptors, including the path, flags, and
stat(2) information. The prfdinfo_core_t structure is defined
in <sys/procfs.h>.

struct ssd[]
n_type: NT_LDT. This entry is present only on an 32-bit x86
machine and only if the process has set up a Local Descriptor
Table (LDT). It contains an array of structures of type
struct ssd, each of which was typically used to set up the %gs
segment register to be used to fetch the address of the
current thread information structure in a multithreaded
process. The ssd structure is defined in <sys/sysi86.h>.

core_content_t
n_type: NT_CONTENT. This optional entry indicates which parts
of the process image are specified to be included in the core
file. See coreadm(8).

prsecflags_t
n_type: NT_SECFLAGS. This entry contains the process
security-flags, see security-flags(7), proc(5), and
psecflags(1) for more information.

prupanic_t n_type: NT_UPANIC. This entry is included if a process
terminated through the upanic(2) system call. It is defined
in <sys/procfs.h>.

The pru_version member indicates the current revision of the
structure, which is expected to be PRUPANIC_VERSION_1 (1).
The pru_flags member will be set to the bitwise-inclusive-OR
of the following fields:

PRUPANIC_FLAG_MSG_VALID Indicates that pru_data member
has valid contents and that the
process provided a message in
the upanic(2) call .

PRUPANIC_FLAG_MSG_ERROR Indicates that the calling
process attempted to include a
message; however, the provided
address of the message did not
point to valid memory.

PRUPANIC_FLAG_MSG_TRUNC Indicates that the calling
process included a message;
however, the message it wanted
to provide was larger than the
current message length.
The pru_data array contains binary data that the terminating
process used to indicate that the reason why it panicked.
This member should be ignored if the PRUPANIC_FLAG_MSG_VALID
flag is not set in pru_flags. While it is recommended that
processes terminate with an ASCII string, consumers of this
should not assume that the binary data is made of of printable
characters.

For each active and zombie LWP in the process, the new NOTE segment
contains an entry with an lwpsinfo_t structure plus, for a non-zombie LWP,
an entry with an lwpstatus_t structure, plus other optionally-present
entries describing the LWP, as follows. A zombie LWP is a non-detached LWP
that has terminated but has not yet been reaped by another LWP in the same
process.

lwpsinfo_t n_type: NT_LWPSINFO. This structure contains information of
interest to the ps(1) command, such as LWP status, CPU usage,
nice value, LWP-ID, and so forth. The lwpsinfo_t structure is
defined in <sys/procfs.h>. This is the only entry present for
a zombie LWP.

lwpstatus_t n_type: NT_LWPSTATUS. This structure contains things of
interest to a debugger from the operating system, such as the
general registers, the floating point registers, state, reason
for stopping, LWP-ID, and so forth. The lwpstatus_t structure
is defined in <sys/procfs.h>. gwindows_t n_type: NT_GWINDOWS.
This entry is present only on a SPARC machine and only if the
system was unable to flush all of the register windows to the
stack. It contains all of the unspilled register windows.
The gwindows_t structure is defined in <sys/regset.h>.

prxregset_t n_type: NT_PRXREG. This entry is present only if the machine
has extra register state associated with it. It contains the
extra register state. The prxregset_t structure is defined in
<sys/procfs_isa.h>; however applications should include
<procfs.h> to get access to it. On most architectures the
prxregset_t is opaque and of variable size. proc(5) discusses
the structure of the extended register set for each supported
architecture.

asrset_t asrset_t n_type: NT_ASRS. This entry is present only on a
SPARC V9 machine and only if the process is a 64-bit process.
It contains the ancillary state registers for the LWP. The
asrset_t asrset_t structure is defined in <sys/regset.h>.

psinfo_t n_type: NT_SPYMASTER. This entry is present only for an agent
LWP and contains the psinfo_t of the process that created the
agent LWP. See the proc(5) description of the spymaster entry
for more details.

Depending on the coreadm(8) settings, the section header of an ELF core
file can contain entries for CTF, DWARF debug information, symbol table,
and string table sections. The sh_addr fields are set to the base address
of the first mapping of the load object that they came from to. This can
be used to match those sections with the corresponding load object.

The size of the core file created by a process can be controlled by the
user (see getrlimit(2))

NAME

DESCRIPTION

SEE ALSO