]>
Commit | Line | Data |
---|---|---|
b78e3a80 | 1 | .\" Copyright (c) 2006, 2008 by Michael Kerrisk <mtk.manpages@gmail.com> |
0be6f5cc | 2 | .\" |
93015253 | 3 | .\" %%%LICENSE_START(VERBATIM) |
0be6f5cc MK |
4 | .\" Permission is granted to make and distribute verbatim copies of this |
5 | .\" manual provided the copyright notice and this permission notice are | |
6 | .\" preserved on all copies. | |
7 | .\" | |
8 | .\" Permission is granted to copy and distribute modified versions of this | |
9 | .\" manual under the conditions for verbatim copying, provided that the | |
10 | .\" entire resulting derived work is distributed under the terms of a | |
11 | .\" permission notice identical to this one. | |
12 | .\" | |
13 | .\" Since the Linux kernel and libraries are constantly changing, this | |
14 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
15 | .\" responsibility for errors or omissions, or for damages resulting from | |
10d76543 MK |
16 | .\" the use of the information contained herein. The author(s) may not |
17 | .\" have taken the same level of care in the production of this manual, | |
18 | .\" which is licensed free of charge, as they might when working | |
19 | .\" professionally. | |
0be6f5cc MK |
20 | .\" |
21 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
22 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 23 | .\" %%%LICENSE_END |
0be6f5cc | 24 | .\" |
9f496381 | 25 | .TH CORE 5 2016-05-09 "Linux" "Linux Programmer's Manual" |
0be6f5cc MK |
26 | .SH NAME |
27 | core \- core dump file | |
28 | .SH DESCRIPTION | |
c13182ef | 29 | The default action of certain signals is to cause a process to terminate |
0be6f5cc MK |
30 | and produce a |
31 | .IR "core dump file" , | |
c13182ef | 32 | a disk file containing an image of the process's memory at |
0be6f5cc | 33 | the time of termination. |
78890124 MK |
34 | This image can be used in a debugger (e.g., |
35 | .BR gdb (1)) | |
36 | to inspect the state of the program at the time that it terminated. | |
0be6f5cc MK |
37 | A list of the signals which cause a process to dump core can be found in |
38 | .BR signal (7). | |
39 | ||
53cd945e | 40 | A process can set its soft |
0daa9e92 | 41 | .B RLIMIT_CORE |
c13182ef | 42 | resource limit to place an upper limit on the size of the core dump file |
0be6f5cc MK |
43 | that will be produced if it receives a "core dump" signal; see |
44 | .BR getrlimit (2) | |
45 | for details. | |
46 | ||
c13182ef | 47 | There are various circumstances in which a core dump file is |
0be6f5cc | 48 | not produced: |
e256d8aa | 49 | .IP * 3 |
67ed0e4b | 50 | The process does not have permission to write the core file. |
91aabea5 | 51 | (By default, the core file is called |
ab0f60c6 MK |
52 | .IR core |
53 | or | |
54 | .IR core.pid , | |
55 | where | |
56 | .I pid | |
57 | is the ID of the process that dumped core, | |
c13182ef | 58 | and is created in the current working directory. |
67ed0e4b | 59 | See below for details on naming.) |
c13182ef | 60 | Writing the core file will fail if the directory in which |
24b74457 | 61 | it is to be created is nonwritable, |
c13182ef | 62 | or if a file with the same name exists and |
67ed0e4b | 63 | is not writable |
c13182ef | 64 | or is not a regular file |
67ed0e4b | 65 | (e.g., it is a directory or a symbolic link). |
e256d8aa | 66 | .IP * |
c13182ef MK |
67 | A (writable, regular) file with the same name as would be used for the |
68 | core dump already exists, but there is more than one hard link to that | |
10cd859a MK |
69 | file. |
70 | .IP * | |
9ee4a2b6 | 71 | The filesystem where the core dump file would be created is full; |
972a8ec7 | 72 | or has run out of inodes; or is mounted read-only; |
9ee4a2b6 | 73 | or the user has reached their quota for the filesystem. |
10cd859a | 74 | .IP * |
c13182ef | 75 | The directory in which the core dump file is to be created does |
67ed0e4b | 76 | not exist. |
0be6f5cc | 77 | .IP * |
78890124 | 78 | The |
0be6f5cc | 79 | .B RLIMIT_CORE |
78890124 | 80 | (core file size) or |
0be6f5cc | 81 | .B RLIMIT_FSIZE |
78890124 MK |
82 | (file size) resource limits for the process are set to zero; see |
83 | .BR getrlimit (2) | |
84 | and the documentation of the shell's | |
85 | .I ulimit | |
86 | command | |
87 | .RI ( limit | |
88 | in | |
89 | .BR csh (1)). | |
0be6f5cc | 90 | .IP * |
c13182ef | 91 | The binary being executed by the process does not have read |
0be6f5cc MK |
92 | permission enabled. |
93 | .IP * | |
94 | The process is executing a set-user-ID (set-group-ID) program | |
c13182ef | 95 | that is owned by a user (group) other than the real user (group) |
60a119dd MK |
96 | ID of the process, |
97 | or the process is executing a program that has file capabilities (see | |
98 | .BR capabilities (7)). | |
0be6f5cc MK |
99 | (However, see the description of the |
100 | .BR prctl (2) | |
101 | .B PR_SET_DUMPABLE | |
102 | operation, and the description of the | |
103 | .I /proc/sys/fs/suid_dumpable | |
14523015 MK |
104 | .\" FIXME . Perhaps relocate discussion of /proc/sys/fs/suid_dumpable |
105 | .\" and PR_SET_DUMPABLE to this page? | |
0be6f5cc MK |
106 | file in |
107 | .BR proc (5).) | |
d298e17f MK |
108 | .IP * |
109 | (Since Linux 3.7) | |
110 | .\" commit 046d662f481830e652ac34cd112249adde16452a | |
111 | The kernel was configured without the | |
112 | .BR CONFIG_COREDUMP | |
113 | option. | |
0ac3f06f MK |
114 | .PP |
115 | In addition, | |
116 | a core dump may exclude part of the address space of the process if the | |
117 | .BR madvise (2) | |
118 | .B MADV_DONTDUMP | |
119 | flag was employed. | |
0be6f5cc | 120 | .SS Naming of core dump files |
c13182ef | 121 | By default, a core dump file is named |
0be6f5cc | 122 | .IR core , |
c13182ef | 123 | but the |
0be6f5cc | 124 | .I /proc/sys/kernel/core_pattern |
b78e3a80 | 125 | file (since Linux 2.6 and 2.4.21) |
0be6f5cc MK |
126 | can be set to define a template that is used to name core dump files. |
127 | The template can contain % specifiers which are substituted | |
128 | by the following values when a core file is created: | |
b78e3a80 MK |
129 | .PP |
130 | .RS 4 | |
131 | .PD 0 | |
132 | .TP 4 | |
133 | %% | |
134 | a single % character | |
135 | .TP | |
b9ed1fbb MK |
136 | %c |
137 | core file size soft resource limit of crashing process (since Linux 2.6.24) | |
b78e3a80 | 138 | .TP |
23ed8402 | 139 | %d |
fd9c713b MK |
140 | .\" Added in git commit 12a2b4b2241e318b4f6df31228e4272d2c2968a1 |
141 | dump mode\(emsame as value returned by | |
142 | .BR prctl (2) | |
143 | .B PR_GET_DUMPABLE | |
23ed8402 MF |
144 | (since Linux 3.7) |
145 | .TP | |
b78e3a80 MK |
146 | %e |
147 | executable filename (without path prefix) | |
148 | .TP | |
d7e34031 MK |
149 | %E |
150 | pathname of executable, | |
c46d3d7a BW |
151 | with slashes (\(aq/\(aq) replaced by exclamation marks (\(aq!\(aq) |
152 | (since Linux 3.0). | |
d7e34031 | 153 | .TP |
b9ed1fbb MK |
154 | %g |
155 | (numeric) real GID of dumped process | |
156 | .TP | |
157 | %h | |
158 | hostname (same as \fInodename\fP returned by \fBuname\fP(2)) | |
159 | .TP | |
e04ae86d MK |
160 | %i |
161 | TID of thread that triggered core dump, | |
162 | as seen in the PID namespace in which the thread resides | |
163 | .\" commit b03023ecbdb76c1dec86b41ed80b123c22783220 | |
164 | (since Linux 3.18) | |
165 | .TP | |
166 | %I | |
167 | TID of thread that triggered core dump, as seen in the initial PID namespace | |
168 | .\" commit b03023ecbdb76c1dec86b41ed80b123c22783220 | |
169 | (since Linux 3.18) | |
170 | .TP | |
b9ed1fbb MK |
171 | %p |
172 | PID of dumped process, | |
173 | as seen in the PID namespace in which the process resides | |
174 | .TP | |
175 | %P | |
176 | .\" Added in git commit 65aafb1e7484b7434a0c1d4c593191ebe5776a2f | |
177 | PID of dumped process, as seen in the initial PID namespace | |
178 | (since Linux 3.12) | |
179 | .TP | |
180 | %s | |
181 | number of signal causing dump | |
182 | .TP | |
183 | %t | |
184 | time of dump, expressed as seconds since the | |
185 | Epoch, 1970-01-01 00:00:00 +0000 (UTC) | |
186 | .TP | |
187 | %u | |
188 | (numeric) real UID of dumped process | |
b78e3a80 MK |
189 | .PD |
190 | .RE | |
191 | .PP | |
c13182ef MK |
192 | A single % at the end of the template is dropped from the |
193 | core filename, as is the combination of a % followed by any | |
0be6f5cc MK |
194 | character other than those listed above. |
195 | All other characters in the template become a literal | |
196 | part of the core filename. | |
f81fb444 | 197 | The template may include \(aq/\(aq characters, which are interpreted |
0be6f5cc | 198 | as delimiters for directory names. |
b78e3a80 MK |
199 | The maximum size of the resulting core filename is 128 bytes (64 bytes |
200 | in kernels before 2.6.19). | |
0be6f5cc MK |
201 | The default value in this file is "core". |
202 | For backward compatibility, if | |
203 | .I /proc/sys/kernel/core_pattern | |
0ea48b19 MK |
204 | does not include |
205 | .I %p | |
206 | and | |
0be6f5cc MK |
207 | .I /proc/sys/kernel/core_uses_pid |
208 | (see below) | |
c7094399 | 209 | is nonzero, then .PID will be appended to the core filename. |
0be6f5cc | 210 | |
10cd859a MK |
211 | Since version 2.4, Linux has also provided |
212 | a more primitive method of controlling | |
0be6f5cc MK |
213 | the name of the core dump file. |
214 | If the | |
215 | .I /proc/sys/kernel/core_uses_pid | |
216 | file contains the value 0, then a core dump file is simply named | |
217 | .IR core . | |
c7094399 | 218 | If this file contains a nonzero value, then the core dump file includes |
0be6f5cc MK |
219 | the process ID in a name of the form |
220 | .IR core.PID . | |
8c897fc6 | 221 | |
4b749a12 | 222 | Since Linux 3.6, |
8c897fc6 KC |
223 | .\" 9520628e8ceb69fa9a4aee6b57f22675d9e1b709 |
224 | if | |
225 | .I /proc/sys/fs/suid_dumpable | |
4b749a12 | 226 | is set to 2 ("suidsafe"), the pattern must be either an absolute pathname |
8c897fc6 | 227 | (starting with a leading \(aq/\(aq character) or a pipe, as defined below. |
b78e3a80 MK |
228 | .SS Piping core dumps to a program |
229 | Since kernel 2.6.19, Linux supports an alternate syntax for the | |
230 | .I /proc/sys/kernel/core_pattern | |
231 | file. | |
232 | If the first character of this file is a pipe symbol (\fB|\fP), | |
d9f2d36a | 233 | then the remainder of the line is interpreted as a user-space program to be |
b78e3a80 MK |
234 | executed. |
235 | Instead of being written to a disk file, the core dump is given as | |
236 | standard input to the program. | |
237 | Note the following points: | |
238 | .IP * 3 | |
239 | The program must be specified using an absolute pathname (or a | |
240 | pathname relative to the root directory, \fI/\fP), | |
241 | and must immediately follow the '|' character. | |
242 | .IP * | |
243 | The process created to run the program runs as user and group | |
244 | .IR root . | |
245 | .IP * | |
246 | Command-line arguments can be supplied to the | |
d26a34f0 | 247 | program (since Linux 2.6.24), |
b78e3a80 MK |
248 | delimited by white space (up to a total line length of 128 bytes). |
249 | .IP * | |
250 | The command-line arguments can include any of | |
251 | the % specifiers listed above. | |
252 | For example, to pass the PID of the process that is being dumped, specify | |
253 | .I %p | |
254 | in an argument. | |
d9f2d36a MK |
255 | .\" |
256 | .SS /proc/sys/kernel/core_pipe_limit | |
257 | When collecting core dumps via a pipe to a user-space program, | |
258 | it can be useful for the collecting program to gather data about | |
259 | the crashing process from that process's | |
260 | .IR /proc/PID | |
261 | directory. | |
262 | In order to do this safely, | |
263 | the kernel must wait for the program collecting the core dump to exit, | |
264 | so as not to remove the crashing process's | |
265 | .IR /proc/PID | |
266 | files prematurely. | |
267 | This in turn creates the | |
268 | possibility that a misbehaving collecting program can block | |
269 | the reaping of a crashed process by simply never exiting. | |
270 | ||
271 | Since Linux 2.6.32, | |
272 | .\" commit a293980c2e261bd5b0d2a77340dd04f684caff58 | |
273 | the | |
274 | .I /proc/sys/kernel/core_pipe_limit | |
275 | can be used to defend against this possibility. | |
276 | The value in this file defines how many concurrent crashing | |
277 | processes may be piped to user-space programs in parallel. | |
278 | If this value is exceeded, then those crashing processes above this value | |
279 | are noted in the kernel log and their core dumps are skipped. | |
280 | ||
281 | A value of 0 in this file is special. | |
282 | It indicates that unlimited processes may be captured in parallel, | |
283 | but that no waiting will take place (i.e., the collecting | |
284 | program is not guaranteed access to | |
285 | .IR /proc/<crashing-PID> ). | |
286 | The default value for this file is 0. | |
287 | .\" | |
b78e3a80 MK |
288 | .SS Controlling which mappings are written to the core dump |
289 | Since kernel 2.6.23, the Linux-specific | |
290 | .IR /proc/PID/coredump_filter | |
291 | file can be used to control which memory segments are written to the | |
292 | core dump file in the event that a core dump is performed for the | |
293 | process with the corresponding process ID. | |
294 | ||
295 | The value in the file is a bit mask of memory mapping types (see | |
296 | .BR mmap (2)). | |
297 | If a bit is set in the mask, then memory mappings of the | |
298 | corresponding type are dumped; otherwise they are not dumped. | |
299 | The bits in this file have the following meanings: | |
300 | .PP | |
301 | .PD 0 | |
302 | .RS 4 | |
303 | .TP | |
304 | bit 0 | |
305 | Dump anonymous private mappings. | |
306 | .TP | |
307 | bit 1 | |
308 | Dump anonymous shared mappings. | |
309 | .TP | |
310 | bit 2 | |
311 | Dump file-backed private mappings. | |
312 | .TP | |
313 | bit 3 | |
314 | Dump file-backed shared mappings. | |
315 | .\" file-backed shared mappings of course also update the underlying | |
316 | .\" mapped file. | |
cd3c7b38 MK |
317 | .TP |
318 | bit 4 (since Linux 2.6.24) | |
bb464ec1 | 319 | Dump ELF headers. |
cd3c7b38 MK |
320 | .TP |
321 | bit 5 (since Linux 2.6.28) | |
322 | Dump private huge pages. | |
323 | .TP | |
324 | bit 6 (since Linux 2.6.28) | |
325 | Dump shared huge pages. | |
db02982a RZ |
326 | .TP |
327 | bit 7 (since Linux 4.4) | |
9242ecfe | 328 | .\" commit ab27a8d04b32b6ee8c30c14c4afd1058e8addc82 |
db02982a RZ |
329 | Dump private DAX pages. |
330 | .TP | |
331 | bit 8 (since Linux 4.4) | |
9242ecfe | 332 | .\" commit ab27a8d04b32b6ee8c30c14c4afd1058e8addc82 |
db02982a | 333 | Dump shared DAX pages. |
b78e3a80 MK |
334 | .RE |
335 | .PD | |
336 | .PP | |
cd3c7b38 MK |
337 | By default, the following bits are set: 0, 1, 4 (if the |
338 | .B CONFIG_CORE_DUMP_DEFAULT_ELF_HEADERS | |
339 | kernel configuration option is enabled), and 5. | |
7b28cf66 MK |
340 | This default can be modified at boot time using the |
341 | .I coredump_filter | |
342 | boot option. | |
343 | ||
cd3c7b38 MK |
344 | The value of this file is displayed in hexadecimal. |
345 | (The default value is thus displayed as 33.) | |
b78e3a80 | 346 | |
a1d5601b | 347 | Memory-mapped I/O pages such as frame buffer are never dumped, and |
b78e3a80 MK |
348 | virtual DSO pages are always dumped, regardless of the |
349 | .I coredump_filter | |
350 | value. | |
351 | ||
352 | A child process created via | |
353 | .BR fork (2) | |
70d70ddc | 354 | inherits its parent's |
b78e3a80 MK |
355 | .I coredump_filter |
356 | value; | |
a1d5601b | 357 | the |
b78e3a80 MK |
358 | .I coredump_filter |
359 | value is preserved across an | |
360 | .BR execve (2). | |
361 | ||
362 | It can be useful to set | |
363 | .I coredump_filter | |
364 | in the parent shell before running a program, for example: | |
365 | ||
366 | .in +4n | |
367 | .nf | |
b43a3b30 MK |
368 | .RB "$" " echo 0x7 > /proc/self/coredump_filter" |
369 | .RB "$" " ./some_program" | |
b78e3a80 MK |
370 | .fi |
371 | .in | |
372 | .PP | |
33a0ccb2 | 373 | This file is provided only if the kernel was built with the |
e242920a MK |
374 | .B CONFIG_ELF_CORE |
375 | configuration option. | |
0be6f5cc | 376 | .SH NOTES |
c13182ef | 377 | The |
0be6f5cc MK |
378 | .BR gdb (1) |
379 | .I gcore | |
380 | command can be used to obtain a core dump of a running process. | |
5ddfb8c7 | 381 | |
173e4d50 MK |
382 | In Linux versions up to and including 2.6.27, |
383 | .\" Changed with commit 6409324b385f3f63a03645b4422e3be67348d922 | |
384 | if a multithreaded process (or, more precisely, a process that | |
5ddfb8c7 MK |
385 | shares its memory with another process by being created with the |
386 | .B CLONE_VM | |
387 | flag of | |
388 | .BR clone (2)) | |
c13182ef | 389 | dumps core, then the process ID is always appended to the core filename, |
d216b211 | 390 | unless the process ID was already included elsewhere in the |
0ea48b19 MK |
391 | filename via a |
392 | .I %p | |
393 | specification in | |
5ddfb8c7 | 394 | .IR /proc/sys/kernel/core_pattern . |
173e4d50 MK |
395 | (This is primarily useful when employing the obsolete |
396 | LinuxThreads implementation, | |
b8424e6a | 397 | where each thread of a process has a different PID.) |
4b47fc34 MK |
398 | .\" Always including the PID in the name of the core file made |
399 | .\" sense for LinuxThreads, where each thread had a unique PID, | |
905e99f2 | 400 | .\" but doesn't seem to serve any purpose with NPTL, where all the |
c13182ef | 401 | .\" threads in a process share the same PID (as POSIX.1 requires). |
d9bfdb9c | 402 | .\" Probably the behavior is maintained so that applications using |
c13182ef | 403 | .\" LinuxThreads continue appending the PID (the kernel has no easy |
7fac88a9 | 404 | .\" way of telling which threading implementation the user-space |
d216b211 | 405 | .\" application is using). -- mtk, April 2006 |
b78e3a80 MK |
406 | .SH EXAMPLE |
407 | The program below can be used to demonstrate the use of the | |
a1d5601b | 408 | pipe syntax in the |
b78e3a80 MK |
409 | .I /proc/sys/kernel/core_pattern |
410 | file. | |
411 | The following shell session demonstrates the use of this program | |
412 | (compiled to create an executable named | |
413 | .IR core_pattern_pipe_test ): | |
414 | .PP | |
415 | .in +4n | |
416 | .nf | |
b43a3b30 MK |
417 | .RB "$" " cc \-o core_pattern_pipe_test core_pattern_pipe_test.c" |
418 | .RB "$" " su" | |
b78e3a80 | 419 | Password: |
e9b77925 | 420 | .RB "#" " echo \(dq|$PWD/core_pattern_pipe_test %p \ |
31a6818e | 421 | UID=%u GID=%g sig=%s\(dq > \e" |
b43a3b30 MK |
422 | .B " /proc/sys/kernel/core_pattern" |
423 | .RB "#" " exit" | |
424 | .RB "$" " sleep 100" | |
31a6818e | 425 | .BR "^\e" " # type control-backslash" |
b78e3a80 | 426 | Quit (core dumped) |
b43a3b30 | 427 | .RB "$" " cat core.info" |
b78e3a80 MK |
428 | argc=5 |
429 | argc[0]=</home/mtk/core_pattern_pipe_test> | |
430 | argc[1]=<20575> | |
431 | argc[2]=<UID=1000> | |
432 | argc[3]=<GID=100> | |
433 | argc[4]=<sig=3> | |
434 | Total bytes in core dump: 282624 | |
435 | .fi | |
436 | .in | |
9c330504 | 437 | .SS Program source |
d84d0300 | 438 | \& |
b78e3a80 MK |
439 | .nf |
440 | /* core_pattern_pipe_test.c */ | |
441 | ||
442 | #define _GNU_SOURCE | |
443 | #include <sys/stat.h> | |
444 | #include <fcntl.h> | |
445 | #include <limits.h> | |
446 | #include <stdio.h> | |
447 | #include <stdlib.h> | |
448 | #include <unistd.h> | |
449 | ||
450 | #define BUF_SIZE 1024 | |
451 | ||
452 | int | |
453 | main(int argc, char *argv[]) | |
454 | { | |
455 | int tot, j; | |
456 | ssize_t nread; | |
457 | char buf[BUF_SIZE]; | |
458 | FILE *fp; | |
459 | char cwd[PATH_MAX]; | |
460 | ||
a1d5601b | 461 | /* Change our current working directory to that of the |
b78e3a80 MK |
462 | crashing process */ |
463 | ||
464 | snprintf(cwd, PATH_MAX, "/proc/%s/cwd", argv[1]); | |
465 | chdir(cwd); | |
466 | ||
467 | /* Write output to file "core.info" in that directory */ | |
468 | ||
469 | fp = fopen("core.info", "w+"); | |
470 | if (fp == NULL) | |
471 | exit(EXIT_FAILURE); | |
472 | ||
473 | /* Display command\-line arguments given to core_pattern | |
474 | pipe program */ | |
475 | ||
476 | fprintf(fp, "argc=%d\\n", argc); | |
477 | for (j = 0; j < argc; j++) | |
478 | fprintf(fp, "argc[%d]=<%s>\\n", j, argv[j]); | |
479 | ||
480 | /* Count bytes in standard input (the core dump) */ | |
481 | ||
482 | tot = 0; | |
a1d5601b | 483 | while ((nread = read(STDIN_FILENO, buf, BUF_SIZE)) > 0) |
b78e3a80 MK |
484 | tot += nread; |
485 | fprintf(fp, "Total bytes in core dump: %d\\n", tot); | |
486 | ||
aaec25cb | 487 | fclose(fp); |
b78e3a80 MK |
488 | exit(EXIT_SUCCESS); |
489 | } | |
490 | .fi | |
0be6f5cc | 491 | .SH SEE ALSO |
a2aac039 | 492 | .BR bash (1), |
0be6f5cc MK |
493 | .BR gdb (1), |
494 | .BR getrlimit (2), | |
a8b32c31 | 495 | .BR mmap (2), |
0be6f5cc MK |
496 | .BR prctl (2), |
497 | .BR sigaction (2), | |
498 | .BR elf (5), | |
499 | .BR proc (5), | |
b8424e6a | 500 | .BR pthreads (7), |
0be6f5cc | 501 | .BR signal (7) |