man/coredumpctl.xml

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