1CORE(5) Linux Programmer's Manual CORE(5)
2
6 core - core dump file
7
9 The default action of certain signals is to cause a process to termi‐
10 nate and produce a core dump file, a disk file containing an image of
11 the process's memory at the time of termination. This image can be
12 used in a debugger (e.g., gdb(1)) to inspect the state of the program
13 at the time that it terminated. A list of the signals which cause a
14 process to dump core can be found in signal(7).
15 A process can set its soft RLIMIT_CORE resource limit to place an upper
17 limit on the size of the core dump file that will be produced if it
18 receives a "core dump" signal; see getrlimit(2) for details.
19 There are various circumstances in which a core dump file is not pro‐
21 duced:
22 * The process does not have permission to write the core file. (By
24 default the core file is called core, and is created in the current
25 working directory. See below for details on naming.) Writing the
26 core file will fail if the directory in which it is to be created is
27 nonwritable, or if a file with the same name exists and is not
28 writable or is not a regular file (e.g., it is a directory or a sym‐
29 bolic link).
30 * A (writable, regular) file with the same name as would be used for
32 the core dump already exists, but there is more than one hard link
33 to that file.
34 * The file system where the core dump file would be created is full;
36 or has run out of inodes; or is mounted read-only; or the user has
37 reached their quota for the file system.
38 * The directory in which the core dump file is to be created does not
40 exist.
41 * The RLIMIT_CORE (core file size) or RLIMIT_FSIZE (file size)
43 resource limits for the process are set to zero; see getrlimit(2)
44 and the documentation of the shell's ulimit command (limit in
45 csh(1)).
46 * The binary being executed by the process does not have read permis‐
48 sion enabled.
49 * The process is executing a set-user-ID (set-group-ID) program that
51 is owned by a user (group) other than the real user (group) ID of
52 the process. (However, see the description of the prctl(2)
53 PR_SET_DUMPABLE operation, and the description of the
54 /proc/sys/fs/suid_dumpable file in proc(5).)
55 Naming of core dump files
57 By default, a core dump file is named core, but the /proc/sys/ker‐
58 nel/core_pattern file (since Linux 2.6 and 2.4.21) can be set to define
59 a template that is used to name core dump files. The template can con‐
60 tain % specifiers which are substituted by the following values when a
61 core file is created:
62 %% a single % character
64 %p PID of dumped process
65 %u (numeric) real UID of dumped process
66 %g (numeric) real GID of dumped process
67 %s number of signal causing dump
68 %t time of dump, expressed as seconds since the Epoch, 1970-01-01
69 00:00:00 +0000 (UTC)
70 %h hostname (same as nodename returned by uname(2))
71 %e executable filename (without path prefix)
72 %c core file size soft resource limit of crashing process (since
73 Linux 2.6.24)
74 A single % at the end of the template is dropped from the core file‐
76 name, as is the combination of a % followed by any character other than
77 those listed above. All other characters in the template become a lit‐
78 eral part of the core filename. The template may include '/' charac‐
79 ters, which are interpreted as delimiters for directory names. The
80 maximum size of the resulting core filename is 128 bytes (64 bytes in
81 kernels before 2.6.19). The default value in this file is "core". For
82 backward compatibility, if /proc/sys/kernel/core_pattern does not
83 include "%p" and /proc/sys/kernel/core_uses_pid (see below) is nonzero,
84 then .PID will be appended to the core filename.
85 Since version 2.4, Linux has also provided a more primitive method of
87 controlling the name of the core dump file. If the /proc/sys/ker‐
88 nel/core_uses_pid file contains the value 0, then a core dump file is
89 simply named core. If this file contains a nonzero value, then the
90 core dump file includes the process ID in a name of the form core.PID.
91 Piping core dumps to a program
93 Since kernel 2.6.19, Linux supports an alternate syntax for the
94 /proc/sys/kernel/core_pattern file. If the first character of this
95 file is a pipe symbol (|), then the remainder of the line is inter‐
96 preted as a program to be executed. Instead of being written to a disk
97 file, the core dump is given as standard input to the program. Note
98 the following points:
99 * The program must be specified using an absolute pathname (or a path‐
101 name relative to the root directory, /), and must immediately follow
102 the '|' character.
103 * The process created to run the program runs as user and group root.
105 * Command-line arguments can be supplied to the program (since kernel
107 2.6.24), delimited by white space (up to a total line length of 128
108 bytes).
109 * The command-line arguments can include any of the % specifiers
111 listed above. For example, to pass the PID of the process that is
112 being dumped, specify %p in an argument.
113 Controlling which mappings are written to the core dump
115 Since kernel 2.6.23, the Linux-specific /proc/PID/coredump_filter file
116 can be used to control which memory segments are written to the core
117 dump file in the event that a core dump is performed for the process
118 with the corresponding process ID.
119 The value in the file is a bit mask of memory mapping types (see
121 mmap(2)). If a bit is set in the mask, then memory mappings of the
122 corresponding type are dumped; otherwise they are not dumped. The bits
123 in this file have the following meanings:
124 bit 0 Dump anonymous private mappings.
126 bit 1 Dump anonymous shared mappings.
127 bit 2 Dump file-backed private mappings.
128 bit 3 Dump file-backed shared mappings.
129 bit 4 (since Linux 2.6.24)
130 Dump ELF headers.
131 bit 5 (since Linux 2.6.28)
132 Dump private huge pages.
133 bit 6 (since Linux 2.6.28)
134 Dump shared huge pages.
135 By default, the following bits are set: 0, 1, 4 (if the CON‐
137 FIG_CORE_DUMP_DEFAULT_ELF_HEADERS kernel configuration option is
138 enabled), and 5. The value of this file is displayed in hexadecimal.
139 (The default value is thus displayed as 33.)
140 Memory-mapped I/O pages such as frame buffer are never dumped, and vir‐
142 tual DSO pages are always dumped, regardless of the coredump_filter
143 value.
144 A child process created via fork(2) inherits its parent's coredump_fil‐
146 ter value; the coredump_filter value is preserved across an execve(2).
147 It can be useful to set coredump_filter in the parent shell before run‐
149 ning a program, for example:
150 $ echo 0x7 > /proc/self/coredump_filter
152 $ ./some_program
153 This file is only provided if the kernel was built with the CON‐
155 FIG_ELF_CORE configuration option.
156
158 The gdb(1) gcore command can be used to obtain a core dump of a running
159 process.
160 If a multithreaded process (or, more precisely, a process that shares
162 its memory with another process by being created with the CLONE_VM flag
163 of clone(2)) dumps core, then the process ID is always appended to the
164 core filename, unless the process ID was already included elsewhere in
165 the filename via a %p specification in /proc/sys/kernel/core_pattern.
166 (This is primarily useful when employing the LinuxThreads implementa‐
167 tion, where each thread of a process has a different PID.)
168
170 The program below can be used to demonstrate the use of the pipe syntax
171 in the /proc/sys/kernel/core_pattern file. The following shell session
172 demonstrates the use of this program (compiled to create an executable
173 named core_pattern_pipe_test):
174 $ cc -o core_pattern_pipe_test core_pattern_pipe_test.c
176 $ su
177 Password:
178 # echo '|$PWD/core_pattern_pipe_test %p UID=%u GID=%g sig=%s' > \
179 /proc/sys/kernel/core_pattern
180 # exit
181 $ sleep 100
182 ^\ # type control-backslash
183 Quit (core dumped)
184 $ cat core.info
185 argc=5
186 argc[0]=</home/mtk/core_pattern_pipe_test>
187 argc[1]=<20575>
188 argc[2]=<UID=1000>
189 argc[3]=<GID=100>
190 argc[4]=<sig=3>
191 Total bytes in core dump: 282624
192 Program source
194 /* core_pattern_pipe_test.c */
196 #define _GNU_SOURCE
198 #include <sys/stat.h>
199 #include <fcntl.h>
200 #include <limits.h>
201 #include <stdio.h>
202 #include <stdlib.h>
203 #include <unistd.h>
204 #define BUF_SIZE 1024
206 int
208 main(int argc, char *argv[])
209 {
210 int tot, j;
211 ssize_t nread;
212 char buf[BUF_SIZE];
213 FILE *fp;
214 char cwd[PATH_MAX];
215 /* Change our current working directory to that of the
217 crashing process */
218 snprintf(cwd, PATH_MAX, "/proc/%s/cwd", argv[1]);
220 chdir(cwd);
221 /* Write output to file "core.info" in that directory */
223 fp = fopen("core.info", "w+");
225 if (fp == NULL)
226 exit(EXIT_FAILURE);
227 /* Display command-line arguments given to core_pattern
229 pipe program */
230 fprintf(fp, "argc=%d\n", argc);
232 for (j = 0; j < argc; j++)
233 fprintf(fp, "argc[%d]=<%s>\n", j, argv[j]);
234 /* Count bytes in standard input (the core dump) */
236 tot = 0;
238 while ((nread = read(STDIN_FILENO, buf, BUF_SIZE)) > 0)
239 tot += nread;
240 fprintf(fp, "Total bytes in core dump: %d\n", tot);
241 exit(EXIT_SUCCESS);
243 }
244
246 bash(1), gdb(1), getrlimit(2), mmap(2), prctl(2), sigaction(2), elf(5),
247 proc(5), pthreads(7), signal(7)
248
250 This page is part of release 3.25 of the Linux man-pages project. A
251 description of the project, and information about reporting bugs, can
252 be found at http://www.kernel.org/doc/man-pages/.
253Linux 2010-02-27 CORE(5)