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

NOTES

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

EXAMPLES

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

SEE ALSO

410       bash(1),   coredumpctl(1),  gdb(1),  getrlimit(2),  mmap(2),  prctl(2),
411       sigaction(2), elf(5), proc(5),  pthreads(7),  signal(7),  systemd-core‐
412       dump(8)
413
414
415
416Linux man-pages 6.04              2023-02-05                           core(5)
Impressum