CORE(4) File Formats and Configurations CORE(4)

core
process core file

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(1M). 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:

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(4)), 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(1M) 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(1M)), 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 BNOTE 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 BLWP 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 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.

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(5). 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(1M).
prsecflags_t
n_type: NT_SECFLAGS. This entry contains the process security-flags, see security-flags(5), proc(4), 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:

Indicates that pru_data member has valid contents and that the process provided a message in the upanic(2) call .
Indicates that the calling process attempted to include a message; however, the provided address of the message did not point to valid memory.
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>.
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(4) description of the spymaster entry for more details.

Depending on the coreadm(1M) 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))

elfdump(1), gcore(1), mdb(1), proc(1), ps(1), coreadm(1M), getrlimit(2), setrlimit(2), setuid(2), sysinfo(2), uname(2), upanic(2), getzoneid(3C), getzonenamebyid(3C), elf(3ELF), signal.h(3HEAD), a.out(4), proc(4), security-flags(5), zones(5)
August 3, 2021 OmniOS