path: root/usr/src/man/man4/core.4

'\"
.\" Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved.
.\" Copyright 2012 DEY Storage Systems, Inc.  All rights reserved.
.\" Copyright (c) 2013, Joyent, Inc. All rights reserved.
.\" Copyright 2020 OmniOS Community Edition (OmniOSce) Association.
.\" Copyright 2020 Oxide Computer Company
.\" 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]
.\"
.Dd October 31, 2020
.Dt CORE 4
.Os
.Sh NAME
.Nm core
.Nd process core file
.Sh 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
.Xr gcore 1
utility to a running process.
.Pp
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
.Xr mdb 1 ,
gdb, dbx, or  or by applying one of the
.Xr proc 1
tools.
.Pp
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
.Xr coreadm 1M .
By default, the global core file pattern is disabled and not used, and the
per-process core file pattern is set to
.Sy core .
Therefore, by default, the operating system attempts to create a core file named
.Pa core
in the process's current working directory.
.Pp
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
.Xr upanic 2
system call is used.
The list of signals that result in generating a core file is shown in
.Xr 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:
.Bl -bullet
.It
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.
.It
Core files owned by the user
.Sy nobody
will not be produced.
For example, core files generated for the superuser on an NFS directory are
owned by
.Sy nobody
and are, therefore, not written.
.It
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
.Pa /var/core/%n/core.%p ,
and no directory
.Pa /var/core/`uname -n`
has been created, no global core files are produced.
.It
If the destination directory is part of a filesystem that is mounted read-only.
.It
If the resource limit
.Dv RLIMIT_CORE
has been set to
.Sy 0
for the
process, no per-process core file is produced.
Refer to
.Xr setrlimit 2
and
.Xr ulimit 1
for more information on resource limits.
.It
If the core file name already exists in the destination directory and is not a
regular file
.Pq that is, is a symlink, block or character special-file, and so forth .
.It
If the kernel cannot open the destination file
.Dv O_EXCL ,
which can occur if same file is being created by another process simultaneously.
.It
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
.Xr coreadm 1M ,
at the risk of exposing secure information.
.El
.Pp
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.
.Pp
For ELF executable programs
.Po
see
.Xr a.out 4
.Pc ,
the core file generated is also an ELF file, containing ELF program and file
headers.
The
.Fa e_type
field in the file header has type
.Dv 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
.Xr coreadm 1M
are also part of the core image.
Each program header has its
.Fa 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
.Fa p_filesz
field set the same as
.Fa p_memsz ,
otherwise
.Fa p_filesz
is
.Sy zero .
.Pp
A mapping's data can be excluded due to the core file content settings
.Po
see
.Xr coreadm 1M
.Pc ,
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
.Dv PF_SUNW_FAILURE
flag set in its
.Fa p_flags
field; if the data is excluded because of a signal, the segment's
.Fa p_flags
field will have the
.Dv PF_SUNW_KILLED
flag set.
.Pp
The program headers of an
.Sy ELF
core file also contain entries for two
.Sy NOTE
segments, each containing several note entries as described below.
The note entry header and core file note type
.Pq Fa n_type
definitions are contained in
.In sys/elf.h .
The first
.Sy NOTE
segment exists for binary compatibility with old programs that deal with core
files.
It contains structures defined in
.In sys/old_procfs.h .
New programs should recognize and skip this
.Sy BNOTE
segment, advancing instead to the new
.Sy NOTE
segment.
The old
.Sy NOTE
segment is deleted from core files in a future release.
.Pp
The old
.Sy NOTE
segment contains the following entries.
Each has entry name
.Sy "CORE"
and presents the contents of a system structure:
.Bl -tag -width prpsinfo_t
.It Vt prpsinfo_t
.Fa n_type :
.Dv NT_PRPSINFO .
This entry contains information of interest to the
.Xr 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
.Vt prpsinfo_t
structure is defined in
.In sys/old_procfs.h .
.It Vt char[]
.Fa n_type :
.Dv 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
.Xr sysinfo 2
when invoked with the command
.Dv SI_PLATFORM .
.It Vt auxv_t[]
.Fa n_type :
.Dv NT_AUXV .
This entry contains the array of
.Vt Bauxv_t
structures that was passed by the operating system as startup information to
the dynamic linker.
Auxiliary vector information is defined in
.In sys/auxv.h .
.El
.Pp
Following these entries, for each active (non-zombie) light-weight process
.Pq LWP
in the process, the old
.Sy NOTE
segment contains an entry with a
.Vt prstatus_t
structure, plus other optionally-present entries describing the LWP, as follows:
.Bl -tag -width "prfpregset_t"
.It Vt prstatus_t
.Fa n_type :
.Dv 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
.Vt prstatus_t
structure is defined in
.In sys/old_procfs.h .
.It Vt prfpregset_t
.Fa n_type :
.Dv NT_PRFPREG .
This entry is present only if the
.Sy BLWP
used the floating-point hardware.
It contains the floating-point registers.
The
.Vt prfpregset_t
structure is defined in
.In sys/procfs_isa.h .
.It Vt gwindows_t
.Fa n_type :
.Dv 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
.Vt gwindows_t
structure is defined in
.In sys/regset.h .
.It Vt prxregset_t
.Fa n_type :
.Dv NT_PRXREG .
This entry is present only if the machine has extra register state associated
with it.
It contains the extra register state.
The
.Vt prxregset_t
structure is defined in
.Vt sys/procfs_isa.h .
.El
.Pp
The new
.Sy NOTE
segment contains the following entries.
Each has entry name
.Sy "CORE"
and presents the contents of a system structure:
.Bl -tag -width prxregset_t
.It Vt psinfo_t
.Fa n_type :
.Dv NT_PSINFO .
This structure contains information of interest to the
.Xr 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
.Vt psinfo_t
structure is defined in
.In sys/procfs.h
.It Vt pstatus_t
.Fa n_type :
.Dv 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
.Vt pstatus_t
structure is defined in
.In sys/procfs.h .
.It Vt char[]
.Fa n_type :
.Dv 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
.Xr sysinfo 2
when invoked with the command
.Dv SI_PLATFORM .
.It auxv_t[]
.Fa n_type :
.Dv NT_AUXV .
This entry contains the array of
.Vt auxv_t
structures that was passed by the operating system as startup information to
the dynamic linker.
Auxiliary vector information is defined in
.In sys/auxv.h .
.It Vt struct utsname
.Fa n_type :
.Dv NT_UTSNAME .
This structure contains the system information that would have been returned
to the process if it had performed a
.Xr uname 2
system call prior to dumping core.
The
.Vt utsname
structure is defined in
.In sys/utsname.h .
.It pcred_t
.Fa n_type :
.Dv NT_PRCRED .
This structure contains the process credentials, including the real, saved,
and effective user and group IDs.
The
.Vt pcred_t
structure is defined in
.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
.Fa pr_ngroups
member of the
.Vt pcred_t
structure, and the structure includes space for one supplementary group.
If
.Fa pr_ngroups
is greater than 1, there is
.So
.Fa pr_ngroups
- 1
.Sc
.Fa gid_t
items following the structure; otherwise, there is no additional data.
.It Vt char[]
.Fa n_type :
.Dv NT_ZONENAME .
This entry contains a string which describes the name of the zone in
which the process was running.
See
.Xr zones 5 .
The information is the same as provided by
.Xr getzonenamebyid 3C
when invoked with the numerical ID returned by
.Xr getzoneid 3C .
.It Vt prfdinfo_core_t
.Fa n_type :
.Dv NT_FDINFO .
This structure contains information about any open file descriptors, including
the path, flags, and
.Xr stat 2
information.
The
.Vt prfdinfo_core_t
structure is defined in
.In sys/procfs.h .
.It Vt struct ssd[]
.Fa n_type :
.Dv 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
.Pq LDT .
It contains an array of structures of type
.Vt struct ssd ,
each of which was typically used to set up the
.Sy %gs
segment register to be used to fetch the address of the current thread
information structure in a multithreaded process.
The
.Vt ssd
structure is defined in
.In sys/sysi86.h .
.It Vt core_content_t
.Fa n_type :
.Dv NT_CONTENT .
This optional entry indicates which parts of the process image are specified
to be included in the core file.
See
.Xr coreadm 1M .
.It Vt prsecflags_t
.Fa n_type :
.Dv NT_SECFLAGS .
This entry contains the process security-flags, see
.Xr security-flags 5 ,
.Xr proc 4 ,
and
.Xr psecflags 1
for more information.
.It Vt prupanic_t
.Fa n_type :
.Dv NT_UPANIC .
This entry is included if a process terminated through the
.Xr upanic 2
system call.
It is defined in
.In sys/procfs.h .
.Pp
The
.Fa pru_version
member indicates the current revision of the structure, which is expected to be
.Dv PRUPANIC_VERSION_1
.Pq 1 .
The
.Fa pru_flags
member will be set to the bitwise-inclusive-OR of the following fields:
.Bl -tag -offset indent -width PRUPANIC_FLAG_MSG_TRUNC
.It Dv PRUPANIC_FLAG_MSG_VALID
Indicates that
.Fa pru_data
member has valid contents and that the process provided a message in the
.Xr upanic 2
call .
.It Dv 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.
.It Dv 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.
.El
The
.Fa 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
.Dv PRUPANIC_FLAG_MSG_VALID
flag is not set in
.Fa 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.
.El
.Pp
For each active and zombie
.Sy LWP
in the process,
the new
.Sy NOTE
segment contains an entry with an
.Vt lwpsinfo_t
structure plus, for a non-zombie LWP, an entry with an
.Vt 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.
.Bl -tag -width "prxregset_t"
.It Vt lwpsinfo_t
.Fa n_type :
.Dv NT_LWPSINFO .
This structure contains information of interest to the
.Xr ps 1
command, such as LWP status, CPU usage, nice value, LWP-ID, and so forth.
The
.Vt lwpsinfo_t
structure is defined in
.In sys/procfs.h .
This is the only entry present for a zombie LWP.
.It lwpstatus_t
.Fa n_type :
.Dv 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
.Vt lwpstatus_t
structure is defined in
.In sys/procfs.h .
.Vt gwindows_t
.Fa n_type :
.Dv 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
.Vt gwindows_t
structure is defined in
.In sys/regset.h .
.It Vt prxregset_t
.Fa n_type :
.Dv NT_PRXREG .
This entry is present only if the machine has extra register state associated
with it.
It contains the extra register state.
The
.Vt prxregset_t
structure is defined in
.In sys/procfs_isa.h .
.It Vt asrset_t
\fB\fBasrset_t\fR\fR
.Fa n_type :
.Dv 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
.Vt asrset_t asrset_t
structure is defined in
.In sys/regset.h .
.It Vt psinfo_t
.Fa n_type :
.Dv NT_SPYMASTER .
This entry is present only for an agent LWP and contains the
.Vt psinfo_t
of the process that created the agent LWP.
See the
.Xr proc 4 description of the
.Sy spymaster
entry for more details.
.El
.Pp
Depending on the
.Xr coreadm 1M
settings, the section header of an ELF core file can contain entries for CTF,
symbol table, and string table sections.
The
.Fa 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.
.Pp
The size of the core file created by a process can be controlled by the user
.Po
see
.Xr getrlimit 2
.Pc
.Sh SEE ALSO
.Xr elfdump 1 ,
.Xr gcore 1 ,
.Xr mdb 1 ,
.Xr proc 1 ,
.Xr ps 1 ,
.Xr coreadm 1M ,
.Xr getrlimit 2 ,
.Xr setrlimit 2 ,
.Xr setuid 2 ,
.Xr sysinfo 2 ,
.Xr uname 2 ,
.Xr upanic 2 ,
.Xr getzoneid 3C ,
.Xr getzonenamebyid 3C ,
.Xr elf 3ELF ,
.Xr signal.h 3HEAD ,
.Xr a.out 4 ,
.Xr proc 4 ,
.Xr security-flags 5 ,
.Xr zones 5