man/coredumpctl.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   SPDX-License-Identifier: LGPL-2.1+
   7 -->
   8
   9 <refentry id="coredumpctl" conditional='ENABLE_COREDUMP'
  10     xmlns:xi="http://www.w3.org/2001/XInclude">
  11
  12   <refentryinfo>
  13     <title>coredumpctl</title>
  14     <productname>systemd</productname>
  15   </refentryinfo>
  16
  17   <refmeta>
  18     <refentrytitle>coredumpctl</refentrytitle>
  19     <manvolnum>1</manvolnum>
  20   </refmeta>
  21
  22   <refnamediv>
  23     <refname>coredumpctl</refname>
  24     <refpurpose>Retrieve and process saved core dumps and metadata</refpurpose>
  25   </refnamediv>
  26
  27   <refsynopsisdiv>
  28     <cmdsynopsis>
  29       <command>coredumpctl</command>
  30       <arg choice="opt" rep="repeat">OPTIONS</arg>
  31       <arg choice="req">COMMAND</arg>
  32       <arg choice="opt" rep="repeat">PID|COMM|EXE|MATCH</arg>
  33     </cmdsynopsis>
  34   </refsynopsisdiv>
  35
  36   <refsect1>
  37     <title>Description</title>
  38
  39     <para><command>coredumpctl</command> is a tool that can be used to retrieve and process core
  40     dumps and metadata which were saved by
  41     <citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
  42     </para>
  43   </refsect1>
  44
  45   <refsect1>
  46     <title>Options</title>
  47
  48     <para>The following options are understood:</para>
  49
  50     <variablelist>
  51
  52       <xi:include href="standard-options.xml" xpointer="help" />
  53       <xi:include href="standard-options.xml" xpointer="version" />
  54
  55       <varlistentry>
  56         <term><option>--no-legend</option></term>
  57
  58         <listitem><para>Do not print column headers.</para></listitem>
  59       </varlistentry>
  60
  61       <xi:include href="standard-options.xml" xpointer="no-pager" />
  62
  63       <varlistentry>
  64         <term><option>-1</option></term>
  65
  66         <listitem><para>Show information of a single core dump only, instead of listing
  67         all known core dumps.</para></listitem>
  68       </varlistentry>
  69
  70       <varlistentry>
  71         <term><option>-S</option></term>
  72         <term><option>--since</option></term>
  73
  74         <listitem><para>Only print entries which are since the specified date.</para></listitem>
  75       </varlistentry>
  76
  77       <varlistentry>
  78         <term><option>-U</option></term>
  79         <term><option>--until</option></term>
  80
  81         <listitem><para>Only print entries which are until the specified date.</para></listitem>
  82       </varlistentry>
  83
  84       <varlistentry>
  85         <term><option>-r</option></term>
  86         <term><option>--reverse</option></term>
  87
  88         <listitem><para>Reverse output so that the newest entries are displayed first.
  89         </para></listitem>
  90       </varlistentry>
  91
  92       <varlistentry>
  93         <term><option>-F</option> <replaceable>FIELD</replaceable></term>
  94         <term><option>--field=</option><replaceable>FIELD</replaceable></term>
  95
  96         <listitem><para>Print all possible data values the specified
  97         field takes in matching core dump entries of the
  98         journal.</para></listitem>
  99       </varlistentry>
 100
 101       <varlistentry>
 102         <term><option>-o</option> <replaceable>FILE</replaceable></term>
 103         <term><option>--output=</option><replaceable>FILE</replaceable></term>
 104
 105         <listitem><para>Write the core to <option>FILE</option>.
 106         </para></listitem>
 107       </varlistentry>
 108
 109       <varlistentry>
 110         <term><option>--debugger=</option><replaceable>DEBUGGER</replaceable></term>
 111
 112         <listitem><para>Use the given debugger for the <command>debug</command>
 113         command. If not given and <varname>$SYSTEMD_DEBUGGER</varname> is unset, then
 114         <citerefentry><refentrytitle>gdb</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 115         will be used. </para></listitem>
 116       </varlistentry>
 117
 118       <varlistentry>
 119         <term><option>-D</option> <replaceable>DIR</replaceable></term>
 120         <term><option>--directory=</option><replaceable>DIR</replaceable></term>
 121
 122         <listitem><para>Use the journal files in the specified <option>DIR</option>.
 123         </para></listitem>
 124       </varlistentry>
 125
 126       <varlistentry>
 127         <term><option>-q</option></term>
 128         <term><option>--quiet</option></term>
 129
 130         <listitem><para>Suppresses informational messages about lack
 131         of access to journal files and possible in-flight coredumps.
 132         </para></listitem>
 133       </varlistentry>
 134     </variablelist>
 135   </refsect1>
 136
 137   <refsect1>
 138     <title>Commands</title>
 139
 140     <para>The following commands are understood:</para>
 141
 142     <variablelist>
 143       <varlistentry>
 144         <term><command>list</command></term>
 145
 146         <listitem><para>List core dumps captured in the journal
 147         matching specified characteristics. If no command is
 148         specified, this is the implied default.</para>
 149
 150         <para>The output is designed to be human readable and contains list contains
 151         a table with the following columns:</para>
 152         <variablelist>
 153           <varlistentry>
 154             <term>TIME</term>
 155             <listitem><para>The timestamp of the crash, as reported by the kernel.</para>
 156             </listitem>
 157           </varlistentry>
 158
 159           <varlistentry>
 160             <term>PID</term>
 161             <listitem><para>The identifier of the process that crashed.</para>
 162             </listitem>
 163           </varlistentry>
 164
 165           <varlistentry>
 166             <term>UID</term>
 167             <term>GID</term>
 168             <listitem><para>The user and group identifiers of the process that crashed.</para>
 169             </listitem>
 170           </varlistentry>
 171
 172           <varlistentry>
 173             <term>SIGNAL</term>
 174             <listitem><para>The signal that caused the process to crash, when applicable.
 175             </para></listitem>
 176           </varlistentry>
 177
 178           <varlistentry>
 179             <term>COREFILE</term>
 180             <listitem><para>Information whether the coredump was stored, and whether
 181             it is still accessible: <literal>none</literal> means the core was
 182             not stored, <literal>-</literal> means that it was not available (for
 183             example because the process was not terminated by a signal),
 184             <literal>present</literal> means that the core file is accessible by the
 185             current user, <literal>journal</literal> means that the core was stored
 186             in the <literal>journal</literal>, <literal>truncated</literal> is the
 187             same as one of the previous two, but the core was too large and was not
 188             stored in its entirety, <literal>error</literal> means that the core file
 189             cannot be accessed, most likely because of insufficient permissions, and
 190             <literal>missing</literal> means that the core was stored in a file, but
 191             this file has since been removed.</para></listitem>
 192           </varlistentry>
 193
 194           <varlistentry>
 195             <term>EXE</term>
 196             <listitem><para>The full path to the executable. For backtraces of scripts
 197             this is the name of the interpreter.</para></listitem>
 198           </varlistentry>
 199         </variablelist>
 200
 201         <para>It's worth noting that different restrictions apply to
 202         data saved in the journal and core dump files saved in
 203         <filename>/var/lib/systemd/coredump</filename>, see overview in
 204         <citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 205         Thus it may very well happen that a particular core dump is still listed
 206         in the journal while its corresponding core dump file has already been
 207         removed.</para></listitem>
 208       </varlistentry>
 209
 210       <varlistentry>
 211         <term><command>info</command></term>
 212
 213         <listitem><para>Show detailed information about core dumps
 214         captured in the journal.</para></listitem>
 215       </varlistentry>
 216
 217       <varlistentry>
 218         <term><command>dump</command></term>
 219
 220         <listitem><para>Extract the last core dump matching specified
 221         characteristics. The core dump will be written on standard
 222         output, unless an output file is specified with
 223         <option>--output=</option>. </para></listitem>
 224       </varlistentry>
 225
 226       <varlistentry>
 227         <term><command>debug</command></term>
 228
 229         <listitem><para>Invoke a debugger on the last core dump
 230         matching specified characteristics. By default,
 231         <citerefentry><refentrytitle>gdb</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 232         will be used. This may be changed using the <option>--debugger=</option>
 233         option or the <varname>$SYSTEMD_DEBUGGER</varname> environment
 234         variable.</para></listitem>
 235       </varlistentry>
 236
 237     </variablelist>
 238
 239   </refsect1>
 240
 241   <refsect1>
 242     <title>Matching</title>
 243
 244     <para>A match can be:</para>
 245
 246     <variablelist>
 247       <varlistentry>
 248         <term><replaceable>PID</replaceable></term>
 249
 250         <listitem><para>Process ID of the
 251         process that dumped
 252         core. An integer.</para></listitem>
 253       </varlistentry>
 254
 255       <varlistentry>
 256         <term><replaceable>COMM</replaceable></term>
 257
 258         <listitem><para>Name of the executable (matches
 259         <option>COREDUMP_COMM=</option>). Must not contain slashes.
 260         </para></listitem>
 261       </varlistentry>
 262
 263       <varlistentry>
 264         <term><replaceable>EXE</replaceable></term>
 265
 266         <listitem><para>Path to the executable (matches
 267         <option>COREDUMP_EXE=</option>). Must contain at least one
 268         slash. </para></listitem>
 269       </varlistentry>
 270
 271       <varlistentry>
 272         <term><replaceable>MATCH</replaceable></term>
 273
 274         <listitem><para>General journalctl predicate (see
 275         <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>).
 276         Must contain an equals sign (<literal>=</literal>).</para></listitem>
 277       </varlistentry>
 278     </variablelist>
 279   </refsect1>
 280
 281   <refsect1>
 282     <title>Exit status</title>
 283     <para>On success, 0 is returned; otherwise, a non-zero failure
 284     code is returned. Not finding any matching core dumps is treated as
 285     failure.
 286     </para>
 287   </refsect1>
 288
 289   <refsect1>
 290     <title>Environment</title>
 291
 292     <variablelist class='environment-variables'>
 293       <varlistentry>
 294         <term><varname>$SYSTEMD_DEBUGGER</varname></term>
 295         <listitem><para>Use the given debugger for the <command>debug</command>
 296         command. See the <option>--debugger=</option> option.</para></listitem>
 297       </varlistentry>
 298     </variablelist>
 299   </refsect1>
 300
 301   <refsect1>
 302     <title>Examples</title>
 303
 304     <example>
 305       <title>List all the core dumps of a program named foo</title>
 306
 307       <programlisting># coredumpctl list foo</programlisting>
 308     </example>
 309
 310     <example>
 311       <title>Invoke gdb on the last core dump</title>
 312
 313       <programlisting># coredumpctl debug</programlisting>
 314     </example>
 315
 316     <example>
 317       <title>Show information about a process that dumped core,
 318       matching by its PID 6654</title>
 319
 320       <programlisting># coredumpctl info 6654</programlisting>
 321     </example>
 322
 323     <example>
 324       <title>Extract the last core dump of /usr/bin/bar to a file named
 325       <filename noindex="true">bar.coredump</filename></title>
 326
 327       <programlisting># coredumpctl -o bar.coredump dump /usr/bin/bar</programlisting>
 328     </example>
 329   </refsect1>
 330
 331   <refsect1>
 332     <title>See Also</title>
 333     <para>
 334       <citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 335       <citerefentry><refentrytitle>coredump.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 336       <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 337       <citerefentry project='man-pages'><refentrytitle>gdb</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 338     </para>
 339   </refsect1>
 340
 341 </refentry>