1CORE(5)                    Linux Programmer's Manual                   CORE(5)
2
3
4

NAME

6       core - core dump file
7

DESCRIPTION

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
16       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
20       There are various circumstances in which a core dump file is  not  pro‐
21       duced:
22
23       *  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
31       *  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
35       *  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
39       *  The  directory in which the core dump file is to be created does not
40          exist.
41
42       *  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
47       *  The  binary being executed by the process does not have read permis‐
48          sion enabled.
49
50       *  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
56       *  (Since Linux 3.7) The kernel was configured without the CONFIG_CORE‐
57          DUMP option.
58
59       In  addition,  a core dump may exclude part of the address space of the
60       process if the madvise(2) MADV_DONTDUMP flag was employed.
61
62   Naming of core dump files
63       By default, a core dump file is  named  core,  but  the  /proc/sys/ker‐
64       nel/core_pattern file (since Linux 2.6 and 2.4.21) can be set to define
65       a template that is used to name core dump files.  The template can con‐
66       tain  % specifiers which are substituted by the following values when a
67       core file is created:
68
69           %%  a single % character
70           %p  PID of dumped process
71           %u  (numeric) real UID of dumped process
72           %g  (numeric) real GID of dumped process
73           %s  number of signal causing dump
74           %t  time of dump, expressed as seconds since the Epoch,  1970-01-01
75               00:00:00 +0000 (UTC)
76           %h  hostname (same as nodename returned by uname(2))
77           %e  executable filename (without path prefix)
78           %E  pathname of executable, with slashes ('/') replaced by exclama‐
79               tion marks ('!').
80           %c  core file size soft resource limit of crashing  process  (since
81               Linux 2.6.24)
82
83       A  single  %  at the end of the template is dropped from the core file‐
84       name, as is the combination of a % followed by any character other than
85       those listed above.  All other characters in the template become a lit‐
86       eral part of the core filename.  The template may include  '/'  charac‐
87       ters,  which  are  interpreted  as delimiters for directory names.  The
88       maximum size of the resulting core filename is 128 bytes (64  bytes  in
89       kernels before 2.6.19).  The default value in this file is "core".  For
90       backward  compatibility,  if  /proc/sys/kernel/core_pattern  does   not
91       include "%p" and /proc/sys/kernel/core_uses_pid (see below) is nonzero,
92       then .PID will be appended to the core filename.
93
94       Since version 2.4, Linux has also provided a more primitive  method  of
95       controlling  the  name  of  the  core dump file.  If the /proc/sys/ker‐
96       nel/core_uses_pid file contains the value 0, then a core dump  file  is
97       simply  named  core.   If  this file contains a nonzero value, then the
98       core dump file includes the process ID in a name of the form core.PID.
99
100       Since Linux 3.6, if /proc/sys/fs/suid_dumpable  is  set  to  2  ("suid‐
101       safe"),  the pattern must be either an absolute pathname (starting with
102       a leading '/' character) or a pipe, as defined below.
103
104   Piping core dumps to a program
105       Since kernel  2.6.19,  Linux  supports  an  alternate  syntax  for  the
106       /proc/sys/kernel/core_pattern  file.   If  the  first character of this
107       file is a pipe symbol (|), then the remainder of  the  line  is  inter‐
108       preted as a program to be executed.  Instead of being written to a disk
109       file, the core dump is given as standard input to  the  program.   Note
110       the following points:
111
112       *  The program must be specified using an absolute pathname (or a path‐
113          name relative to the root directory, /), and must immediately follow
114          the '|' character.
115
116       *  The process created to run the program runs as user and group root.
117
118       *  Command-line  arguments  can be supplied to the program (since Linux
119          2.6.24), delimited by white space (up to a total line length of  128
120          bytes).
121
122       *  The  command-line  arguments  can  include  any  of the % specifiers
123          listed above.  For example, to pass the PID of the process  that  is
124          being dumped, specify %p in an argument.
125
126   Controlling which mappings are written to the core dump
127       Since  kernel 2.6.23, the Linux-specific /proc/PID/coredump_filter file
128       can be used to control which memory segments are written  to  the  core
129       dump  file  in  the event that a core dump is performed for the process
130       with the corresponding process ID.
131
132       The value in the file is a  bit  mask  of  memory  mapping  types  (see
133       mmap(2)).   If  a  bit  is set in the mask, then memory mappings of the
134       corresponding type are dumped; otherwise they are not dumped.  The bits
135       in this file have the following meanings:
136
137           bit 0  Dump anonymous private mappings.
138           bit 1  Dump anonymous shared mappings.
139           bit 2  Dump file-backed private mappings.
140           bit 3  Dump file-backed shared mappings.
141           bit 4 (since Linux 2.6.24)
142                  Dump ELF headers.
143           bit 5 (since Linux 2.6.28)
144                  Dump private huge pages.
145           bit 6 (since Linux 2.6.28)
146                  Dump shared huge pages.
147
148       By  default,  the  following  bits  are  set:  0,  1,  4  (if  the CON‐
149       FIG_CORE_DUMP_DEFAULT_ELF_HEADERS  kernel   configuration   option   is
150       enabled),  and  5.  The value of this file is displayed in hexadecimal.
151       (The default value is thus displayed as 33.)
152
153       Memory-mapped I/O pages such as frame buffer are never dumped, and vir‐
154       tual  DSO  pages  are  always dumped, regardless of the coredump_filter
155       value.
156
157       A child process created via fork(2) inherits its parent's coredump_fil‐
158       ter value; the coredump_filter value is preserved across an execve(2).
159
160       It can be useful to set coredump_filter in the parent shell before run‐
161       ning a program, for example:
162
163           $ echo 0x7 > /proc/self/coredump_filter
164           $ ./some_program
165
166       This file is provided only if  the  kernel  was  built  with  the  CON‐
167       FIG_ELF_CORE configuration option.
168

NOTES

170       The gdb(1) gcore command can be used to obtain a core dump of a running
171       process.
172
173       In Linux versions up  to  and  including  2.6.27,  if  a  multithreaded
174       process  (or,  more  precisely,  a  process that shares its memory with
175       another process by being created with the CLONE_VM  flag  of  clone(2))
176       dumps  core,  then  the process ID is always appended to the core file‐
177       name, unless the process ID was already included elsewhere in the file‐
178       name via a %p specification in /proc/sys/kernel/core_pattern.  (This is
179       primarily useful when employing the obsolete  LinuxThreads  implementa‐
180       tion, where each thread of a process has a different PID.)
181

EXAMPLE

183       The program below can be used to demonstrate the use of the pipe syntax
184       in the /proc/sys/kernel/core_pattern file.  The following shell session
185       demonstrates  the use of this program (compiled to create an executable
186       named core_pattern_pipe_test):
187
188           $ cc -o core_pattern_pipe_test core_pattern_pipe_test.c
189           $ su
190           Password:
191           # echo "|$PWD/core_pattern_pipe_test %p UID=%u GID=%g sig=%s" > \
192               /proc/sys/kernel/core_pattern
193           # exit
194           $ sleep 100
195           ^\                     # type control-backslash
196           Quit (core dumped)
197           $ cat core.info
198           argc=5
199           argc[0]=</home/mtk/core_pattern_pipe_test>
200           argc[1]=<20575>
201           argc[2]=<UID=1000>
202           argc[3]=<GID=100>
203           argc[4]=<sig=3>
204           Total bytes in core dump: 282624
205
206   Program source
207
208       /* core_pattern_pipe_test.c */
209
210       #define _GNU_SOURCE
211       #include <sys/stat.h>
212       #include <fcntl.h>
213       #include <limits.h>
214       #include <stdio.h>
215       #include <stdlib.h>
216       #include <unistd.h>
217
218       #define BUF_SIZE 1024
219
220       int
221       main(int argc, char *argv[])
222       {
223           int tot, j;
224           ssize_t nread;
225           char buf[BUF_SIZE];
226           FILE *fp;
227           char cwd[PATH_MAX];
228
229           /* Change our current working directory to that of the
230              crashing process */
231
232           snprintf(cwd, PATH_MAX, "/proc/%s/cwd", argv[1]);
233           chdir(cwd);
234
235           /* Write output to file "core.info" in that directory */
236
237           fp = fopen("core.info", "w+");
238           if (fp == NULL)
239               exit(EXIT_FAILURE);
240
241           /* Display command-line arguments given to core_pattern
242              pipe program */
243
244           fprintf(fp, "argc=%d\n", argc);
245           for (j = 0; j < argc; j++)
246               fprintf(fp, "argc[%d]=<%s>\n", j, argv[j]);
247
248           /* Count bytes in standard input (the core dump) */
249
250           tot = 0;
251           while ((nread = read(STDIN_FILENO, buf, BUF_SIZE)) > 0)
252               tot += nread;
253           fprintf(fp, "Total bytes in core dump: %d\n", tot);
254
255           exit(EXIT_SUCCESS);
256       }
257

SEE ALSO

259       bash(1), gdb(1), getrlimit(2), mmap(2), prctl(2), sigaction(2), elf(5),
260       proc(5), pthreads(7), signal(7)
261

COLOPHON

263       This  page  is  part of release 3.53 of the Linux man-pages project.  A
264       description of the project, and information about reporting  bugs,  can
265       be found at http://www.kernel.org/doc/man-pages/.
266
267
268
269Linux                             2013-06-08                           CORE(5)
Impressum