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

NOTES

319       The gdb(1) gcore command can be used to obtain a core dump of a running
320       process.
321
322       In  Linux  versions  up  to  and  including  2.6.27, if a multithreaded
323       process (or, more precisely, a process that shares its memory with  an‐
324       other  process  by  being  created  with the CLONE_VM flag of clone(2))
325       dumps core, then the process ID is always appended to  the  core  file‐
326       name, unless the process ID was already included elsewhere in the file‐
327       name via a %p specification in /proc/sys/kernel/core_pattern.  (This is
328       primarily  useful  when employing the obsolete LinuxThreads implementa‐
329       tion, where each thread of a process has a different PID.)
330

EXAMPLES

332       The program below can be used to demonstrate the use of the pipe syntax
333       in the /proc/sys/kernel/core_pattern file.  The following shell session
334       demonstrates the use of this program (compiled to create an  executable
335       named core_pattern_pipe_test):
336
337           $ cc -o core_pattern_pipe_test core_pattern_pipe_test.c
338           $ su
339           Password:
340           # echo "|$PWD/core_pattern_pipe_test %p UID=%u GID=%g sig=%s" > \
341               /proc/sys/kernel/core_pattern
342           # exit
343           $ sleep 100
344           ^\                     # type control-backslash
345           Quit (core dumped)
346           $ cat core.info
347           argc=5
348           argc[0]=</home/mtk/core_pattern_pipe_test>
349           argc[1]=<20575>
350           argc[2]=<UID=1000>
351           argc[3]=<GID=100>
352           argc[4]=<sig=3>
353           Total bytes in core dump: 282624
354
355   Program source
356
357       /* core_pattern_pipe_test.c */
358
359       #define _GNU_SOURCE
360       #include <sys/stat.h>
361       #include <fcntl.h>
362       #include <limits.h>
363       #include <stdio.h>
364       #include <stdlib.h>
365       #include <unistd.h>
366
367       #define BUF_SIZE 1024
368
369       int
370       main(int argc, char *argv[])
371       {
372           ssize_t nread, tot;
373           char buf[BUF_SIZE];
374           FILE *fp;
375           char cwd[PATH_MAX];
376
377           /* Change our current working directory to that of the
378              crashing process */
379
380           snprintf(cwd, PATH_MAX, "/proc/%s/cwd", argv[1]);
381           chdir(cwd);
382
383           /* Write output to file "core.info" in that directory */
384
385           fp = fopen("core.info", "w+");
386           if (fp == NULL)
387               exit(EXIT_FAILURE);
388
389           /* Display command-line arguments given to core_pattern
390              pipe program */
391
392           fprintf(fp, "argc=%d\n", argc);
393           for (int j = 0; j < argc; j++)
394               fprintf(fp, "argc[%d]=<%s>\n", j, argv[j]);
395
396           /* Count bytes in standard input (the core dump) */
397
398           tot = 0;
399           while ((nread = read(STDIN_FILENO, buf, BUF_SIZE)) > 0)
400               tot += nread;
401           fprintf(fp, "Total bytes in core dump: %zd\n", tot);
402
403           fclose(fp);
404           exit(EXIT_SUCCESS);
405       }
406

SEE ALSO

408       bash(1),   coredumpctl(1),  gdb(1),  getrlimit(2),  mmap(2),  prctl(2),
409       sigaction(2), elf(5), proc(5),  pthreads(7),  signal(7),  systemd-core‐
410       dump(8)
411

COLOPHON

413       This  page  is  part of release 5.10 of the Linux man-pages project.  A
414       description of the project, information about reporting bugs,  and  the
415       latest     version     of     this    page,    can    be    found    at
416       https://www.kernel.org/doc/man-pages/.
417
418
419
420Linux                             2020-11-01                           CORE(5)
Impressum