Rewrite: ALL HAIL ELF

Mention the KERN_NOSUIDCOREDUMP sysctl(3)

ok deraadt@

1 files changed, 68 insertions, 99 deletions

diff --git a/share/man/man5/core.5 b/share/man/man5/core.5
index ec8f3e4606a..fb431d69277 100644
--- a/share/man/man5/core.5
+++ b/share/man/man5/core.5
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: core.5,v 1.19 2015/09/10 17:55:21 schwarze Exp $
+.\"	$OpenBSD: core.5,v 1.20 2016/08/16 04:14:34 guenther Exp $
 .\"	$NetBSD: core.5,v 1.4 1994/11/30 19:31:11 jtc Exp $
 .\"
 .\" Copyright (c) 1980, 1991, 1993
@@ -30,27 +30,32 @@
 .\"
 .\"     @(#)core.5	8.3 (Berkeley) 12/11/93
 .\"
-.Dd $Mdocdate: September 10 2015 $
+.Dd $Mdocdate: August 16 2016 $
 .Dt CORE 5
 .Os
 .Sh NAME
 .Nm core
 .Nd memory image file format
 .Sh SYNOPSIS
-.In sys/param.h
-.In sys/core.h
+.In sys/types.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 sigaction 2 ) .
-This memory image is written to a file named
+.Pp
+By default, this memory image is written to a file named
 .Pa programname.core
 in the working directory, provided the terminated process had write
-permission in the directory, 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 . )
+permission in the directory,
+and the terminated process either had an effective user ID of zero or
+had never changed user or group ID.
+See the description of
+.Dv KERN_NOSUIDCOREDUMP
+in
+.Xr sysctl 3
+for other options.
 .Pp
 The maximum size of a
 .Pa programname.core
@@ -60,99 +65,59 @@ Files which would be larger than the limit are not created.
 .Pp
 The
 .Pa programname.core
-file consists of the u-area, whose size (in pages) is defined by the
-.Dv UPAGES
-manifest in the
-.In machine/param.h
-file.
-The u-area starts with a
-.Fa user
-structure as given in
-.In sys/user.h .
-The remainder of the
-.Pa programname.core
-file consists of the data pages followed by the stack pages of the
-process image.
-The amount of data space image in the
-.Pa programname.core
-file is given (in pages) by the variable
-.Fa u_dsize
-in the u-area.
-The amount of stack image in the core file is given (in pages) by the variable
-.Fa u_ssize
-in the u-area.
-The size of a
-.Dq page
-is given by the constant
-.Dv PAGE_SIZE ,
-defined in
-.In machine/param.h .
-The
-.Fa user
-structure is defined as:
-.Bd -unfilled -offset indent
-struct	user {
-	struct	pcb u_pcb;
-
-	struct	pstats u_stats;
-
-	/*
-	 * Remaining fields only for core dump and/or ptrace--
-	 * not valid at other times!
-	 */
-	struct	kinfo_proc u_kproc;
-	struct	md_coredump u_md;
-};
-.Ed
-.Pp
-.Fa md_coredump
-is defined in the header file
-.In machine/pcb.h .
+file is in the ELF binary file format with an
+.Va e_type
+of
+.Dv ET_CORE .
+It has no section header table and a segment header that contains
+.Dv PT_LOAD
+and
+.Dv PT_NOTE
+segments that describe the state of the process when terminated.
 .Pp
-The on-disk core file consists of a header followed by a number of segments.
-Each segment is preceded by a
-.Fa coreseg
-structure giving the segment's type,
-the virtual address where the bits resided in process address space
-and the size of the segment.
+The
+.Dv PT_LOAD
+segments hold images of the process memory when it was terminated.
+Device mappings are excluded,
+as are read-only mappings that do not have private mapping changes.
+Each segment's
+.Va p_vaddr ,
+.Va p_memsz ,
+and
+.Va p_flags
+specify the address, size, and access protection of the memory
+segment it describes.
 .Pp
-The core header 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 -unfilled -offset indent
-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
-.Bd -unfilled -offset indent
-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->p_comm */
-	u_int32_t c_signo;		/* Killing signal */
-	u_long	c_ucode;		/* Hmm ? */
-	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
+The
+.Dv PT_NOTE
+segment contains notes describing the kernel state and CPU registers
+of each thread in the process.
+Note describing the process as a whole have the name
+.Dq OpenBSD
+An
+.Dv NT_OPENBSD_PROCINFO
+note is included containing an
+.Vt elfcore_procinfo
+structure with information about the kernel state of the process.
+An
+.Dv NT_OPENBSD_AUXV
+note is included containing a copy of the original process environment strings.
+On sparc and sparc64, an
+.Dv NT_OPENBSD_WCOOKIE
+note is included containing the process's
+.Sq window cookie .
 .Pp
-The core structure's
-.Fa c_midmag field
-is an a.out-style midmag number with a
-.Dv COREMAGIC
-magic number.
-and flags from the following list:
-.Bd -unfilled -offset indent
-#define CORE_CPU	1
-#define CORE_DATA	2
-#define CORE_STACK	4
-.Ed
+Notes describing the individual threads in the process have names
+in the format
+.Dq OpenBSD@%d
+where the suffix is the thread ID.
+For each thread, an
+.Dv NT_OPENBSD_REGS
+note is included containing the state of the regular registers of
+the thread and, on architectures other than luna88k and sgi, an
+.Dv NT_OPENBSD_FPREGS
+note is also included containing the state of the floating-point
+registers of the thread.
 .Sh SEE ALSO
 .Xr gdb 1 ,
 .Xr setrlimit 2 ,
@@ -163,6 +128,10 @@ A
 .Nm
 file format appeared in
 .At v3 .
+.Ox 2.0
+started using the ELF format for some architectures.
+All architectures used ELF starting in
+.Ox 5.4 .
 .Sh CAVEATS
 Programs which are started with either the set-user-ID or
 set-group-ID bits set,