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+ -->
6 <refentry id=
"coredumpctl" conditional='ENABLE_COREDUMP'
7 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
10 <title>coredumpctl
</title>
11 <productname>systemd
</productname>
15 <refentrytitle>coredumpctl
</refentrytitle>
16 <manvolnum>1</manvolnum>
20 <refname>coredumpctl
</refname>
21 <refpurpose>Retrieve and process saved core dumps and metadata
</refpurpose>
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>
34 <title>Description
</title>
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>.
43 <title>Commands
</title>
45 <para>The following commands are understood:
</para>
49 <term><command>list
</command></term>
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>
55 <para>The output is designed to be human readable and contains list contains
56 a table with the following columns:
</para>
60 <listitem><para>The timestamp of the crash, as reported by the kernel.
</para>
66 <listitem><para>The identifier of the process that crashed.
</para>
73 <listitem><para>The user and group identifiers of the process that crashed.
</para>
79 <listitem><para>The signal that caused the process to crash, when applicable.
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>
101 <listitem><para>The full path to the executable. For backtraces of scripts
102 this is the name of the interpreter.
</para></listitem>
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>
116 <term><command>info
</command></term>
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>
124 <term><command>dump
</command></term>
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>
133 <term><command>debug
</command></term>
135 <listitem><para>Invoke a debugger on the last core dump
136 matching specified characteristics. By default,
137 <citerefentry><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.
</para></listitem>
148 <title>Options
</title>
150 <para>The following options are understood:
</para>
154 <xi:include href=
"standard-options.xml" xpointer=
"help" />
155 <xi:include href=
"standard-options.xml" xpointer=
"version" />
158 <term><option>--no-legend
</option></term>
160 <listitem><para>Do not print column headers.
</para></listitem>
163 <xi:include href=
"standard-options.xml" xpointer=
"no-pager" />
166 <term><option>-
1</option></term>
168 <listitem><para>Show information of a single core dump only, instead of listing
169 all known core dumps.
</para></listitem>
173 <term><option>-S
</option></term>
174 <term><option>--since
</option></term>
176 <listitem><para>Only print entries which are since the specified date.
</para></listitem>
180 <term><option>-U
</option></term>
181 <term><option>--until
</option></term>
183 <listitem><para>Only print entries which are until the specified date.
</para></listitem>
187 <term><option>-r
</option></term>
188 <term><option>--reverse
</option></term>
190 <listitem><para>Reverse output so that the newest entries are displayed first.
195 <term><option>-F
</option> <replaceable>FIELD
</replaceable></term>
196 <term><option>--field=
</option><replaceable>FIELD
</replaceable></term>
198 <listitem><para>Print all possible data values the specified
199 field takes in matching core dump entries of the
200 journal.
</para></listitem>
204 <term><option>-o
</option> <replaceable>FILE
</replaceable></term>
205 <term><option>--output=
</option><replaceable>FILE
</replaceable></term>
207 <listitem><para>Write the core to
<option>FILE
</option>.
212 <term><option>--debugger=
</option><replaceable>DEBUGGER
</replaceable></term>
214 <listitem><para>Use the given debugger for the
<command>debug
</command>
215 command. If not given and
<varname>$SYSTEMD_DEBUGGER
</varname> is unset, then
216 <citerefentry><refentrytitle>gdb
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
217 will be used.
</para></listitem>
221 <term><option>--file=
<replaceable>GLOB
</replaceable></option></term>
223 <listitem><para>Takes a file glob as an argument. If
224 specified, coredumpctl will operate on the specified journal
225 files matching
<replaceable>GLOB
</replaceable> instead of the
226 default runtime and system journal paths. May be specified
227 multiple times, in which case files will be suitably
228 interleaved.
</para></listitem>
232 <term><option>-D
</option> <replaceable>DIR
</replaceable></term>
233 <term><option>--directory=
</option><replaceable>DIR
</replaceable></term>
235 <listitem><para>Use the journal files in the specified
<option>DIR
</option>.
240 <term><option>-q
</option></term>
241 <term><option>--quiet
</option></term>
243 <listitem><para>Suppresses informational messages about lack
244 of access to journal files and possible in-flight coredumps.
251 <title>Matching
</title>
253 <para>A match can be:
</para>
257 <term><replaceable>PID
</replaceable></term>
259 <listitem><para>Process ID of the
261 core. An integer.
</para></listitem>
265 <term><replaceable>COMM
</replaceable></term>
267 <listitem><para>Name of the executable (matches
268 <option>COREDUMP_COMM=
</option>). Must not contain slashes.
273 <term><replaceable>EXE
</replaceable></term>
275 <listitem><para>Path to the executable (matches
276 <option>COREDUMP_EXE=
</option>). Must contain at least one
277 slash.
</para></listitem>
281 <term><replaceable>MATCH
</replaceable></term>
283 <listitem><para>General journalctl match filter, must contain an equals
284 sign (
<literal>=
</literal>). See
285 <citerefentry><refentrytitle>journalctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
292 <title>Exit status
</title>
293 <para>On success,
0 is returned; otherwise, a non-zero failure
294 code is returned. Not finding any matching core dumps is treated as
300 <title>Environment
</title>
302 <variablelist class='environment-variables'
>
304 <term><varname>$SYSTEMD_DEBUGGER
</varname></term>
305 <listitem><para>Use the given debugger for the
<command>debug
</command>
306 command. See the
<option>--debugger=
</option> option.
</para></listitem>
312 <title>Examples
</title>
315 <title>List all the core dumps of a program named foo
</title>
317 <programlisting># coredumpctl list foo
</programlisting>
321 <title>Invoke gdb on the last core dump
</title>
323 <programlisting># coredumpctl debug
</programlisting>
327 <title>Show information about a process that dumped core,
328 matching by its PID
6654</title>
330 <programlisting># coredumpctl info
6654</programlisting>
334 <title>Extract the last core dump of /usr/bin/bar to a file named
335 <filename index=
"false">bar.coredump
</filename></title>
337 <programlisting># coredumpctl -o bar.coredump dump /usr/bin/bar
</programlisting>
342 <title>See Also
</title>
344 <citerefentry><refentrytitle>systemd-coredump
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
345 <citerefentry><refentrytitle>coredump.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
346 <citerefentry><refentrytitle>systemd-journald.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
347 <citerefentry project='man-pages'
><refentrytitle>gdb
</refentrytitle><manvolnum>1</manvolnum></citerefentry>