2012-10-19 14:29:46 +04:00
<?xml version='1.0'?> <!-- * - nxml - * -->
2019-03-14 16:40:58 +03:00
< !DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
2015-06-18 20:47:44 +03:00
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
2020-11-09 07:23:58 +03:00
<!-- SPDX - License - Identifier: LGPL - 2.1 - or - later -->
2012-10-19 14:29:46 +04:00
2014-06-19 15:46:01 +04:00
<refentry id= "coredumpctl" conditional= 'ENABLE_COREDUMP'
2015-02-04 05:14:13 +03:00
xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo >
<title > coredumpctl</title>
<productname > systemd</productname>
</refentryinfo>
<refmeta >
<refentrytitle > coredumpctl</refentrytitle>
<manvolnum > 1</manvolnum>
</refmeta>
<refnamediv >
<refname > coredumpctl</refname>
2016-05-16 12:56:04 +03:00
<refpurpose > Retrieve and process saved core dumps and metadata</refpurpose>
2015-02-04 05:14:13 +03:00
</refnamediv>
<refsynopsisdiv >
<cmdsynopsis >
<command > coredumpctl</command>
<arg choice= "opt" rep= "repeat" > OPTIONS</arg>
<arg choice= "req" > COMMAND</arg>
<arg choice= "opt" rep= "repeat" > PID|COMM|EXE|MATCH</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1 >
<title > Description</title>
2016-05-16 12:56:04 +03:00
<para > <command > coredumpctl</command> is a tool that can be used to retrieve and process core
dumps and metadata which were saved by
<citerefentry > <refentrytitle > systemd-coredump</refentrytitle> <manvolnum > 8</manvolnum> </citerefentry> .
</para>
2015-02-04 05:14:13 +03:00
</refsect1>
2016-05-16 12:56:04 +03:00
<refsect1 >
<title > Commands</title>
2015-02-04 05:14:13 +03:00
<para > The following commands are understood:</para>
<variablelist >
<varlistentry >
<term > <command > list</command> </term>
2016-05-16 12:56:04 +03:00
<listitem > <para > List core dumps captured in the journal
2015-02-04 05:14:13 +03:00
matching specified characteristics. If no command is
2016-05-16 12:56:04 +03:00
specified, this is the implied default.</para>
2020-07-06 11:49:59 +03:00
<para > The output is designed to be human readable and contains a table with the following
columns:</para>
2017-02-26 01:29:14 +03:00
<variablelist >
<varlistentry >
<term > TIME</term>
<listitem > <para > The timestamp of the crash, as reported by the kernel.</para>
</listitem>
</varlistentry>
<varlistentry >
<term > PID</term>
<listitem > <para > The identifier of the process that crashed.</para>
</listitem>
</varlistentry>
<varlistentry >
<term > UID</term>
<term > GID</term>
<listitem > <para > The user and group identifiers of the process that crashed.</para>
</listitem>
</varlistentry>
<varlistentry >
<term > SIGNAL</term>
<listitem > <para > The signal that caused the process to crash, when applicable.
</para> </listitem>
</varlistentry>
<varlistentry >
<term > COREFILE</term>
<listitem > <para > Information whether the coredump was stored, and whether
2017-08-04 00:36:21 +03:00
it is still accessible: <literal > none</literal> means the core was
2017-02-26 01:29:14 +03:00
not stored, <literal > -</literal> means that it was not available (for
example because the process was not terminated by a signal),
<literal > present</literal> means that the core file is accessible by the
current user, <literal > journal</literal> means that the core was stored
in the <literal > journal</literal> , <literal > truncated</literal> is the
same as one of the previous two, but the core was too large and was not
stored in its entirety, <literal > error</literal> means that the core file
cannot be accessed, most likely because of insufficient permissions, and
<literal > missing</literal> means that the core was stored in a file, but
this file has since been removed.</para> </listitem>
</varlistentry>
<varlistentry >
<term > EXE</term>
<listitem > <para > The full path to the executable. For backtraces of scripts
this is the name of the interpreter.</para> </listitem>
</varlistentry>
</variablelist>
2016-05-16 12:56:04 +03:00
<para > It's worth noting that different restrictions apply to
data saved in the journal and core dump files saved in
<filename > /var/lib/systemd/coredump</filename> , see overview in
<citerefentry > <refentrytitle > systemd-coredump</refentrytitle> <manvolnum > 8</manvolnum> </citerefentry> .
Thus it may very well happen that a particular core dump is still listed
in the journal while its corresponding core dump file has already been
removed.</para> </listitem>
2015-02-04 05:14:13 +03:00
</varlistentry>
<varlistentry >
<term > <command > info</command> </term>
2018-07-08 01:00:39 +03:00
<listitem > <para > Show detailed information about the last core dump
or core dumps matching specified characteristics
2015-02-04 05:14:13 +03:00
captured in the journal.</para> </listitem>
</varlistentry>
<varlistentry >
<term > <command > dump</command> </term>
2016-05-16 12:56:04 +03:00
<listitem > <para > Extract the last core dump matching specified
characteristics. The core dump will be written on standard
2015-02-04 05:14:13 +03:00
output, unless an output file is specified with
2015-08-25 21:04:55 +03:00
<option > --output=</option> . </para> </listitem>
2015-02-04 05:14:13 +03:00
</varlistentry>
<varlistentry >
2018-04-18 22:32:17 +03:00
<term > <command > debug</command> </term>
<listitem > <para > Invoke a debugger on the last core dump
matching specified characteristics. By default,
2020-06-25 15:37:24 +03:00
<citerefentry project= 'man-pages' > <refentrytitle > gdb</refentrytitle> <manvolnum > 1</manvolnum> </citerefentry>
2018-04-18 22:32:17 +03:00
will be used. This may be changed using the <option > --debugger=</option>
option or the <varname > $SYSTEMD_DEBUGGER</varname> environment
2020-12-14 17:44:36 +03:00
variable. Use the <option > --debugger-arguments=</option> option to pass extra
command line arguments to the debugger.</para> </listitem>
2015-02-04 05:14:13 +03:00
</varlistentry>
</variablelist>
</refsect1>
2019-10-08 18:58:44 +03:00
<refsect1 >
<title > Options</title>
<para > The following options are understood:</para>
<variablelist >
<xi:include href= "standard-options.xml" xpointer= "help" />
<xi:include href= "standard-options.xml" xpointer= "version" />
2021-02-09 18:43:55 +03:00
<xi:include href= "standard-options.xml" xpointer= "no-pager" />
<xi:include href= "standard-options.xml" xpointer= "no-legend" />
<xi:include href= "standard-options.xml" xpointer= "json" />
2019-10-08 18:58:44 +03:00
<varlistentry >
2021-02-09 18:43:55 +03:00
<term > <option > -1</option> </term>
2019-10-08 18:58:44 +03:00
2021-02-09 18:43:55 +03:00
<listitem > <para > Show information of the most recent core dump only, instead of listing all known core
2021-07-27 10:37:29 +03:00
dumps. Equivalent to <option > --reverse -n 1</option> .</para> </listitem>
2019-10-08 18:58:44 +03:00
</varlistentry>
<varlistentry >
2021-02-09 18:43:55 +03:00
<term > <option > -n</option> <replaceable > INT</replaceable> </term>
2019-10-08 18:58:44 +03:00
2021-02-09 18:43:55 +03:00
<listitem > <para > Show at most the specified number of entries. The specified parameter must be an
integer greater or equal to 1.</para> </listitem>
2019-10-08 18:58:44 +03:00
</varlistentry>
<varlistentry >
<term > <option > -S</option> </term>
<term > <option > --since</option> </term>
<listitem > <para > Only print entries which are since the specified date.</para> </listitem>
</varlistentry>
<varlistentry >
<term > <option > -U</option> </term>
<term > <option > --until</option> </term>
<listitem > <para > Only print entries which are until the specified date.</para> </listitem>
</varlistentry>
<varlistentry >
<term > <option > -r</option> </term>
<term > <option > --reverse</option> </term>
<listitem > <para > Reverse output so that the newest entries are displayed first.
</para> </listitem>
</varlistentry>
<varlistentry >
<term > <option > -F</option> <replaceable > FIELD</replaceable> </term>
<term > <option > --field=</option> <replaceable > FIELD</replaceable> </term>
<listitem > <para > Print all possible data values the specified
field takes in matching core dump entries of the
journal.</para> </listitem>
</varlistentry>
<varlistentry >
<term > <option > -o</option> <replaceable > FILE</replaceable> </term>
<term > <option > --output=</option> <replaceable > FILE</replaceable> </term>
<listitem > <para > Write the core to <option > FILE</option> .
</para> </listitem>
</varlistentry>
<varlistentry >
<term > <option > --debugger=</option> <replaceable > DEBUGGER</replaceable> </term>
<listitem > <para > Use the given debugger for the <command > debug</command>
command. If not given and <varname > $SYSTEMD_DEBUGGER</varname> is unset, then
2020-06-25 15:37:24 +03:00
<citerefentry project= 'man-pages' > <refentrytitle > gdb</refentrytitle> <manvolnum > 1</manvolnum> </citerefentry>
2019-10-08 18:58:44 +03:00
will be used. </para> </listitem>
</varlistentry>
2020-12-14 17:44:36 +03:00
<varlistentry >
<term > <option > -A</option> <replaceable > ARGS</replaceable> </term>
<term > <option > --debugger-arguments=</option> <replaceable > ARGS</replaceable> </term>
<listitem > <para > Pass the given <replaceable > ARGS</replaceable> as extra command line arguments
to the debugger. Quote as appropriate when <replaceable > ARGS</replaceable> contain whitespace.
(See Examples.)</para> </listitem>
</varlistentry>
2020-04-12 21:39:09 +03:00
<varlistentry >
<term > <option > --file=<replaceable > GLOB</replaceable> </option> </term>
<listitem > <para > Takes a file glob as an argument. If
specified, coredumpctl will operate on the specified journal
files matching <replaceable > GLOB</replaceable> instead of the
default runtime and system journal paths. May be specified
multiple times, in which case files will be suitably
interleaved.</para> </listitem>
</varlistentry>
2019-10-08 18:58:44 +03:00
<varlistentry >
<term > <option > -D</option> <replaceable > DIR</replaceable> </term>
<term > <option > --directory=</option> <replaceable > DIR</replaceable> </term>
<listitem > <para > Use the journal files in the specified <option > DIR</option> .
</para> </listitem>
</varlistentry>
<varlistentry >
<term > <option > -q</option> </term>
<term > <option > --quiet</option> </term>
<listitem > <para > Suppresses informational messages about lack
of access to journal files and possible in-flight coredumps.
</para> </listitem>
</varlistentry>
2021-10-06 15:47:46 +03:00
<varlistentry >
<term > <option > --all</option> </term>
<listitem > <para > Look at all available journal files in <filename > /var/log/journal/</filename>
(excluding journal namespaces) instead of only local ones.</para> </listitem>
</varlistentry>
2019-10-08 18:58:44 +03:00
</variablelist>
</refsect1>
2015-02-04 05:14:13 +03:00
<refsect1 >
<title > Matching</title>
<para > A match can be:</para>
<variablelist >
<varlistentry >
<term > <replaceable > PID</replaceable> </term>
<listitem > <para > Process ID of the
process that dumped
core. An integer.</para> </listitem>
</varlistentry>
<varlistentry >
<term > <replaceable > COMM</replaceable> </term>
<listitem > <para > Name of the executable (matches
<option > COREDUMP_COMM=</option> ). Must not contain slashes.
</para> </listitem>
</varlistentry>
<varlistentry >
<term > <replaceable > EXE</replaceable> </term>
<listitem > <para > Path to the executable (matches
<option > COREDUMP_EXE=</option> ). Must contain at least one
slash. </para> </listitem>
</varlistentry>
<varlistentry >
<term > <replaceable > MATCH</replaceable> </term>
2018-06-19 09:35:43 +03:00
<listitem > <para > General journalctl match filter, must contain an equals
sign (<literal > =</literal> ). See
<citerefentry > <refentrytitle > journalctl</refentrytitle> <manvolnum > 1</manvolnum> </citerefentry> .
</para> </listitem>
2015-02-04 05:14:13 +03:00
</varlistentry>
</variablelist>
</refsect1>
<refsect1 >
<title > Exit status</title>
<para > On success, 0 is returned; otherwise, a non-zero failure
2016-05-16 12:56:04 +03:00
code is returned. Not finding any matching core dumps is treated as
2015-02-04 05:14:13 +03:00
failure.
</para>
</refsect1>
2018-04-20 12:28:04 +03:00
<refsect1 >
<title > Environment</title>
<variablelist class= 'environment-variables' >
<varlistentry >
<term > <varname > $SYSTEMD_DEBUGGER</varname> </term>
<listitem > <para > Use the given debugger for the <command > debug</command>
command. See the <option > --debugger=</option> option.</para> </listitem>
</varlistentry>
</variablelist>
</refsect1>
2015-02-04 05:14:13 +03:00
<refsect1 >
<title > Examples</title>
<example >
2021-02-27 21:00:51 +03:00
<title > List all the core dumps of a program</title>
2015-02-04 05:14:13 +03:00
2021-02-27 21:00:51 +03:00
<programlisting > $ coredumpctl list /usr/lib64/firefox/firefox
TIME PID UID GID SIG COREFILE EXE SIZE
Tue … 8018 1000 1000 SIGSEGV missing /usr/lib64/firefox/firefox n/a
Wed … 251609 1000 1000 SIGTRAP missing /usr/lib64/firefox/firefox n/a
Fri … 552351 1000 1000 SIGSEGV present /usr/lib64/firefox/firefox 28.7M
</programlisting>
<para > The journal has three entries pertaining to <filename > /usr/lib64/firefox/firefox</filename> , and
only the last entry still has an available core file (in external storage on disk).</para>
<para > Note that <filename > coredumpctl</filename> needs access to the journal files to retrieve the
relevant entries from the journal. Thus, an unprivileged user will normally only see information about
crashing programs of this user.</para>
2015-02-04 05:14:13 +03:00
</example>
<example >
2021-02-27 21:00:51 +03:00
<title > Invoke <command > gdb</command> on the last core dump</title>
2015-02-04 05:14:13 +03:00
2021-02-27 21:00:51 +03:00
<programlisting > $ coredumpctl debug</programlisting>
2020-12-14 17:44:36 +03:00
</example>
<example >
2021-02-27 21:00:51 +03:00
<title > Use <command > gdb</command> to display full register info from the last core dump</title>
2020-12-14 17:44:36 +03:00
2021-02-27 21:00:51 +03:00
<programlisting > $ coredumpctl debug --debugger-arguments="-batch -ex 'info all-registers'"</programlisting>
2015-02-04 05:14:13 +03:00
</example>
<example >
2021-03-03 17:30:04 +03:00
<title > Show information about a core dump matched by PID</title>
<programlisting > $ coredumpctl info 6654
PID: 6654 (bash)
UID: 1000 (user)
GID: 1000 (user)
Signal: 11 (SEGV)
Timestamp: Mon 2021-01-01 00:00:01 CET (20s ago)
2021-04-02 14:52:56 +03:00
Command Line: bash -c $'kill -SEGV $$'
2021-03-03 17:30:04 +03:00
Executable: /usr/bin/bash
Control Group: /user.slice/user-1000.slice/…
Unit: user@1000.service
User Unit: vte-spawn-….scope
Slice: user-1000.slice
Owner UID: 1000 (user)
Boot ID: …
Machine ID: …
Hostname: …
Storage: /var/lib/systemd/coredump/core.bash.1000.….zst (present)
Disk Size: 51.7K
Message: Process 130414 (bash) of user 1000 dumped core.
Stack trace of thread 130414:
#0 0x00007f398142358b kill (libc.so.6 + 0x3d58b)
#1 0x0000558c2c7fda09 kill_builtin (bash + 0xb1a09)
#2 0x0000558c2c79dc59 execute_builtin.lto_priv.0 (bash + 0x51c59)
#3 0x0000558c2c79709c execute_simple_command (bash + 0x4b09c)
#4 0x0000558c2c798408 execute_command_internal (bash + 0x4c408)
#5 0x0000558c2c7f6bdc parse_and_execute (bash + 0xaabdc)
#6 0x0000558c2c85415c run_one_command.isra.0 (bash + 0x10815c)
#7 0x0000558c2c77d040 main (bash + 0x31040)
#8 0x00007f398140db75 __libc_start_main (libc.so.6 + 0x27b75)
#9 0x0000558c2c77dd1e _start (bash + 0x31d1e)
</programlisting>
2015-02-04 05:14:13 +03:00
</example>
<example >
2016-05-16 12:56:04 +03:00
<title > Extract the last core dump of /usr/bin/bar to a file named
2019-11-21 22:22:12 +03:00
<filename index= "false" > bar.coredump</filename> </title>
2015-02-04 05:14:13 +03:00
2021-02-27 21:00:51 +03:00
<programlisting > $ coredumpctl -o bar.coredump dump /usr/bin/bar</programlisting>
2015-02-04 05:14:13 +03:00
</example>
</refsect1>
<refsect1 >
<title > See Also</title>
<para >
<citerefentry > <refentrytitle > systemd-coredump</refentrytitle> <manvolnum > 8</manvolnum> </citerefentry> ,
<citerefentry > <refentrytitle > coredump.conf</refentrytitle> <manvolnum > 5</manvolnum> </citerefentry> ,
<citerefentry > <refentrytitle > systemd-journald.service</refentrytitle> <manvolnum > 8</manvolnum> </citerefentry> ,
<citerefentry project= 'man-pages' > <refentrytitle > gdb</refentrytitle> <manvolnum > 1</manvolnum> </citerefentry>
</para>
</refsect1>
2012-10-19 14:29:46 +04:00
</refentry>