400 lines
14 KiB
Groff
400 lines
14 KiB
Groff
.\" $NetBSD: core.5,v 1.18 2002/10/02 11:00:53 wiz Exp $
|
|
.\"
|
|
.\" Copyright (c) 2002 The NetBSD Foundation, Inc.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to The NetBSD Foundation
|
|
.\" by Jason R. Thorpe.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by the NetBSD
|
|
.\" Foundation, Inc. and its contributors.
|
|
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
|
|
.\" contributors may be used to endorse or promote products derived
|
|
.\" from this software without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
|
|
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
|
|
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
|
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
|
|
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
|
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
|
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
|
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
|
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
|
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
|
.\" POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.\" Copyright (c) 1980, 1991, 1993
|
|
.\" The Regents of the University of California. All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by the University of
|
|
.\" California, Berkeley and its contributors.
|
|
.\" 4. Neither the name of the University nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" @(#)core.5 8.3 (Berkeley) 12/11/93
|
|
.\"
|
|
.Dd July 8, 2002
|
|
.Dt CORE 5
|
|
.Os
|
|
.Sh NAME
|
|
.Nm core
|
|
.Nd memory image file format
|
|
.Sh SYNOPSIS
|
|
.Fd #include \*[Lt]sys/param.h\*[Gt]
|
|
.Pp
|
|
For a.out-format core files:
|
|
.Pp
|
|
.Fd #include \*[Lt]sys/core.h\*[Gt]
|
|
.Pp
|
|
For ELF-format core files:
|
|
.Pp
|
|
.Fd #include \*[Lt]sys/exec.h\*[Gt]
|
|
.Fd #include \*[Lt]sys/exec_elf.h\*[Gt]
|
|
.Sh DESCRIPTION
|
|
A small number of signals which cause abnormal termination of a process
|
|
also cause a record of the process's in-core state to be written
|
|
to disk for later examination by one of the available debuggers
|
|
(see
|
|
.Xr signal 7 ) .
|
|
.Pp
|
|
This memory image is written to a file named from a per-process template;
|
|
provided the terminated process had write permission, and provided the
|
|
abnormality did not cause a system crash.
|
|
(In this event, the decision to save the core file is arbitrary, see
|
|
.Xr savecore 8 . )
|
|
The file is named from a per-process template, mapped to the sysctl
|
|
variable
|
|
.Em proc.\*[Lt]pid\*[Gt].corename
|
|
(where \*[Lt]pid\*[Gt] has to be replaced by the pid in decimal format of the
|
|
process).
|
|
This template is either an absolute or relative path name, in which format
|
|
characters can be used, preceded by the percent character
|
|
.Pq Dq \&% .
|
|
The following characters are recognized as format and substituted:
|
|
.Bl -tag -width 4n -offset indent -compact
|
|
.It Sy n
|
|
The process's name
|
|
.It Sy p
|
|
The PID of the process (in decimal)
|
|
.It Sy t
|
|
The process's creation date (a la
|
|
.Xr time 3 ,
|
|
in decimal)
|
|
.It Sy u
|
|
The login name, as returned by
|
|
.Xr getlogin 2
|
|
.El
|
|
.Pp
|
|
By default, the per-process template string points to the default core name
|
|
template, which is mapped to the sysctl variable
|
|
.Em kern.defcorename .
|
|
Changing this value on a live system will change the core name template for
|
|
all processes which didn't have a per-process template set.
|
|
The default value of the default core name template is
|
|
.Nm %n.core
|
|
and can be changed at compile-time with the kernel configuration option
|
|
.Cd options DEFCORENAME
|
|
(see
|
|
.Xr options 4 )
|
|
.Pp
|
|
The per-process template string is inherited on process creation, but is reset
|
|
to point to the default core name template on execution of a set-id binary.
|
|
.Pp
|
|
The maximum size of a core file is limited by
|
|
.Xr setrlimit 2 .
|
|
Files which would be larger than the limit are not created.
|
|
.Ss ELF CORE FORMAT
|
|
ELF-format core files are described by a standard ELF exec header and
|
|
a series of ELF program headers. Each program header describes a range
|
|
of the virtual address space of the process.
|
|
.Pp
|
|
In addition,
|
|
.Nx
|
|
ELF core files include an ELF note section which provides additional
|
|
information about the process. The first note in the note section
|
|
has a note name of
|
|
.Dq NetBSD-CORE
|
|
and a note type of
|
|
ELF_NOTE_NETBSD_CORE_PROCINFO (1), and contains the following
|
|
structure:
|
|
.Bd -literal
|
|
struct netbsd_elfcore_procinfo {
|
|
/* Version 1 fields start here. */
|
|
uint32_t cpi_version; /* netbsd_elfcore_procinfo version */
|
|
uint32_t cpi_cpisize; /* sizeof(netbsd_elfcore_procinfo) */
|
|
uint32_t cpi_signo; /* killing signal */
|
|
uint32_t cpi_sigcode; /* signal code */
|
|
uint32_t cpi_sigpend[4]; /* pending signals */
|
|
uint32_t cpi_sigmask[4]; /* blocked signals */
|
|
uint32_t cpi_sigignore[4]; /* blocked signals */
|
|
uint32_t cpi_sigcatch[4]; /* blocked signals */
|
|
int32_t cpi_pid; /* process ID */
|
|
int32_t cpi_ppid; /* parent process ID */
|
|
int32_t cpi_pgrp; /* process group ID */
|
|
int32_t cpi_sid; /* session ID */
|
|
uint32_t cpi_ruid; /* real user ID */
|
|
uint32_t cpi_euid; /* effective user ID */
|
|
uint32_t cpi_svuid; /* saved user ID */
|
|
uint32_t cpi_rgid; /* real group ID */
|
|
uint32_t cpi_egid; /* effective group ID */
|
|
uint32_t cpi_svgid; /* saved group ID */
|
|
uint32_t cpi_nlwps; /* number of LWPs */
|
|
int8_t cpi_name[32]; /* copy of p->p_comm */
|
|
/* Add version 2 fields below here. */
|
|
};
|
|
.Ed
|
|
.Pp
|
|
The fields of
|
|
.Fa struct netbsd_elfcore_procinfo
|
|
are as follows:
|
|
.Bl -tag -width cpi_sigignoreXX
|
|
.It cpi_version
|
|
The version of this structure. The current version is defined by
|
|
the NETBSD_ELFCORE_PROCINFO_VERSION constant.
|
|
.It cpi_cpisize
|
|
The size of this structure.
|
|
.It cpi_signo
|
|
Signal that caused the process to dump core.
|
|
.It cpi_sigcode
|
|
Signal-specific code, if any, corresponding to
|
|
.Va cpi_signo .
|
|
.It cpi_sigpend
|
|
A mask of signals pending delivery to the process. This may be
|
|
examined by copying it to a
|
|
.Fa sigset_t .
|
|
.It cpi_sigmask
|
|
The set of signals currently blocked by the process. This may be
|
|
examined by copying it to a
|
|
.Fa sigset_t .
|
|
.It cpi_sigignore
|
|
The set of signals currently being ignored by the process. This may be
|
|
examined by copying it to a
|
|
.Fa sigset_t .
|
|
.It cpi_sigcatch
|
|
The set of signals with registers signals handlers for the process. This
|
|
may be examined by copying it to a
|
|
.Fa sigset_t .
|
|
.It cpi_pid
|
|
Process ID of the process.
|
|
.It cpi_ppid
|
|
Process ID of the parent process.
|
|
.It cpi_pgrp
|
|
Process group ID of the process.
|
|
.It cpi_sid
|
|
Session ID of the process.
|
|
.It cpi_ruid
|
|
Real user ID of the process.
|
|
.It cpi_euid
|
|
Effective user ID of the process.
|
|
.It cpi_svuid
|
|
Saved user ID of the process.
|
|
.It cpi_rgid
|
|
Real group ID of the process.
|
|
.It cpi_egid
|
|
Effective group ID of the process.
|
|
.It cpi_svgid
|
|
Saved group ID of the process.
|
|
.It cpi_nlwps
|
|
Number of kernel-visible execution contexts (LWPs) of the process.
|
|
.It cpi_name
|
|
Process name, copied from the p_comm field of
|
|
.Fa struct proc .
|
|
.El
|
|
.Pp
|
|
The note section also contains additional notes for each
|
|
kernel-visible execution context of the process (LWP).
|
|
These notes have names of the form
|
|
.Dq NetBSD-CORE@nn
|
|
where
|
|
.Dq nn
|
|
is the LWP ID of the execution context, for example:
|
|
.Dq NetBSD-CORE@1 .
|
|
These notes contain register and other per-execution context
|
|
data in the same format as is used by the
|
|
.Xr ptrace 2
|
|
system call. The note types correspond to the
|
|
.Xr ptrace 2
|
|
request numbers that return the same data. For example,
|
|
a note with a note type of PT_GETREGS would contain a
|
|
.Fa struct reg
|
|
with the register contents of the execution context.
|
|
For a complete list of available
|
|
.Xr ptrace 2
|
|
request types for a given architecture, refer to that architecture's
|
|
.Pa \*[Lt]machine/ptrace.h\*[Gt]
|
|
header file.
|
|
.Ss A.OUT CORE FORMAT
|
|
.Pp
|
|
The core file contains of a core header followed by a number of
|
|
segments. Each segment is preceded by a core segment header.
|
|
Both the core header and core segment header are defined in
|
|
.Aq Pa sys/core.h .
|
|
.Pp
|
|
The core header,
|
|
.Fa struct core ,
|
|
specifies the lengths of the core header itself and
|
|
each of the following core segment headers to allow for any machine
|
|
dependent alignment requirements.
|
|
.Bd -literal
|
|
struct core {
|
|
u_int32_t c_midmag; /* magic, id, flags */
|
|
u_int16_t c_hdrsize; /* Size of this header (machdep algn) */
|
|
u_int16_t c_seghdrsize; /* Size of a segment header */
|
|
u_int32_t c_nseg; /* # of core segments */
|
|
char c_name[MAXCOMLEN+1]; /* Copy of p-\*[Gt]p_comm */
|
|
u_int32_t c_signo; /* Killing signal */
|
|
u_long c_ucode; /* Signal code */
|
|
u_long c_cpusize; /* Size of machine dependent segment */
|
|
u_long c_tsize; /* Size of traditional text segment */
|
|
u_long c_dsize; /* Size of traditional data segment */
|
|
u_long c_ssize; /* Size of traditional stack segment */
|
|
};
|
|
.Ed
|
|
.Pp
|
|
The fields of
|
|
.Fa struct core
|
|
are as follows:
|
|
.Bl -tag -width XXXc_seghdrsize
|
|
.It c_midmag
|
|
Core file machine ID, magic value, and flags.
|
|
These values may be extracted with the
|
|
.Fn CORE_GETMID ,
|
|
.Fn CORE_GETMAGIC ,
|
|
and
|
|
.Fn CORE_GETFLAG
|
|
macros. The machine ID values are listed in
|
|
.Aq Pa sys/exec_aout.h .
|
|
For a valid core file, the magic value in the header must be
|
|
.Dv COREMAGIC .
|
|
No flags are defined for the core header.
|
|
.It c_hdrsize
|
|
Size of this data structure.
|
|
.It c_seghdrsize
|
|
Size of a segment header.
|
|
.It c_nseg
|
|
Number of segments that follow this header.
|
|
.It c_name
|
|
Process name, copied from the p_comm field of
|
|
.Fa struct proc .
|
|
.It c_signo
|
|
Signal that caused the process to dump core.
|
|
.It c_ucode
|
|
Code associated with the signal.
|
|
.It c_cpusize
|
|
Size of the segment containing CPU-specific information.
|
|
This segment will have the
|
|
.Dv CORE_CPU
|
|
flag set.
|
|
.It c_tsize
|
|
Size of the segment containing the program text.
|
|
.It c_dsize
|
|
Size of the segment containing the program's traditional data area.
|
|
.It c_ssize
|
|
Size of the segment containing the program's traditional stack area.
|
|
This segment will have the
|
|
.Dv CORE_STACK
|
|
flag set.
|
|
.El
|
|
The header is followed by
|
|
.Fa c_nseg
|
|
segments, each of which is preceded with a segment header,
|
|
.Fa struct coreseg :
|
|
.Bd -literal
|
|
struct coreseg {
|
|
u_int32_t c_midmag; /* magic, id, flags */
|
|
u_long c_addr; /* Virtual address of segment */
|
|
u_long c_size; /* Size of this segment */
|
|
};
|
|
.Ed
|
|
.Pp
|
|
The fields of
|
|
.Fa struct coreseg
|
|
are as follows:
|
|
.Bl -tag -width XXXc_midmag
|
|
.It c_midmag
|
|
Core segment magic value and flags.
|
|
These values may be extracted with the
|
|
.Fn CORE_GETMAGIC
|
|
and
|
|
.Fn CORE_GETFLAG
|
|
macros.
|
|
The magic value in the segment header must be
|
|
.Dv CORESEGMAGIC .
|
|
Exactly one of of the flags
|
|
.Dv CORE_CPU ,
|
|
.Dv CORE_DATA ,
|
|
or
|
|
.Dv CORE_STACK
|
|
will be set to indicate the segment type.
|
|
.It c_addr
|
|
Virtual address of the segment in the program image.
|
|
Meaningless if the segment type is
|
|
.Dv CORE_CPU .
|
|
.It c_size
|
|
Size of the segment, not including this header.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr a.out 5 ,
|
|
.Xr elf 5 ,
|
|
.Xr gdb 1 ,
|
|
.Xr setrlimit 2 ,
|
|
.Xr sysctl 3 ,
|
|
.Xr signal 7 ,
|
|
.Xr sysctl 8
|
|
.Sh HISTORY
|
|
A
|
|
.Nm core
|
|
file format appeared in
|
|
.At v6 .
|
|
The
|
|
.Nx
|
|
a.out core file format was introduced in
|
|
.Nx 1.0 .
|
|
The
|
|
.Nx
|
|
ELF core file format was introduced in
|
|
.Nx 1.6 .
|
|
.Pp
|
|
In releases previous to
|
|
.Nx 1.6 ,
|
|
ELF program images produced a.out-format core files.
|
|
.Sh BUGS
|
|
There is no standard location or name for the
|
|
CPU-dependent data structure stored in the
|
|
.Dv CORE_CPU
|
|
segment.
|