1502 Remove conversion cruft from manpages

[unleashed.git] / usr / src / man / man4 / core.4

'\" te
.\" Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved.
.\" Copyright 1989 AT&T
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH CORE 4 "May 13, 2008"
.SH NAME
core \- process core file
.SH DESCRIPTION
.sp
.LP
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 \fBgcore\fR(1) utility to a running process.
.sp
.LP
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 \fBdbx\fR(1) or \fBmdb\fR(1) or by applying one of the
\fBproc\fR(1) tools.
.sp
.LP
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
\fBcoreadm\fR(1M). By default, the global core file pattern is disabled and not
used, and the per-process core file pattern is set to \fBcore\fR. Therefore, by
default, the operating system attempts to create a core file named \fBcore\fR
in the process's current working directory.
.sp
.LP
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 \fBsignal.h\fR(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:
.RS +4
.TP
.ie t \(bu
.el 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.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Core files owned by the user \fBnobody\fR will not be produced. For example,
core files generated for the superuser on an NFS directory are owned by
\fBnobody\fR and are, therefore, not written.
.RE
.RS +4
.TP
.ie t \(bu
.el 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 \fB/var/core/%n/core.%p\fR, and no directory \fB/var/core/`uname -n`\fR
has been created, no global core files are produced.
.RE
.RS +4
.TP
.ie t \(bu
.el o
If the destination directory is part of a filesystem that is mounted read-only.
.RE
.RS +4
.TP
.ie t \(bu
.el o
If the resource limit \fBRLIMIT_CORE\fR has been set to \fB0\fR for the
process, no per-process core file is produced. Refer to \fBsetrlimit\fR(2) and
\fBulimit\fR(1) for more information on resource limits.
.RE
.RS +4
.TP
.ie t \(bu
.el 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).
.RE
.RS +4
.TP
.ie t \(bu
.el o
If the kernel cannot open the destination file \fBO_EXCL\fR, which can occur if
same file is being created by another process simultaneously.
.RE
.RS +4
.TP
.ie t \(bu
.el 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 \fBcoreadm\fR(1M), at the risk of
exposing secure information.
.RE
.sp
.LP
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.
.sp
.LP
For ELF executable programs (see \fBa.out\fR(4)), the core file generated is
also an ELF file, containing ELF program and file headers. The \fBe_type\fR
field in the file header has type \fBET_CORE\fR. 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
\fBcoreadm\fR(1M) are also part of the core image. Each program header has its
\fBp_memsz\fR field set to the size of the mapping. The program headers that
represent mappings whose data is included in the core file have their
\fBp_filesz\fR field set the same as \fBp_memsz\fR, otherwise \fBp_filesz\fR is
\fBzero\fR.
.sp
.LP
A mapping's data can be excluded due to the core file content settings (see
\fBcoreadm\fR(1M)), or due to some failure. If the data is excluded because of
a failure, the program header entry will have the \fBPF_SUNW_FAILURE\fR flag
set in its \fBp_flags\fR field.
.sp
.LP
The program headers of an \fBELF\fR core file also contain entries for two
\fBNOTE\fR segments, each containing several note entries as described below.
The note entry header and core file note type (\fBn_type\fR) definitions are
contained in <\fBsys/elf.h\fR>. The first \fBNOTE\fR segment exists for binary
compatibility with old programs that deal with core files. It contains
structures defined in <\fBsys/old_procfs.h\fR>. New programs should recognize
and skip this \fBNOTE\fR segment, advancing instead to the new \fBNOTE\fR
segment. The old \fBNOTE\fR segment is deleted from core files in a future
release.
.sp
.LP
The old \fBNOTE\fR segment contains the following entries. Each has entry name
\fB"CORE"\fR and presents the contents of a system structure:
.sp
.ne 2
.na
\fB\fBprpsinfo_t\fR\fR
.ad
.RS 16n
\fBn_type\fR: \fBNT_PRPSINFO\fR. This entry contains information of interest to
the \fBps\fR(1) command, such as process status, \fBCPU\fR usage, \fBnice\fR
value, controlling terminal, user-ID, process-ID, the name of the executable,
and so forth. The \fBprpsinfo_t\fR structure is defined in
<\fBsys/old_procfs.h\fR>.
.RE

.sp
.ne 2
.na
\fB\fBchar\fR array\fR
.ad
.RS 16n
\fBn_type\fR: \fBNT_PLATFORM\fR. 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 \fBsysinfo\fR(2) when invoked with
the command \fBSI_PLATFORM\fR.
.RE

.sp
.ne 2
.na
\fB\fBauxv_t\fR array\fR
.ad
.RS 16n
\fBn_type\fR: \fBNT_AUXV\fR. This entry contains the array of \fBauxv_t\fR
structures that was passed by the operating system as startup information to
the dynamic linker. Auxiliary vector information is defined in
<\fBsys/auxv.h\fR>.
.RE

.sp
.LP
Following these entries, for each active (non-zombie) light-weight process
(LWP) in the process, the old \fBNOTE\fR segment contains an entry with a
\fBprstatus_t\fR structure, plus other optionally-present entries describing
the LWP, as follows:
.sp
.ne 2
.na
\fB\fBprstatus_t\fR\fR
.ad
.RS 16n
\fBn_type\fR: \fBNT_PRSTATUS\fR. 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
\fBprstatus_t\fR structure is defined in <\fBsys/old_procfs.h\fR>.
.RE

.sp
.ne 2
.na
\fB\fBprfpregset_t\fR\fR
.ad
.RS 16n
\fBn_type\fR: \fBNT_PRFPREG\fR. This entry is present only if the \fBLWP\fR
used the floating-point hardware. It contains the floating-point registers. The
\fBprfpregset_t\fR structure is defined in <\fBsys/procfs_isa.h\fR>.
.RE

.sp
.ne 2
.na
\fB\fBgwindows_t\fR\fR
.ad
.RS 16n
\fBn_type\fR: \fBNT_GWINDOWS\fR. 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 \fBgwindows_t\fR
structure is defined in <\fBsys/regset.h\fR>.
.RE

.sp
.ne 2
.na
\fB\fBprxregset_t\fR\fR
.ad
.RS 16n
\fBn_type\fR: \fBNT_PRXREG\fR. This entry is present only if the machine has
extra register state associated with it. It contains the extra register state.
The \fBprxregset_t\fR structure is defined in <\fBsys/procfs_isa.h\fR>.
.RE

.sp
.LP
The new \fBNOTE\fR segment contains the following entries. Each has entry name
"\fBCORE\fR" and presents the contents of a system structure:
.sp
.ne 2
.na
\fB\fBpsinfo_t\fR\fR
.ad
.RS 20n
\fBn_type\fR: \fBNT_PSINFO\fR. This structure contains information of interest
to the \fBps\fR(1) command, such as process status, \fBCPU\fR usage, \fBnice\fR
value, controlling terminal, user-ID, process-ID, the name of the executable,
and so forth. The \fBpsinfo_t\fR structure is defined in <\fBsys/procfs.h\fR>.
.RE

.sp
.ne 2
.na
\fB\fBpstatus_t\fR\fR
.ad
.RS 20n
\fBn_type\fR: \fBNT_PSTATUS\fR. This structure contains things of interest to a
debugger from the operating system, such as pending signals, state, process-ID,
and so forth. The \fBpstatus_t\fR structure is defined in <\fBsys/procfs.h\fR>.
.RE

.sp
.ne 2
.na
\fB\fBchar\fR array\fR
.ad
.RS 20n
\fBn_type\fR: \fBNT_PLATFORM\fR. 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 \fBsysinfo\fR(2) when invoked with
the command \fBSI_PLATFORM\fR.
.RE

.sp
.ne 2
.na
\fB\fBauxv_t\fR array\fR
.ad
.RS 20n
\fBn_type\fR: \fBNT_AUXV\fR. This entry contains the array of \fBauxv_t\fR
structures that was passed by the operating system as startup information to
the dynamic linker. Auxiliary vector information is defined in
<\fBsys/auxv.h\fR>.
.RE

.sp
.ne 2
.na
\fB\fBstruct utsname\fR\fR
.ad
.RS 20n
\fBn_type\fR: \fBNT_UTSNAME\fR. This structure contains the system information
that would have been returned to the process if it had performed a
\fBuname\fR(2) system call prior to dumping core. The \fButsname\fR structure
is defined in <\fBsys/utsname.h\fR>.
.RE

.sp
.ne 2
.na
\fB\fBprcred_t\fR\fR
.ad
.RS 20n
\fBn_type\fR: \fBNT_PRCRED\fR. This structure contains the process credentials,
including the real, saved, and effective user and group IDs. The \fBprcred_t\fR
structure is defined in <\fBaasys/procfs.h\fR>. Following the structure is an
optional array of supplementary group IDs. The total number of supplementary
group IDs is given by the \fBpr_ngroups\fR member of the \fBprcred_t\fR
structure, and the structure includes space for one supplementary group. If
\fBpr_ngroups\fR is greater than 1, there is \fBpr_ngroups - 1\fR \fBgid_t\fR
items following the structure; otherwise, there is no additional data.
.RE

.sp
.ne 2
.na
\fB\fBchar array\fR\fR
.ad
.RS 20n
\fBn_type\fR: \fBNT_ZONENAME\fR. This entry contains a string which describes
the name of the zone in which the process was running. See \fBzones\fR(5). The
information is the same as provided by \fBgetzonenamebyid\fR(3C) when invoked
with the numerical ID returned by \fBgetzoneid\fR(3C).
.RE

.sp
.ne 2
.na
\fB\fBstruct ssd\fR array\fR
.ad
.RS 20n
\fBn_type\fR: \fBNT_LDT\fR. 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 \fBstruct ssd\fR, each of which was typically
used to set up the \fB%gs\fR segment register to be used to fetch the address
of the current thread information structure in a multithreaded process. The
\fBssd\fR structure is defined in <\fBsys/sysi86.h\fR>.
.RE

.sp
.ne 2
.na
\fB\fBcore_content_t\fR\fR
.ad
.RS 20n
\fBn_type\fR: \fBNT_CONTENT\fR. This optional entry indicates which parts of
the process image are specified to be included in the core file. See
\fBcoreadm\fR(1M).
.RE

.sp
.LP
Following these entries, for each active and zombie \fBLWP\fR in the process,
the new \fBNOTE\fR segment contains an entry with an \fBlwpsinfo_t\fR structure
plus, for a non-zombie LWP, an entry with an \fBlwpstatus_t\fR 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.
.sp
.ne 2
.na
\fB\fBlwpsinfo_t\fR\fR
.ad
.RS 15n
\fBn_type\fR: \fBNT_LWPSINFO\fR. This structure contains information of
interest to the \fBps\fR(1) command, such as \fBLWP\fR status, \fBCPU\fR usage,
\fBnice\fR value, \fBLWP-ID\fR, and so forth. The \fBlwpsinfo_t\fR structure is
defined in <\fBsys/procfs.h\fR>. This is the only entry present for a zombie
LWP.
.RE

.sp
.ne 2
.na
\fB\fBlwpstatus_t\fR\fR
.ad
.RS 15n
\fBn_type\fR: \fBNT_LWPSTATUS\fR. 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, \fBLWP-ID\fR, and so
forth. The \fBlwpstatus_t\fR structure is defined in <\fBsys/procfs.h>\fR>.
.RE

.sp
.ne 2
.na
\fB\fBgwindows_t\fR\fR
.ad
.RS 15n
\fBn_type\fR: \fBNT_GWINDOWS\fR. 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 \fBgwindows_t\fR
structure is defined in \fB<sys/regset.h>\fR\&.
.RE

.sp
.ne 2
.na
\fB\fBprxregset_t\fR\fR
.ad
.RS 15n
\fBn_type\fR: \fBNT_PRXREG\fR. This entry is present only if the machine has
extra register state associated with it. It contains the extra register state.
The \fBprxregset_t\fR structure is defined in \fB<sys/procfs_isa.h>\fR\&.
.RE

.sp
.ne 2
.na
\fB\fBasrset_t\fR\fR
.ad
.RS 15n
\fBn_type\fR: \fBNT_ASRS\fR. 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 \fBLWP.\fR The \fBasrset_t\fR structure is defined in
\fB<sys/regset.h>\fR\&.
.RE

.sp
.LP
Depending on the \fBcoreadm\fR(1M) settings, the section header of an ELF core
file can contain entries for CTF, symbol table, and string table sections. The
\fBsh_addr\fR 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.
.sp
.LP
The size of the core file created by a process can be controlled by the user
(see \fBgetrlimit\fR(2)).
.SH SEE ALSO
.sp
.LP
\fBelfdump\fR(1), \fBgcore\fR(1), \fBmdb\fR(1), \fBproc\fR(1), \fBps\fR(1),
\fBcoreadm\fR(1M), \fBgetrlimit\fR(2), \fBsetrlimit\fR(2), \fBsetuid\fR(2),
\fBsysinfo\fR(2), \fBuname\fR(2), \fBgetzonenamebyid\fR(3C),
\fBgetzoneid\fR(3C), \fBelf\fR(3ELF), \fBsignal.h\fR(3HEAD), \fBa.out\fR(4),
\fBproc\fR(4), \fBzones\fR(5)
.sp
.LP
\fIANSI C Programmer's Guide\fR