diff options
Diffstat (limited to 'man5/core.5')
| -rw-r--r-- | man5/core.5 | 684 |
1 files changed, 0 insertions, 684 deletions
diff --git a/man5/core.5 b/man5/core.5 deleted file mode 100644 index 2fb7979da..000000000 --- a/man5/core.5 +++ /dev/null @@ -1,684 +0,0 @@ -.\" Copyright (c) 2006, 2008 by Michael Kerrisk <mtk.manpages@gmail.com> -.\" -.\" SPDX-License-Identifier: Linux-man-pages-copyleft -.\" -.TH core 5 (date) "Linux man-pages (unreleased)" -.SH NAME -core \- core dump file -.SH DESCRIPTION -The default action of certain signals is to cause a process to terminate -and produce a -.IR "core dump file" , -a file containing an image of the process's memory at -the time of termination. -This image can be used in a debugger (e.g., -.BR gdb (1)) -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). -.P -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. -.P -There are various circumstances in which a core dump file is -not produced: -.IP \[bu] 3 -The process does not have permission to write the core file. -(By default, the core file is called -.I core -or -.IR core.pid , -where -.I pid -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 fails if the directory in which -it is to be created is not writable, -or if a file with the same name exists and -is not writable -or is not a regular file -(e.g., it is a directory or a symbolic link). -.IP \[bu] -A (writable, regular) file with the same name as would be used for the -core dump already exists, but there is more than one hard link to that -file. -.IP \[bu] -The filesystem where the core dump file would be created is full; -or has run out of inodes; or is mounted read-only; -or the user has reached their quota for the filesystem. -.IP \[bu] -The directory in which the core dump file is to be created does -not exist. -.IP \[bu] -The -.B RLIMIT_CORE -(core file size) or -.B RLIMIT_FSIZE -(file size) resource limits for the process are set to zero; see -.BR getrlimit (2) -and the documentation of the shell's -.I ulimit -command -.RI ( limit -in -.BR csh (1)). -However, -.B RLIMIT_CORE -will be ignored if the system is configured to pipe core dumps to a program. -.IP \[bu] -The binary being executed by the process does not have read -permission enabled. -(This is a security measure to -ensure that an executable whose contents are not readable -does not produce a\[em]possibly readable\[em]core dump containing -an image of the executable.) -.IP \[bu] -The process is executing a set-user-ID (set-group-ID) program -that is owned by a user (group) other than the real user (group) -ID of the process, -or the process is executing a program that has file capabilities (see -.BR capabilities (7)). -(However, see the description of the -.BR prctl (2) -.B PR_SET_DUMPABLE -operation, and the description of the -.I /proc/sys/fs/suid_dumpable -.\" FIXME . Perhaps relocate discussion of /proc/sys/fs/suid_dumpable -.\" and PR_SET_DUMPABLE to this page? -file in -.BR proc (5).) -.IP \[bu] -.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 \[bu] -(Since Linux 3.7) -.\" commit 046d662f481830e652ac34cd112249adde16452a -The kernel was configured without the -.B CONFIG_COREDUMP -option. -.P -In addition, -a core dump may exclude part of the address space of the process if the -.BR madvise (2) -.B MADV_DONTDUMP -flag was employed. -.P -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 , -but the -.I /proc/sys/kernel/core_pattern -file (since Linux 2.6 and 2.4.21) -can be set to define a template that is used to name core dump files. -The template can contain % specifiers which are substituted -by the following values when a core file is created: -.P -.RS 4 -.PD 0 -.TP 4 -%% -A single % character. -.TP -%c -Core file size soft resource limit of crashing process (since Linux 2.6.24). -.TP -%d -.\" Added in git commit 12a2b4b2241e318b4f6df31228e4272d2c2968a1 -Dump mode\[em]same as value returned by -.BR prctl (2) -.B PR_GET_DUMPABLE -(since Linux 3.7). -.TP -%e -The process or thread's -.I comm -value, which typically is the same as the executable filename -(without path prefix, and truncated to a maximum of 15 characters), -but may have been modified to be something different; -see the discussion of -.IR /proc/ pid /comm -and -.IR /proc/ pid /task/ tid /comm -in -.BR proc (5). -.TP -%E -Pathname of executable, -with slashes (\[aq]/\[aq]) replaced by exclamation marks (\[aq]!\[aq]) -(since Linux 3.0). -.TP -%g -Numeric real GID of dumped process. -.TP -%h -Hostname (same as \fInodename\fP returned by \fBuname\fP(2)). -.TP -%i -TID of thread that triggered core dump, -as seen in the PID namespace in which the thread resides -.\" commit b03023ecbdb76c1dec86b41ed80b123c22783220 -(since Linux 3.18). -.TP -%I -TID of thread that triggered core dump, as seen in the initial PID namespace -.\" commit b03023ecbdb76c1dec86b41ed80b123c22783220 -(since Linux 3.18). -.TP -%p -PID of dumped process, -as seen in the PID namespace in which the process resides. -.TP -%P -.\" Added in git commit 65aafb1e7484b7434a0c1d4c593191ebe5776a2f -PID of dumped process, as seen in the initial PID namespace -(since Linux 3.12). -.TP -%s -Number of signal causing dump. -.TP -%t -Time of dump, expressed as seconds since the -Epoch, 1970-01-01 00:00:00 +0000 (UTC). -.TP -%u -Numeric real UID of dumped process. -.PD -.RE -.P -A single % at the end of the template is dropped from the -core filename, as is the combination of a % followed by any -character other than those listed above. -All other characters in the template become a literal -part of the core filename. -The template may include \[aq]/\[aq] characters, which are interpreted -as delimiters for directory names. -The maximum size of the resulting core filename is 128 bytes (64 bytes -before Linux 2.6.19). -The default value in this file is "core". -For backward compatibility, if -.I /proc/sys/kernel/core_pattern -does not include -.I %p -and -.I /proc/sys/kernel/core_uses_pid -(see below) -is nonzero, then .PID will be appended to the core filename. -.P -Paths are interpreted according to the settings that are active for the -crashing process. -That means the crashing process's mount namespace (see -.BR mount_namespaces (7)), -its current working directory (found via -.BR getcwd (2)), -and its root directory (see -.BR chroot (2)). -.P -Since Linux 2.4, Linux has also provided -a more primitive method of controlling -the name of the core dump file. -If the -.I /proc/sys/kernel/core_uses_pid -file contains the value 0, then a core dump file is simply named -.IR core . -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 . -.P -Since Linux 3.6, -.\" 9520628e8ceb69fa9a4aee6b57f22675d9e1b709 -if -.I /proc/sys/fs/suid_dumpable -is set to 2 ("suidsafe"), the pattern must be either an absolute pathname -(starting with a leading \[aq]/\[aq] character) or a pipe, as defined below. -.SS Piping core dumps to a program -Since Linux 2.6.19, Linux supports an alternate syntax for the -.I /proc/sys/kernel/core_pattern -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. -.P -Since Linux 5.3.0, -.\" commit 315c69261dd3fa12dbc830d4fa00d1fad98d3b03 -the pipe template is split on spaces into an argument list -.I before -the template parameters are expanded. -In earlier kernels, the template parameters are expanded first and -the resulting string is split on spaces into an argument list. -This means that in earlier kernels executable names added by the -.I %e -and -.I %E -template parameters could get split into multiple arguments. -So the core dump handler needs to put the executable names as the last -argument and ensure it joins all parts of the executable name using spaces. -Executable names with multiple spaces in them are not correctly represented -in earlier kernels, -meaning that the core dump handler needs to use mechanisms to find -the executable name. -.P -Instead of being written to a file, the core dump is given as -standard input to the program. -Note the following points: -.IP \[bu] 3 -The program must be specified using an absolute pathname (or a -pathname relative to the root directory, \fI/\fP), -and must immediately follow the '|' character. -.IP \[bu] -The command-line arguments can include any of -the % specifiers listed above. -For example, to pass the PID of the process that is being dumped, specify -.I %p -in an argument. -.IP \[bu] -The process created to run the program runs as user and group -.IR root . -.IP \[bu] -Running as -.I root -does not confer any exceptional security bypasses. -Namely, LSMs (e.g., SELinux) are still active and may prevent the handler -from accessing details about the crashed process via -.IR /proc/ pid. -.IP \[bu] -The program pathname is interpreted with respect to the initial mount namespace -as it is always executed there. -It is not affected by the settings -(e.g., root directory, mount namespace, current working directory) -of the crashing process. -.IP \[bu] -The process runs in the initial namespaces -(PID, mount, user, and so on) -and not in the namespaces of the crashing process. -One can utilize specifiers such as -.I %P -to find the right -.IR /proc/ pid -directory and probe/enter the crashing process's namespaces if needed. -.IP \[bu] -The process starts with its current working directory -as the root directory. -If desired, it is possible change to the working directory of -the dumping process by employing the value provided by the -.I %P -specifier to change to the location of the dumping process via -.IR /proc/ pid /cwd . -.IP \[bu] -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 \[bu] -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, -it can be useful for the collecting program to gather data about -the crashing process from that process's -.IR /proc/ pid -directory. -In order to do this safely, -the kernel must wait for the program collecting the core dump to exit, -so as not to remove the crashing process's -.IR /proc/ pid -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. -.P -Since Linux 2.6.32, -.\" commit a293980c2e261bd5b0d2a77340dd04f684caff58 -the -.I /proc/sys/kernel/core_pipe_limit -can be used to defend against this possibility. -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. -.P -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 -program is not guaranteed access to -.IR /proc/<crashing\-PID> ). -The default value for this file is 0. -.\" -.SS Controlling which mappings are written to the core dump -Since Linux 2.6.23, the Linux-specific -.IR /proc/ pid /coredump_filter -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. -.P -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 -corresponding type are dumped; otherwise they are not dumped. -The bits in this file have the following meanings: -.P -.PD 0 -.RS 4 -.TP -bit 0 -Dump anonymous private mappings. -.TP -bit 1 -Dump anonymous shared mappings. -.TP -bit 2 -Dump file-backed private mappings. -.TP -bit 3 -Dump file-backed shared mappings. -.\" file-backed shared mappings of course also update the underlying -.\" mapped file. -.TP -bit 4 (since Linux 2.6.24) -Dump ELF headers. -.TP -bit 5 (since Linux 2.6.28) -Dump private huge pages. -.TP -bit 6 (since Linux 2.6.28) -Dump shared huge pages. -.TP -bit 7 (since Linux 4.4) -.\" commit ab27a8d04b32b6ee8c30c14c4afd1058e8addc82 -Dump private DAX pages. -.TP -bit 8 (since Linux 4.4) -.\" commit ab27a8d04b32b6ee8c30c14c4afd1058e8addc82 -Dump shared DAX pages. -.RE -.PD -.P -By default, the following bits are set: 0, 1, 4 (if the -.B CONFIG_CORE_DUMP_DEFAULT_ELF_HEADERS -kernel configuration option is enabled), and 5. -This default can be modified at boot time using the -.I coredump_filter -boot option. -.P -The value of this file is displayed in hexadecimal. -(The default value is thus displayed as 33.) -.P -Memory-mapped I/O pages such as frame buffer are never dumped, and -virtual DSO -.RB ( vdso (7)) -pages are always dumped, regardless of the -.I coredump_filter -value. -.P -A child process created via -.BR fork (2) -inherits its parent's -.I coredump_filter -value; -the -.I coredump_filter -value is preserved across an -.BR execve (2). -.P -It can be useful to set -.I coredump_filter -in the parent shell before running a program, for example: -.P -.in +4n -.EX -.RB "$" " echo 0x7 > /proc/self/coredump_filter" -.RB "$" " ./some_program" -.EE -.in -.P -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: -.P -.in +4n -.EX -$ \fBcat /proc/sys/kernel/core_pattern\fP -|/usr/lib/systemd/systemd\-coredump %P %u %g %s %t %c %e -.EE -.in -.P -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): -.P -.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 -.P -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 -.I core -in the current directory, one could use: -.P -.in +4n -.EX -$ \fBcoredumpctl dump 2955 \-o core\fP -.EE -.in -.P -For more extensive details, see the -.BR coredumpctl (1) -manual page. -.P -To (persistently) 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: -.P -.in +4n -.EX -# \fBecho "kernel.core_pattern=core.%p" > \e\fP -\fB /etc/sysctl.d/50\-coredump.conf\fP -# \fB/lib/systemd/systemd\-sysctl\fP -.EE -.in -.P -It is also possible to temporarily (i.e., until the next reboot) change the -.I core_pattern -setting using a command such as the following -(which causes the names of core dump files to include the executable name -as well as the number of the signal which triggered the core dump): -.P -.in +4n -.EX -# \fBsysctl \-w kernel.core_pattern="%e\-%s.core"\fP -.EE -.in -.\" -.SH NOTES -The -.BR gdb (1) -.I gcore -command can be used to obtain a core dump of a running process. -.P -In Linux versions up to and including 2.6.27, -.\" Changed with commit 6409324b385f3f63a03645b4422e3be67348d922 -if a multithreaded process (or, more precisely, a process that -shares its memory with another process by being created with the -.B CLONE_VM -flag of -.BR clone (2)) -dumps core, then the process ID is always appended to the core filename, -unless the process ID was already included elsewhere in the -filename via a -.I %p -specification in -.IR /proc/sys/kernel/core_pattern . -(This is primarily useful when employing the obsolete -LinuxThreads implementation, -where each thread of a process has a different PID.) -.\" Always including the PID in the name of the core file made -.\" sense for LinuxThreads, where each thread had a unique PID, -.\" but doesn't seem to serve any purpose with NPTL, where all the -.\" threads in a process share the same PID (as POSIX.1 requires). -.\" Probably the behavior is maintained so that applications using -.\" LinuxThreads continue appending the PID (the kernel has no easy -.\" way of telling which threading implementation the user-space -.\" application is using). -- mtk, April 2006 -.SH EXAMPLES -The program below can be used to demonstrate the use of the -pipe syntax in the -.I /proc/sys/kernel/core_pattern -file. -The following shell session demonstrates the use of this program -(compiled to create an executable named -.IR core_pattern_pipe_test ): -.P -.in +4n -.EX -.RB "$" " cc \-o core_pattern_pipe_test core_pattern_pipe_test.c" -.RB "$" " su" -Password: -.RB "#" " echo \[dq]|$PWD/core_pattern_pipe_test %p \ -UID=%u GID=%g sig=%s\[dq] > \e" -.B " /proc/sys/kernel/core_pattern" -.RB "#" " exit" -.RB "$" " sleep 100" -.BR "\[ha]\e" " # type control\-backslash" -Quit (core dumped) -.RB "$" " cat core.info" -argc=5 -argc[0]=</home/mtk/core_pattern_pipe_test> -argc[1]=<20575> -argc[2]=<UID=1000> -argc[3]=<GID=100> -argc[4]=<sig=3> -Total bytes in core dump: 282624 -.EE -.in -.SS Program source -\& -.EX -/* core_pattern_pipe_test.c */ -\& -#define _GNU_SOURCE -#include <sys/stat.h> -#include <fcntl.h> -#include <limits.h> -#include <stdio.h> -#include <stdlib.h> -#include <unistd.h> -\& -#define BUF_SIZE 1024 -\& -int -main(int argc, char *argv[]) -{ - ssize_t nread, tot; - char buf[BUF_SIZE]; - FILE *fp; - char cwd[PATH_MAX]; -\& - /* Change our current working directory to that of the - crashing process. */ -\& - snprintf(cwd, PATH_MAX, "/proc/%s/cwd", argv[1]); - chdir(cwd); -\& - /* Write output to file "core.info" in that directory. */ -\& - fp = fopen("core.info", "w+"); - if (fp == NULL) - exit(EXIT_FAILURE); -\& - /* Display command\-line arguments given to core_pattern - pipe program. */ -\& - fprintf(fp, "argc=%d\en", argc); - for (size_t j = 0; j < argc; j++) - fprintf(fp, "argc[%zu]=<%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: %zd\en", tot); -\& - fclose(fp); - exit(EXIT_SUCCESS); -} -.EE -.SH SEE ALSO -.BR bash (1), -.BR coredumpctl (1), -.BR gdb (1), -.BR getrlimit (2), -.BR mmap (2), -.BR prctl (2), -.BR sigaction (2), -.BR elf (5), -.BR proc (5), -.BR pthreads (7), -.BR signal (7), -.BR systemd\-coredump (8) |