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