]> git.ipfire.org Git - thirdparty/man-pages.git/blobdiff - man5/core.5
getgroups.2: ffix
[thirdparty/man-pages.git] / man5 / core.5
index 582886cabe9f7bd5007b01af6e089a69ccdde46a..d3efca3f86e0af10df38632fa0231c9065dc2396 100644 (file)
@@ -22,7 +22,7 @@
 .\" the source, must acknowledge the copyright and authors of this work.
 .\" %%%LICENSE_END
 .\"
-.TH CORE 5 2016-10-08 "Linux" "Linux Programmer's Manual"
+.TH CORE 5 2019-03-06 "Linux" "Linux Programmer's Manual"
 .SH NAME
 core \- core dump file
 .SH DESCRIPTION
@@ -36,14 +36,14 @@ This image can be used in a debugger (e.g.,
 to inspect the state of the program at the time that it terminated.
 A list of the signals which cause a process to dump core can be found in
 .BR signal (7).
-
+.PP
 A process can set its soft
 .B RLIMIT_CORE
 resource limit to place an upper limit on the size of the core dump file
 that will be produced if it receives a "core dump" signal; see
 .BR getrlimit (2)
 for details.
-
+.PP
 There are various circumstances in which a core dump file is
 not produced:
 .IP * 3
@@ -57,7 +57,7 @@ where
 is the ID of the process that dumped core,
 and is created in the current working directory.
 See below for details on naming.)
-Writing the core file will fail if the directory in which
+Writing the core file fails if the directory in which
 it is to be created is nonwritable,
 or if a file with the same name exists and
 is not writable
@@ -106,6 +106,23 @@ operation, and the description of the
 file in
 .BR proc (5).)
 .IP *
+.I /proc/sys/kernel/core_pattern
+is empty and
+.I /proc/sys/kernel/core_uses_pid
+contains the value 0.
+(These files are described below.)
+Note that if
+.I /proc/sys/kernel/core_pattern
+is empty and
+.I /proc/sys/kernel/core_uses_pid
+contains the value 1,
+core dump files will have names of the form
+.IR .pid ,
+and such files are hidden unless one uses the
+.BR ls (1)
+.I \-a
+option.
+.IP *
 (Since Linux 3.7)
 .\" commit 046d662f481830e652ac34cd112249adde16452a
 The kernel was configured without the
@@ -117,6 +134,15 @@ a core dump may exclude part of the address space of the process if the
 .BR madvise (2)
 .B MADV_DONTDUMP
 flag was employed.
+.PP
+On systems that employ
+.BR systemd (1)
+as the
+.I init
+framework, core dumps may instead be placed in a location determined by
+.BR systemd (1).
+See below for further details.
+.\"
 .SS Naming of core dump files
 By default, a core dump file is named
 .IR core ,
@@ -207,7 +233,7 @@ and
 .I /proc/sys/kernel/core_uses_pid
 (see below)
 is nonzero, then .PID will be appended to the core filename.
-
+.PP
 Paths are interpreted according to the settings that are active for the
 crashing process.
 That means the crashing process's mount namespace (see
@@ -216,7 +242,7 @@ its current working directory (found via
 .BR getcwd (2)),
 and its root directory (see
 .BR chroot (2)).
-
+.PP
 Since version 2.4, Linux has also provided
 a more primitive method of controlling
 the name of the core dump file.
@@ -227,7 +253,7 @@ file contains the value 0, then a core dump file is simply named
 If this file contains a nonzero value, then the core dump file includes
 the process ID in a name of the form
 .IR core.PID .
-
+.PP
 Since Linux 3.6,
 .\" 9520628e8ceb69fa9a4aee6b57f22675d9e1b709
 if
@@ -240,7 +266,7 @@ Since kernel 2.6.19, Linux supports an alternate syntax for the
 file.
 If the first character of this file is a pipe symbol (\fB|\fP),
 then the remainder of the line is interpreted as the command-line for
-a user-space program (or script) that is to be executed.
+a user-space program (or script) that is to be executed.
 Instead of being written to a disk file, the core dump is given as
 standard input to the program.
 Note the following points:
@@ -291,6 +317,11 @@ specifier to change to the location of the dumping process via
 Command-line arguments can be supplied to the
 program (since Linux 2.6.24),
 delimited by white space (up to a total line length of 128 bytes).
+.IP *
+The
+.B RLIMIT_CORE
+limit is not enforced for core dumps that are piped to a program
+via this mechanism.
 .\"
 .SS /proc/sys/kernel/core_pipe_limit
 When collecting core dumps via a pipe to a user-space program,
@@ -306,7 +337,7 @@ files prematurely.
 This in turn creates the
 possibility that a misbehaving collecting program can block
 the reaping of a crashed process by simply never exiting.
-
+.PP
 Since Linux 2.6.32,
 .\" commit a293980c2e261bd5b0d2a77340dd04f684caff58
 the
@@ -316,7 +347,7 @@ The value in this file defines how many concurrent crashing
 processes may be piped to user-space programs in parallel.
 If this value is exceeded, then those crashing processes above this value
 are noted in the kernel log and their core dumps are skipped.
-
+.PP
 A value of 0 in this file is special.
 It indicates that unlimited processes may be captured in parallel,
 but that no waiting will take place (i.e., the collecting
@@ -330,7 +361,7 @@ Since kernel 2.6.23, the Linux-specific
 file can be used to control which memory segments are written to the
 core dump file in the event that a core dump is performed for the
 process with the corresponding process ID.
-
+.PP
 The value in the file is a bit mask of memory mapping types (see
 .BR mmap (2)).
 If a bit is set in the mask, then memory mappings of the
@@ -379,15 +410,17 @@ kernel configuration option is enabled), and 5.
 This default can be modified at boot time using the
 .I coredump_filter
 boot option.
-
+.PP
 The value of this file is displayed in hexadecimal.
 (The default value is thus displayed as 33.)
-
+.PP
 Memory-mapped I/O pages such as frame buffer are never dumped, and
-virtual DSO pages are always dumped, regardless of the
+virtual DSO
+.RB ( vdso (7))
+pages are always dumped, regardless of the
 .I coredump_filter
 value.
-
+.PP
 A child process created via
 .BR fork (2)
 inherits its parent's
@@ -397,27 +430,110 @@ the
 .I coredump_filter
 value is preserved across an
 .BR execve (2).
-
+.PP
 It can be useful to set
 .I coredump_filter
 in the parent shell before running a program, for example:
-
+.PP
 .in +4n
-.nf
+.EX
 .RB "$" " echo 0x7 > /proc/self/coredump_filter"
 .RB "$" " ./some_program"
-.fi
+.EE
 .in
 .PP
 This file is provided only if the kernel was built with the
 .B CONFIG_ELF_CORE
 configuration option.
+.\"
+.SS Core dumps and systemd
+On systems using the
+.BR systemd (1)
+.I init
+framework, core dumps may be placed in a location determined by
+.BR systemd (1).
+To do this,
+.BR systemd (1)
+employs the
+.I core_pattern
+feature that allows piping core dumps to a program.
+One can verify this by checking whether core dumps are being piped to the
+.BR systemd\-coredump (8)
+program:
+.PP
+.in +4n
+.EX
+$ \fBcat /proc/sys/kernel/core_pattern\fP
+|/usr/lib/systemd/systemd\-coredump %P %u %g %s %t %c %e
+.EE
+.in
+.PP
+In this case, core dumps will be placed in the location configured for
+.BR systemd\-coredump (8),
+typically as
+.BR lz4 (1)
+compressed files in the directory
+.IR /var/lib/systemd/coredump/ .
+One can list the core dumps that have been recorded by
+.BR systemd\-coredump (8)
+using
+.BR coredumpctl (1):
+.PP
+.in +2n
+.EX
+$ \fBcoredumpctl list | tail -5\fP
+Wed 2017-10-11 22:25:30 CEST  2748 1000 1000 3 present  /usr/bin/sleep
+Thu 2017-10-12 06:29:10 CEST  2716 1000 1000 3 present  /usr/bin/sleep
+Thu 2017-10-12 06:30:50 CEST  2767 1000 1000 3 present  /usr/bin/sleep
+Thu 2017-10-12 06:37:40 CEST  2918 1000 1000 3 present  /usr/bin/cat
+Thu 2017-10-12 08:13:07 CEST  2955 1000 1000 3 present  /usr/bin/cat
+.EE
+.in
+.PP
+The information shown for each core dump includes the date and time
+of the dump, the PID, UID, and GID  of the dumping process,
+the signal number that caused the core dump,
+and the pathname of the executable that was being run by the dumped process.
+Various options to
+.BR coredumpctl (1)
+allow a specified coredump file to be pulled from the
+.BR systemd (1)
+location into a specified file.
+For example, to extract the core dump for PID 2955 shown above to a file named
+.IR core
+in the current directory, one could use:
+.PP
+.in +4n
+.EX
+$ \fBcoredumpctl dump 2955 \-o core\fP
+.EE
+.in
+.PP
+For more extensive details, see the
+.BR coredumpctl (1)
+manual page.
+.PP
+To disable the
+.BR systemd (1)
+mechanism that archives core dumps, restoring to something more like
+traditional Linux behavior, one can set an override for the
+.BR systemd (1)
+mechanism, using something like:
+.PP
+.in +2n
+.EX
+# echo "kernel.core_pattern=core.%p" > /etc/sysctl.d/50\-coredump.conf
+# /lib/systemd/systemd\-sysctl
+.EE
+.in
+.PP
+.\"
 .SH NOTES
 The
 .BR gdb (1)
 .I gcore
 command can be used to obtain a core dump of a running process.
-
+.PP
 In Linux versions up to and including 2.6.27,
 .\" Changed with commit 6409324b385f3f63a03645b4422e3be67348d922
 if a multithreaded process (or, more precisely, a process that
@@ -452,7 +568,7 @@ The following shell session demonstrates the use of this program
 .IR core_pattern_pipe_test ):
 .PP
 .in +4n
-.nf
+.EX
 .RB "$" " cc \-o core_pattern_pipe_test core_pattern_pipe_test.c"
 .RB "$" " su"
 Password:
@@ -471,11 +587,11 @@ argc[2]=<UID=1000>
 argc[3]=<GID=100>
 argc[4]=<sig=3>
 Total bytes in core dump: 282624
-.fi
+.EE
 .in
 .SS Program source
 \&
-.nf
+.EX
 /* core_pattern_pipe_test.c */
 
 #define _GNU_SOURCE
@@ -512,23 +628,24 @@ main(int argc, char *argv[])
     /* Display command\-line arguments given to core_pattern
        pipe program */
 
-    fprintf(fp, "argc=%d\\n", argc);
+    fprintf(fp, "argc=%d\en", argc);
     for (j = 0; j < argc; j++)
-        fprintf(fp, "argc[%d]=<%s>\\n", j, argv[j]);
+        fprintf(fp, "argc[%d]=<%s>\en", j, argv[j]);
 
     /* Count bytes in standard input (the core dump) */
 
     tot = 0;
     while ((nread = read(STDIN_FILENO, buf, BUF_SIZE)) > 0)
         tot += nread;
-    fprintf(fp, "Total bytes in core dump: %d\\n", tot);
+    fprintf(fp, "Total bytes in core dump: %d\en", tot);
 
     fclose(fp);
     exit(EXIT_SUCCESS);
 }
-.fi
+.EE
 .SH SEE ALSO
 .BR bash (1),
+.BR coredumpctl (1),
 .BR gdb (1),
 .BR getrlimit (2),
 .BR mmap (2),
@@ -537,4 +654,5 @@ main(int argc, char *argv[])
 .BR elf (5),
 .BR proc (5),
 .BR pthreads (7),
-.BR signal (7)
+.BR signal (7),
+.BR systemd\-coredump (8)