Tribblix: 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.

prcwd_t n_type: NT_CWD. This entry describes information about
the current working directory of the process at the time
the core file is generated and information about the file
system that the current working directory is found on.
The prcwd_t is defined in <sys/procfs.h>.

The members of the prcwd_t include:

prcwd_fsid The file system ID. This is the same
data that is found in the f_fsid
member of the struct statvfs
structure obtained through
statvfs(2). The file system ID is
currently the device number (i.e. the
dev_t) and matches the mnt_major and
mnt_minor of the struct extmnttab
structure that is obtained through
getextmntent(3C).

prcwd_fsname A NUL-terminated string containing
the name of the file system itself,
e.g. "zfs", "tmpfs", etc. This is
the same as the f_bastype member of
the struct statvfs and mnt_fstype of
the struct mnttab.

prcwd_mntpt A NUL-terminated string that contains
the path where the file system
containing the current working
directory is mounted.

prcwd_mntspec A NUL-terminated string that is the
name of the mounted resource. This
may be a ZFS dataset, a synthetic
resource like "swap", "procfs", or
"bootfs", or the path to a particular
disk or file. This corresponds to
the mnt_special member of the struct
mnttab.

prcwd_cwd A NUL-terminated string containing
the current path of the process at
the time the core file was generated.

From the operating system's perspective, a path is often
just a NUL-terminated collection of bytes. This means it
is possible that a path may contain bytes that are not
printable or meaningful in the locale of a process that is
processing this particular structure.

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