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