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 or core.pid, where pid is  the
25          ID  of  the  process that dumped core, and is created in the current
26          working directory.  See below for details on naming.)   Writing  the
27          core  file  fails  if  the directory in which it is to be created is
28          nonwritable, or if a file with the  same  name  exists  and  is  not
29          writable or is not a regular file (e.g., it is a directory or a sym‐
30          bolic link).
31
32       *  A (writable, regular) file with the same name as would be  used  for
33          the  core  dump already exists, but there is more than one hard link
34          to that file.
35
36       *  The filesystem where the core dump file would be created is full; or
37          has  run  out  of  inodes;  or is mounted read-only; or the user has
38          reached their quota for the filesystem.
39
40       *  The directory in which the core dump file is to be created does  not
41          exist.
42
43       *  The  RLIMIT_CORE  (core  file  size)  or  RLIMIT_FSIZE  (file  size)
44          resource limits for the process are set to  zero;  see  getrlimit(2)
45          and  the  documentation  of  the  shell's  ulimit  command (limit in
46          csh(1)).
47
48       *  The binary being executed by the process does not have read  permis‐
49          sion enabled.
50
51       *  The  process  is executing a set-user-ID (set-group-ID) program that
52          is owned by a user (group) other than the real user  (group)  ID  of
53          the  process,  or  the  process is executing a program that has file
54          capabilities (see capabilities(7)).  (However, see  the  description
55          of  the  prctl(2)  PR_SET_DUMPABLE operation, and the description of
56          the /proc/sys/fs/suid_dumpable file in proc(5).)
57
58       *  /proc/sys/kernel/core_pattern   is    empty    and    /proc/sys/ker‐
59          nel/core_uses_pid  contains the value 0.  (These files are described
60          below.)  Note that if  /proc/sys/kernel/core_pattern  is  empty  and
61          /proc/sys/kernel/core_uses_pid contains the value 1, core dump files
62          will have names of the form .pid, and such files are  hidden  unless
63          one uses the ls(1) -a option.
64
65       *  (Since Linux 3.7) The kernel was configured without the CONFIG_CORE‐
66          DUMP option.
67
68       In addition, a core dump may exclude part of the address space  of  the
69       process if the madvise(2) MADV_DONTDUMP flag was employed.
70
71       On systems that employ systemd(1) as the init framework, core dumps may
72       instead be placed in a location determined by  systemd(1).   See  below
73       for further details.
74
75   Naming of core dump files
76       By  default,  a  core  dump  file is named core, but the /proc/sys/ker‐
77       nel/core_pattern file (since Linux 2.6 and 2.4.21) can be set to define
78       a template that is used to name core dump files.  The template can con‐
79       tain % specifiers which are substituted by the following values when  a
80       core file is created:
81
82           %%  a single % character
83           %c  core  file  size soft resource limit of crashing process (since
84               Linux 2.6.24)
85           %d  dump mode—same as value returned  by  prctl(2)  PR_GET_DUMPABLE
86               (since Linux 3.7)
87           %e  executable filename (without path prefix)
88           %E  pathname of executable, with slashes ('/') replaced by exclama‐
89               tion marks ('!') (since Linux 3.0).
90           %g  (numeric) real GID of dumped process
91           %h  hostname (same as nodename returned by uname(2))
92           %i  TID of thread that triggered core dump,  as  seen  in  the  PID
93               namespace in which the thread resides (since Linux 3.18)
94           %I  TID  of thread that triggered core dump, as seen in the initial
95               PID namespace (since Linux 3.18)
96           %p  PID of dumped process, as seen in the PID  namespace  in  which
97               the process resides
98           %P  PID  of  dumped  process,  as seen in the initial PID namespace
99               (since Linux 3.12)
100           %s  number of signal causing dump
101           %t  time of dump, expressed as seconds since the Epoch,  1970-01-01
102               00:00:00 +0000 (UTC)
103           %u  (numeric) real UID of dumped process
104
105       A  single  %  at the end of the template is dropped from the core file‐
106       name, as is the combination of a % followed by any character other than
107       those listed above.  All other characters in the template become a lit‐
108       eral part of the core filename.  The template may include  '/'  charac‐
109       ters,  which  are  interpreted  as delimiters for directory names.  The
110       maximum size of the resulting core filename is 128 bytes (64  bytes  in
111       kernels before 2.6.19).  The default value in this file is "core".  For
112       backward  compatibility,  if  /proc/sys/kernel/core_pattern  does   not
113       include  %p  and /proc/sys/kernel/core_uses_pid (see below) is nonzero,
114       then .PID will be appended to the core filename.
115
116       Paths are interpreted according to the settings that are active for the
117       crashing  process.   That  means the crashing process's mount namespace
118       (see mount_namespaces(7)), its current  working  directory  (found  via
119       getcwd(2)), and its root directory (see chroot(2)).
120
121       Since  version  2.4, Linux has also provided a more primitive method of
122       controlling the name of the core  dump  file.   If  the  /proc/sys/ker‐
123       nel/core_uses_pid  file  contains the value 0, then a core dump file is
124       simply named core.  If this file contains a  nonzero  value,  then  the
125       core dump file includes the process ID in a name of the form core.PID.
126
127       Since  Linux  3.6,  if  /proc/sys/fs/suid_dumpable  is set to 2 ("suid‐
128       safe"), the pattern must be either an absolute pathname (starting  with
129       a leading '/' character) or a pipe, as defined below.
130
131   Piping core dumps to a program
132       Since  kernel  2.6.19,  Linux  supports  an  alternate  syntax  for the
133       /proc/sys/kernel/core_pattern file.  If the  first  character  of  this
134       file  is  a  pipe  symbol (|), then the remainder of the line is inter‐
135       preted as the command-line for a user-space program (or script) that is
136       to be executed.  Instead of being written to a disk file, the core dump
137       is given as standard input to the program.  Note the following points:
138
139       *  The program must be specified using an absolute pathname (or a path‐
140          name relative to the root directory, /), and must immediately follow
141          the '|' character.
142
143       *  The command-line arguments can  include  any  of  the  %  specifiers
144          listed  above.   For example, to pass the PID of the process that is
145          being dumped, specify %p in an argument.
146
147       *  The process created to run the program runs as user and group root.
148
149       *  Running as root does not confer any exceptional  security  bypasses.
150          Namely,  LSMs  (e.g.,  SELinux) are still active and may prevent the
151          handler  from  accessing  details  about  the  crashed  process  via
152          /proc/[pid].
153
154       *  The  program  pathname  is  interpreted  with respect to the initial
155          mount namespace as it is always executed there.  It is not  affected
156          by  the  settings  (e.g.,  root  directory, mount namespace, current
157          working directory) of the crashing process.
158
159       *  The process runs in the initial namespaces (PID, mount, user, and so
160          on) and not in the namespaces of the crashing process.  One can uti‐
161          lize specifiers such as %P to find the right  /proc/[pid]  directory
162          and probe/enter the crashing process's namespaces if needed.
163
164       *  The  process  starts  with its current working directory as the root
165          directory.  If desired, it is possible change to the working  direc‐
166          tory  of  the dumping process by employing the value provided by the
167          %P specifier to change to the location of the  dumping  process  via
168          /proc/[pid]/cwd.
169
170       *  Command-line  arguments  can be supplied to the program (since Linux
171          2.6.24), delimited by white space (up to a total line length of  128
172          bytes).
173
174       *  The  RLIMIT_CORE limit is not enforced for core dumps that are piped
175          to a program via this mechanism.
176
177   /proc/sys/kernel/core_pipe_limit
178       When collecting core dumps via a pipe to a user-space program,  it  can
179       be  useful for the collecting program to gather data about the crashing
180       process from that process's /proc/[pid] directory.  In order to do this
181       safely,  the  kernel must wait for the program collecting the core dump
182       to exit, so as not to remove the crashing process's  /proc/[pid]  files
183       prematurely.   This  in turn creates the possibility that a misbehaving
184       collecting program can block the reaping of a crashed process by simply
185       never exiting.
186
187       Since Linux 2.6.32, the /proc/sys/kernel/core_pipe_limit can be used to
188       defend against this possibility.  The value in this  file  defines  how
189       many  concurrent crashing processes may be piped to user-space programs
190       in parallel.  If this value is exceeded, then those crashing  processes
191       above  this  value are noted in the kernel log and their core dumps are
192       skipped.
193
194       A value of 0 in this file is special.  It indicates that unlimited pro‐
195       cesses may be captured in parallel, but that no waiting will take place
196       (i.e., the collecting program is not guaranteed access to /proc/<crash‐
197       ing-PID>).  The default value for this file is 0.
198
199   Controlling which mappings are written to the core dump
200       Since  kernel  2.6.23,  the  Linux-specific /proc/[pid]/coredump_filter
201       file can be used to control which memory segments are  written  to  the
202       core  dump  file  in  the  event  that a core dump is performed for the
203       process with the corresponding process ID.
204
205       The value in the file is a  bit  mask  of  memory  mapping  types  (see
206       mmap(2)).   If  a  bit  is set in the mask, then memory mappings of the
207       corresponding type are dumped; otherwise they are not dumped.  The bits
208       in this file have the following meanings:
209
210           bit 0  Dump anonymous private mappings.
211           bit 1  Dump anonymous shared mappings.
212           bit 2  Dump file-backed private mappings.
213           bit 3  Dump file-backed shared mappings.
214           bit 4 (since Linux 2.6.24)
215                  Dump ELF headers.
216           bit 5 (since Linux 2.6.28)
217                  Dump private huge pages.
218           bit 6 (since Linux 2.6.28)
219                  Dump shared huge pages.
220           bit 7 (since Linux 4.4)
221                  Dump private DAX pages.
222           bit 8 (since Linux 4.4)
223                  Dump shared DAX pages.
224
225       By  default,  the  following  bits  are  set:  0,  1,  4  (if  the CON‐
226       FIG_CORE_DUMP_DEFAULT_ELF_HEADERS  kernel   configuration   option   is
227       enabled),  and  5.  This default can be modified at boot time using the
228       coredump_filter boot option.
229
230       The value of this file is displayed in hexadecimal.  (The default value
231       is thus displayed as 33.)
232
233       Memory-mapped I/O pages such as frame buffer are never dumped, and vir‐
234       tual DSO (vdso(7)) pages are always dumped,  regardless  of  the  core‐
235       dump_filter value.
236
237       A child process created via fork(2) inherits its parent's coredump_fil‐
238       ter value; the coredump_filter value is preserved across an execve(2).
239
240       It can be useful to set coredump_filter in the parent shell before run‐
241       ning a program, for example:
242
243           $ echo 0x7 > /proc/self/coredump_filter
244           $ ./some_program
245
246       This  file  is  provided  only  if  the  kernel was built with the CON‐
247       FIG_ELF_CORE configuration option.
248
249   Core dumps and systemd
250       On systems using the systemd(1)  init  framework,  core  dumps  may  be
251       placed  in a location determined by systemd(1).  To do this, systemd(1)
252       employs the core_pattern feature that allows piping  core  dumps  to  a
253       program.   One can verify this by checking whether core dumps are being
254       piped to the systemd-coredump(8) program:
255
256           $ cat /proc/sys/kernel/core_pattern
257           |/usr/lib/systemd/systemd-coredump %P %u %g %s %t %c %e
258
259       In this case, core dumps will be placed in the location configured  for
260       systemd-coredump(8), typically as lz4(1) compressed files in the direc‐
261       tory /var/lib/systemd/coredump/.  One can list the core dumps that have
262       been recorded by systemd-coredump(8) using coredumpctl(1):
263
264         $ coredumpctl list | tail -5
265         Wed 2017-10-11 22:25:30 CEST  2748 1000 1000 3 present  /usr/bin/sleep
266         Thu 2017-10-12 06:29:10 CEST  2716 1000 1000 3 present  /usr/bin/sleep
267         Thu 2017-10-12 06:30:50 CEST  2767 1000 1000 3 present  /usr/bin/sleep
268         Thu 2017-10-12 06:37:40 CEST  2918 1000 1000 3 present  /usr/bin/cat
269         Thu 2017-10-12 08:13:07 CEST  2955 1000 1000 3 present  /usr/bin/cat
270
271       The  information shown for each core dump includes the date and time of
272       the dump, the PID, UID, and GID  of the  dumping  process,  the  signal
273       number  that  caused  the core dump, and the pathname of the executable
274       that was being run by the dumped process.   Various  options  to  core‐
275       dumpctl(1)  allow  a specified coredump file to be pulled from the sys‐
276       temd(1) location into a specified file.  For example,  to  extract  the
277       core  dump for PID 2955 shown above to a file named core in the current
278       directory, one could use:
279
280           $ coredumpctl dump 2955 -o core
281
282       For more extensive details, see the coredumpctl(1) manual page.
283
284       To disable the systemd(1) mechanism that archives core dumps, restoring
285       to something more like traditional Linux behavior, one can set an over‐
286       ride for the systemd(1) mechanism, using something like:
287
288         # echo "kernel.core_pattern=core.%p" > /etc/sysctl.d/50-coredump.conf
289         # /lib/systemd/systemd-sysctl
290

NOTES

292       The gdb(1) gcore command can be used to obtain a core dump of a running
293       process.
294
295       In  Linux  versions  up  to  and  including  2.6.27, if a multithreaded
296       process (or, more precisely, a process  that  shares  its  memory  with
297       another  process  by  being created with the CLONE_VM flag of clone(2))
298       dumps core, then the process ID is always appended to  the  core  file‐
299       name, unless the process ID was already included elsewhere in the file‐
300       name via a %p specification in /proc/sys/kernel/core_pattern.  (This is
301       primarily  useful  when employing the obsolete LinuxThreads implementa‐
302       tion, where each thread of a process has a different PID.)
303

EXAMPLE

305       The program below can be used to demonstrate the use of the pipe syntax
306       in the /proc/sys/kernel/core_pattern file.  The following shell session
307       demonstrates the use of this program (compiled to create an  executable
308       named core_pattern_pipe_test):
309
310           $ cc -o core_pattern_pipe_test core_pattern_pipe_test.c
311           $ su
312           Password:
313           # echo "|$PWD/core_pattern_pipe_test %p UID=%u GID=%g sig=%s" > \
314               /proc/sys/kernel/core_pattern
315           # exit
316           $ sleep 100
317           ^\                     # type control-backslash
318           Quit (core dumped)
319           $ cat core.info
320           argc=5
321           argc[0]=</home/mtk/core_pattern_pipe_test>
322           argc[1]=<20575>
323           argc[2]=<UID=1000>
324           argc[3]=<GID=100>
325           argc[4]=<sig=3>
326           Total bytes in core dump: 282624
327
328   Program source
329
330       /* core_pattern_pipe_test.c */
331
332       #define _GNU_SOURCE
333       #include <sys/stat.h>
334       #include <fcntl.h>
335       #include <limits.h>
336       #include <stdio.h>
337       #include <stdlib.h>
338       #include <unistd.h>
339
340       #define BUF_SIZE 1024
341
342       int
343       main(int argc, char *argv[])
344       {
345           int tot, j;
346           ssize_t nread;
347           char buf[BUF_SIZE];
348           FILE *fp;
349           char cwd[PATH_MAX];
350
351           /* Change our current working directory to that of the
352              crashing process */
353
354           snprintf(cwd, PATH_MAX, "/proc/%s/cwd", argv[1]);
355           chdir(cwd);
356
357           /* Write output to file "core.info" in that directory */
358
359           fp = fopen("core.info", "w+");
360           if (fp == NULL)
361               exit(EXIT_FAILURE);
362
363           /* Display command-line arguments given to core_pattern
364              pipe program */
365
366           fprintf(fp, "argc=%d\n", argc);
367           for (j = 0; j < argc; j++)
368               fprintf(fp, "argc[%d]=<%s>\n", j, argv[j]);
369
370           /* Count bytes in standard input (the core dump) */
371
372           tot = 0;
373           while ((nread = read(STDIN_FILENO, buf, BUF_SIZE)) > 0)
374               tot += nread;
375           fprintf(fp, "Total bytes in core dump: %d\n", tot);
376
377           fclose(fp);
378           exit(EXIT_SUCCESS);
379       }
380

SEE ALSO

382       bash(1),   coredumpctl(1),  gdb(1),  getrlimit(2),  mmap(2),  prctl(2),
383       sigaction(2), elf(5), proc(5),  pthreads(7),  signal(7),  systemd-core‐
384       dump(8)
385

COLOPHON

387       This  page  is  part of release 5.02 of the Linux man-pages project.  A
388       description of the project, information about reporting bugs,  and  the
389       latest     version     of     this    page,    can    be    found    at
390       https://www.kernel.org/doc/man-pages/.
391
392
393
394Linux                             2019-03-06                           CORE(5)
Impressum