illumos: manual page: core.4

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

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 dbx(1) or mdb(1) 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. 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(1M), 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(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 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 array
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 array
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>.

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 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 array
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 array
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>.

prcred_t
n_type: NT_PRCRED. This structure contains the
process credentials, including the real, saved, and
effective user and group IDs. The prcred_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 prcred_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 array
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_t
n_type: NT_FDINFO. This structure contains
information about any open file descriptors,
including the path, flags, and stat(2) information.
The prfdinfo_t structure is defined in
<sys/procfs.h>.

struct ssd array
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).

Following these entries, 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
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 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.

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.

Depending on the coreadm(1M) settings, the section header of an ELF core
file can contain entries for CTF, 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