1<?xml version='1.0'?> <!--*-nxml-*-->
2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
5
6<refentry id="coredumpctl" conditional='ENABLE_COREDUMP'
7    xmlns:xi="http://www.w3.org/2001/XInclude">
8
9  <refentryinfo>
10    <title>coredumpctl</title>
11    <productname>systemd</productname>
12  </refentryinfo>
13
14  <refmeta>
15    <refentrytitle>coredumpctl</refentrytitle>
16    <manvolnum>1</manvolnum>
17  </refmeta>
18
19  <refnamediv>
20    <refname>coredumpctl</refname>
21    <refpurpose>Retrieve and process saved core dumps and metadata</refpurpose>
22  </refnamediv>
23
24  <refsynopsisdiv>
25    <cmdsynopsis>
26      <command>coredumpctl</command>
27      <arg choice="opt" rep="repeat">OPTIONS</arg>
28      <arg choice="req">COMMAND</arg>
29      <arg choice="opt" rep="repeat">PID|COMM|EXE|MATCH</arg>
30    </cmdsynopsis>
31  </refsynopsisdiv>
32
33  <refsect1>
34    <title>Description</title>
35
36    <para><command>coredumpctl</command> is a tool that can be used to retrieve and process core
37    dumps and metadata which were saved by
38    <citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
39    </para>
40  </refsect1>
41
42  <refsect1>
43    <title>Commands</title>
44
45    <para>The following commands are understood:</para>
46
47    <variablelist>
48      <varlistentry>
49        <term><command>list</command></term>
50
51        <listitem><para>List core dumps captured in the journal
52        matching specified characteristics. If no command is
53        specified, this is the implied default.</para>
54
55        <para>The output is designed to be human readable and contains a table with the following
56        columns:</para>
57        <variablelist>
58          <varlistentry>
59            <term>TIME</term>
60            <listitem><para>The timestamp of the crash, as reported by the kernel.</para>
61            </listitem>
62          </varlistentry>
63
64          <varlistentry>
65            <term>PID</term>
66            <listitem><para>The identifier of the process that crashed.</para>
67            </listitem>
68          </varlistentry>
69
70          <varlistentry>
71            <term>UID</term>
72            <term>GID</term>
73            <listitem><para>The user and group identifiers of the process that crashed.</para>
74            </listitem>
75          </varlistentry>
76
77          <varlistentry>
78            <term>SIGNAL</term>
79            <listitem><para>The signal that caused the process to crash, when applicable.
80            </para></listitem>
81          </varlistentry>
82
83          <varlistentry>
84            <term>COREFILE</term>
85            <listitem><para>Information whether the coredump was stored, and whether
86            it is still accessible: <literal>none</literal> means the core was
87            not stored, <literal>-</literal> means that it was not available (for
88            example because the process was not terminated by a signal),
89            <literal>present</literal> means that the core file is accessible by the
90            current user, <literal>journal</literal> means that the core was stored
91            in the <literal>journal</literal>, <literal>truncated</literal> is the
92            same as one of the previous two, but the core was too large and was not
93            stored in its entirety, <literal>error</literal> means that the core file
94            cannot be accessed, most likely because of insufficient permissions, and
95            <literal>missing</literal> means that the core was stored in a file, but
96            this file has since been removed.</para></listitem>
97          </varlistentry>
98
99          <varlistentry>
100            <term>EXE</term>
101            <listitem><para>The full path to the executable. For backtraces of scripts
102            this is the name of the interpreter.</para></listitem>
103          </varlistentry>
104        </variablelist>
105
106        <para>It's worth noting that different restrictions apply to
107        data saved in the journal and core dump files saved in
108        <filename>/var/lib/systemd/coredump</filename>, see overview in
109        <citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
110        Thus it may very well happen that a particular core dump is still listed
111        in the journal while its corresponding core dump file has already been
112        removed.</para></listitem>
113      </varlistentry>
114
115      <varlistentry>
116        <term><command>info</command></term>
117
118        <listitem><para>Show detailed information about the last core dump
119        or core dumps matching specified characteristics
120        captured in the journal.</para></listitem>
121      </varlistentry>
122
123      <varlistentry>
124        <term><command>dump</command></term>
125
126        <listitem><para>Extract the last core dump matching specified
127        characteristics. The core dump will be written on standard
128        output, unless an output file is specified with
129        <option>--output=</option>. </para></listitem>
130      </varlistentry>
131
132      <varlistentry>
133        <term><command>debug</command></term>
134
135        <listitem><para>Invoke a debugger on the last core dump
136        matching specified characteristics. By default,
137        <citerefentry project='man-pages'><refentrytitle>gdb</refentrytitle><manvolnum>1</manvolnum></citerefentry>
138        will be used. This may be changed using the <option>--debugger=</option>
139        option or the <varname>$SYSTEMD_DEBUGGER</varname> environment
140        variable. Use the <option>--debugger-arguments=</option> option to pass extra
141        command line arguments to the debugger.</para></listitem>
142      </varlistentry>
143
144    </variablelist>
145
146  </refsect1>
147
148  <refsect1>
149    <title>Options</title>
150
151    <para>The following options are understood:</para>
152
153    <variablelist>
154
155      <xi:include href="standard-options.xml" xpointer="help" />
156      <xi:include href="standard-options.xml" xpointer="version" />
157      <xi:include href="standard-options.xml" xpointer="no-pager" />
158      <xi:include href="standard-options.xml" xpointer="no-legend" />
159      <xi:include href="standard-options.xml" xpointer="json" />
160
161      <varlistentry>
162        <term><option>-1</option></term>
163
164        <listitem><para>Show information of the most recent core dump only, instead of listing all known core
165        dumps. Equivalent to <option>--reverse -n 1</option>.</para></listitem>
166      </varlistentry>
167
168      <varlistentry>
169        <term><option>-n</option> <replaceable>INT</replaceable></term>
170
171        <listitem><para>Show at most the specified number of entries. The specified parameter must be an
172        integer greater or equal to 1.</para></listitem>
173      </varlistentry>
174
175      <varlistentry>
176        <term><option>-S</option></term>
177        <term><option>--since</option></term>
178
179        <listitem><para>Only print entries which are since the specified date.</para></listitem>
180      </varlistentry>
181
182      <varlistentry>
183        <term><option>-U</option></term>
184        <term><option>--until</option></term>
185
186        <listitem><para>Only print entries which are until the specified date.</para></listitem>
187      </varlistentry>
188
189      <varlistentry>
190        <term><option>-r</option></term>
191        <term><option>--reverse</option></term>
192
193        <listitem><para>Reverse output so that the newest entries are displayed first.
194        </para></listitem>
195      </varlistentry>
196
197      <varlistentry>
198        <term><option>-F</option> <replaceable>FIELD</replaceable></term>
199        <term><option>--field=</option><replaceable>FIELD</replaceable></term>
200
201        <listitem><para>Print all possible data values the specified
202        field takes in matching core dump entries of the
203        journal.</para></listitem>
204      </varlistentry>
205
206      <varlistentry>
207        <term><option>-o</option> <replaceable>FILE</replaceable></term>
208        <term><option>--output=</option><replaceable>FILE</replaceable></term>
209
210        <listitem><para>Write the core to <option>FILE</option>.
211        </para></listitem>
212      </varlistentry>
213
214      <varlistentry>
215        <term><option>--debugger=</option><replaceable>DEBUGGER</replaceable></term>
216
217        <listitem><para>Use the given debugger for the <command>debug</command>
218        command. If not given and <varname>$SYSTEMD_DEBUGGER</varname> is unset, then
219        <citerefentry project='man-pages'><refentrytitle>gdb</refentrytitle><manvolnum>1</manvolnum></citerefentry>
220        will be used. </para></listitem>
221      </varlistentry>
222
223      <varlistentry>
224        <term><option>-A</option> <replaceable>ARGS</replaceable></term>
225        <term><option>--debugger-arguments=</option><replaceable>ARGS</replaceable></term>
226
227        <listitem><para>Pass the given <replaceable>ARGS</replaceable> as extra command line arguments
228        to the debugger. Quote as appropriate when <replaceable>ARGS</replaceable> contain whitespace.
229        (See Examples.)</para></listitem>
230      </varlistentry>
231
232      <varlistentry>
233        <term><option>--file=<replaceable>GLOB</replaceable></option></term>
234
235        <listitem><para>Takes a file glob as an argument. If
236        specified, coredumpctl will operate on the specified journal
237        files matching <replaceable>GLOB</replaceable> instead of the
238        default runtime and system journal paths. May be specified
239        multiple times, in which case files will be suitably
240        interleaved.</para></listitem>
241      </varlistentry>
242
243      <varlistentry>
244        <term><option>-D</option> <replaceable>DIR</replaceable></term>
245        <term><option>--directory=</option><replaceable>DIR</replaceable></term>
246
247        <listitem><para>Use the journal files in the specified <option>DIR</option>.
248        </para></listitem>
249      </varlistentry>
250
251      <varlistentry>
252        <term><option>-q</option></term>
253        <term><option>--quiet</option></term>
254
255        <listitem><para>Suppresses informational messages about lack
256        of access to journal files and possible in-flight coredumps.
257        </para></listitem>
258      </varlistentry>
259
260      <varlistentry>
261        <term><option>--all</option></term>
262
263        <listitem><para>Look at all available journal files in <filename>/var/log/journal/</filename>
264        (excluding journal namespaces) instead of only local ones.</para></listitem>
265      </varlistentry>
266    </variablelist>
267  </refsect1>
268
269  <refsect1>
270    <title>Matching</title>
271
272    <para>A match can be:</para>
273
274    <variablelist>
275      <varlistentry>
276        <term><replaceable>PID</replaceable></term>
277
278        <listitem><para>Process ID of the
279        process that dumped
280        core. An integer.</para></listitem>
281      </varlistentry>
282
283      <varlistentry>
284        <term><replaceable>COMM</replaceable></term>
285
286        <listitem><para>Name of the executable (matches
287        <option>COREDUMP_COMM=</option>). Must not contain slashes.
288        </para></listitem>
289      </varlistentry>
290
291      <varlistentry>
292        <term><replaceable>EXE</replaceable></term>
293
294        <listitem><para>Path to the executable (matches
295        <option>COREDUMP_EXE=</option>). Must contain at least one
296        slash. </para></listitem>
297      </varlistentry>
298
299      <varlistentry>
300        <term><replaceable>MATCH</replaceable></term>
301
302        <listitem><para>General journalctl match filter, must contain an equals
303        sign (<literal>=</literal>). See
304        <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
305        </para></listitem>
306      </varlistentry>
307    </variablelist>
308  </refsect1>
309
310  <refsect1>
311    <title>Exit status</title>
312    <para>On success, 0 is returned; otherwise, a non-zero failure
313    code is returned. Not finding any matching core dumps is treated as
314    failure.
315    </para>
316  </refsect1>
317
318  <refsect1>
319    <title>Environment</title>
320
321    <variablelist class='environment-variables'>
322      <varlistentry>
323        <term><varname>$SYSTEMD_DEBUGGER</varname></term>
324        <listitem><para>Use the given debugger for the <command>debug</command>
325        command. See the <option>--debugger=</option> option.</para></listitem>
326      </varlistentry>
327    </variablelist>
328  </refsect1>
329
330  <refsect1>
331    <title>Examples</title>
332
333    <example>
334      <title>List all the core dumps of a program</title>
335
336      <programlisting>$ coredumpctl list /usr/lib64/firefox/firefox
337TIME     PID  UID  GID SIG     COREFILE EXE                         SIZE
338Tue …   8018 1000 1000 SIGSEGV missing  /usr/lib64/firefox/firefox   n/a
339Wed … 251609 1000 1000 SIGTRAP missing  /usr/lib64/firefox/firefox   n/a
340Fri … 552351 1000 1000 SIGSEGV present  /usr/lib64/firefox/firefox 28.7M
341</programlisting>
342
343       <para>The journal has three entries pertaining to <filename>/usr/lib64/firefox/firefox</filename>, and
344       only the last entry still has an available core file (in external storage on disk).</para>
345
346       <para>Note that <filename>coredumpctl</filename> needs access to the journal files to retrieve the
347       relevant entries from the journal. Thus, an unprivileged user will normally only see information about
348       crashing programs of this user.</para>
349    </example>
350
351    <example>
352      <title>Invoke <command>gdb</command> on the last core dump</title>
353
354      <programlisting>$ coredumpctl debug</programlisting>
355    </example>
356
357    <example>
358      <title>Use <command>gdb</command> to display full register info from the last core dump</title>
359
360      <programlisting>$ coredumpctl debug --debugger-arguments="-batch -ex 'info all-registers'"</programlisting>
361    </example>
362
363    <example>
364      <title>Show information about a core dump matched by PID</title>
365
366      <programlisting>$ coredumpctl info 6654
367           PID: 6654 (bash)
368           UID: 1000 (user)
369           GID: 1000 (user)
370        Signal: 11 (SEGV)
371     Timestamp: Mon 2021-01-01 00:00:01 CET (20s ago)
372  Command Line: bash -c $'kill -SEGV $$'
373    Executable: /usr/bin/bash
374 Control Group: /user.slice/user-1000.slice/…
375          Unit: user@1000.service
376     User Unit: vte-spawn-….scope
377         Slice: user-1000.slice
378     Owner UID: 1000 (user)
379       Boot ID: …
380    Machine ID: …
381      Hostname: …
382       Storage: /var/lib/systemd/coredump/core.bash.1000.….zst (present)
383     Disk Size: 51.7K
384       Message: Process 130414 (bash) of user 1000 dumped core.
385
386                Stack trace of thread 130414:
387                #0  0x00007f398142358b kill (libc.so.6 + 0x3d58b)
388                #1  0x0000558c2c7fda09 kill_builtin (bash + 0xb1a09)
389                #2  0x0000558c2c79dc59 execute_builtin.lto_priv.0 (bash + 0x51c59)
390                #3  0x0000558c2c79709c execute_simple_command (bash + 0x4b09c)
391                #4  0x0000558c2c798408 execute_command_internal (bash + 0x4c408)
392                #5  0x0000558c2c7f6bdc parse_and_execute (bash + 0xaabdc)
393                #6  0x0000558c2c85415c run_one_command.isra.0 (bash + 0x10815c)
394                #7  0x0000558c2c77d040 main (bash + 0x31040)
395                #8  0x00007f398140db75 __libc_start_main (libc.so.6 + 0x27b75)
396                #9  0x0000558c2c77dd1e _start (bash + 0x31d1e)
397</programlisting>
398    </example>
399
400    <example>
401      <title>Extract the last core dump of /usr/bin/bar to a file named
402      <filename index="false">bar.coredump</filename></title>
403
404      <programlisting>$ coredumpctl -o bar.coredump dump /usr/bin/bar</programlisting>
405    </example>
406  </refsect1>
407
408  <refsect1>
409    <title>See Also</title>
410    <para>
411      <citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
412      <citerefentry><refentrytitle>coredump.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
413      <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
414      <citerefentry project='man-pages'><refentrytitle>gdb</refentrytitle><manvolnum>1</manvolnum></citerefentry>
415    </para>
416  </refsect1>
417
418</refentry>
419