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