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 non-writable, 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 (00:00h,
69 1 Jan 1970, 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 non-
84 zero, 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 non-zero 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 The default value of coredump_filter is 0x3; this reflects traditional
131 Linux behavior and means that only anonymous memory segments are
132 dumped.
133 Memory-mapped I/O pages such as frame buffer are never dumped, and vir‐
135 tual DSO pages are always dumped, regardless of the coredump_filter
136 value.
137 A child process created via fork(2) inherits its parents coredump_fil‐
139 ter value; the coredump_filter value is preserved across an execve(2).
140 It can be useful to set coredump_filter in the parent shell before run‐
142 ning a program, for example:
143 $ echo 0x7 > /proc/self/coredump_filter
145 $ ./some_program
146 This file is only provided if the kernel was built with the CON‐
148 FIG_ELF_CORE configuration option.
149
151 The gdb(1) gcore command can be used to obtain a core dump of a running
152 process.
153 If a multithreaded process (or, more precisely, a process that shares
155 its memory with another process by being created with the CLONE_VM flag
156 of clone(2)) dumps core, then the process ID is always appended to the
157 core filename, unless the process ID was already included elsewhere in
158 the filename via a %p specification in /proc/sys/kernel/core_pattern.
159 (This is primarily useful when employing the LinuxThreads implementa‐
160 tion, where each thread of a process has a different PID.)
161
163 The program below can be used to demonstrate the use of the pipe syntax
164 in the /proc/sys/kernel/core_pattern file. The following shell session
165 demonstrates the use of this program (compiled to create an executable
166 named core_pattern_pipe_test):
167 $ cc -o core_pattern_pipe_test core_pattern_pipe_test.c
169 $ su
170 Password:
171 # echo '|$PWD/core_pattern_pipe_test %p UID=%u GID=%g sig=%s' > \
172 /proc/sys/kernel/core_pattern
173 # exit
174 $ sleep 100
175 ^\ # type control-backslash
176 Quit (core dumped)
177 $ cat core.info
178 argc=5
179 argc[0]=</home/mtk/core_pattern_pipe_test>
180 argc[1]=<20575>
181 argc[2]=<UID=1000>
182 argc[3]=<GID=100>
183 argc[4]=<sig=3>
184 Total bytes in core dump: 282624
185 Program source
187 /* core_pattern_pipe_test.c */
189 #define _GNU_SOURCE
191 #include <sys/stat.h>
192 #include <fcntl.h>
193 #include <limits.h>
194 #include <stdio.h>
195 #include <stdlib.h>
196 #include <unistd.h>
197 #define BUF_SIZE 1024
199 int
201 main(int argc, char *argv[])
202 {
203 int tot, j;
204 ssize_t nread;
205 char buf[BUF_SIZE];
206 FILE *fp;
207 char cwd[PATH_MAX];
208 /* Change our current working directory to that of the
210 crashing process */
211 snprintf(cwd, PATH_MAX, "/proc/%s/cwd", argv[1]);
213 chdir(cwd);
214 /* Write output to file "core.info" in that directory */
216 fp = fopen("core.info", "w+");
218 if (fp == NULL)
219 exit(EXIT_FAILURE);
220 /* Display command-line arguments given to core_pattern
222 pipe program */
223 fprintf(fp, "argc=%d\n", argc);
225 for (j = 0; j < argc; j++)
226 fprintf(fp, "argc[%d]=<%s>\n", j, argv[j]);
227 /* Count bytes in standard input (the core dump) */
229 tot = 0;
231 while ((nread = read(STDIN_FILENO, buf, BUF_SIZE)) > 0)
232 tot += nread;
233 fprintf(fp, "Total bytes in core dump: %d\n", tot);
234 exit(EXIT_SUCCESS);
236 }
237
239 bash(1), gdb(1), getrlimit(2), mmap(2), prctl(2), sigaction(2), elf(5),
240 proc(5), pthreads(7), signal(7)
241
243 This page is part of release 3.22 of the Linux man-pages project. A
244 description of the project, and information about reporting bugs, can
245 be found at http://www.kernel.org/doc/man-pages/.
246Linux 2008-08-26 CORE(5)