diff options
Diffstat (limited to 'static/netbsd/man5/core.5')
| -rw-r--r-- | static/netbsd/man5/core.5 | 416 |
1 files changed, 416 insertions, 0 deletions
diff --git a/static/netbsd/man5/core.5 b/static/netbsd/man5/core.5 new file mode 100644 index 00000000..adce3e19 --- /dev/null +++ b/static/netbsd/man5/core.5 @@ -0,0 +1,416 @@ +.\" $NetBSD: core.5,v 1.33 2019/12/06 18:03:49 kamil 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. +.\" +.\" 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. 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 December 6, 2019 +.Dt CORE 5 +.Os +.Sh NAME +.Nm core +.Nd memory image file format +.Sh SYNOPSIS +.In sys/param.h +.Pp +For a.out-format core files: +.Pp +.In sys/core.h +.Pp +For ELF-format core files: +.Pp +.In sys/exec.h +.In sys/exec_elf.h +.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.<pid>.corename +(where <pid> 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 +.Dv ELF_NOTE_NETBSD_CORE_PROCINFO ( 1 ) , +and contains the following +structure: +.Bd -literal +struct netbsd_elfcore_procinfo { + 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 */ + int32_t cpi_siglwp; /* LWP target of killing signal */ +}; +.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 +.Dv 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 . +.It cpi_siglwp +LWP target of killing signal. +.El +.Pp +The second note with name +.Dq NetBSD-CORE +is a note type of +.Dv ELF_NOTE_NETBSD_CORE_AUXV ( 2 ) , +and contains an array of AuxInfo structures. +.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 +.Aq Pa machine/ptrace.h +header file. +.Ss A.OUT CORE FORMAT +The core file consists 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 +.In 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 { + uint32_t c_midmag; /* magic, id, flags */ + uint16_t c_hdrsize; /* Size of this header (machdep algn) */ + uint16_t c_seghdrsize; /* Size of a segment header */ + uint32_t c_nseg; /* # of core segments */ + char c_name[MAXCOMLEN+1]; /* Copy of p->p_comm */ + uint32_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 +.In 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 { + uint32_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 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 gdb 1 , +.Xr setrlimit 2 , +.Xr sysctl 3 , +.Xr a.out 5 , +.Xr elf 5 , +.Xr signal 7 , +.Xr sysctl 8 +.Sh HISTORY +A +.Nm core +file format appeared in +.At v1 . +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. +.Pp +The +.Dv cpi_siglwp +member of the +.Dv netbsd_elfcore_procinfo +structure first appeared in +.Nx 2.0 . +However it retained the procinfo version 1, +stored in +.Dv cpi_version . +.Pp +.Dv ELF_NOTE_NETBSD_CORE_AUXV +was added in +.Nx 8.0 . +.Sh BUGS +There is no standard location or name for the +CPU-dependent data structure stored in the +.Dv CORE_CPU +segment. |