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   This file is part of systemd.
   7
   8   Copyright 2012 Zbigniew Jędrzejewski-Szmek
   9
  10   systemd is free software; you can redistribute it and/or modify it
  11   under the terms of the GNU Lesser General Public License as published by
  12   the Free Software Foundation; either version 2.1 of the License, or
  13   (at your option) any later version.
  14
  15   systemd is distributed in the hope that it will be useful, but
  16   WITHOUT ANY WARRANTY; without even the implied warranty of
  17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  18   Lesser General Public License for more details.
  19
  20   You should have received a copy of the GNU Lesser General Public License
  21   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  22 -->
  23
  24 <refentry id="coredumpctl" conditional='ENABLE_COREDUMP'
  25     xmlns:xi="http://www.w3.org/2001/XInclude">
  26
  27   <refentryinfo>
  28     <title>coredumpctl</title>
  29     <productname>systemd</productname>
  30
  31     <authorgroup>
  32       <author>
  33         <contrib>Developer</contrib>
  34         <firstname>Zbigniew</firstname>
  35         <surname>Jędrzejewski-Szmek</surname>
  36         <email>zbyszek@in.waw.pl</email>
  37       </author>
  38     </authorgroup>
  39   </refentryinfo>
  40
  41   <refmeta>
  42     <refentrytitle>coredumpctl</refentrytitle>
  43     <manvolnum>1</manvolnum>
  44   </refmeta>
  45
  46   <refnamediv>
  47     <refname>coredumpctl</refname>
  48     <refpurpose>Retrieve and process saved core dumps and metadata</refpurpose>
  49   </refnamediv>
  50
  51   <refsynopsisdiv>
  52     <cmdsynopsis>
  53       <command>coredumpctl</command>
  54       <arg choice="opt" rep="repeat">OPTIONS</arg>
  55       <arg choice="req">COMMAND</arg>
  56       <arg choice="opt" rep="repeat">PID|COMM|EXE|MATCH</arg>
  57     </cmdsynopsis>
  58   </refsynopsisdiv>
  59
  60   <refsect1>
  61     <title>Description</title>
  62
  63     <para><command>coredumpctl</command> is a tool that can be used to retrieve and process core
  64     dumps and metadata which were saved by
  65     <citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
  66     </para>
  67   </refsect1>
  68
  69   <refsect1>
  70     <title>Options</title>
  71
  72     <para>The following options are understood:</para>
  73
  74     <variablelist>
  75
  76       <xi:include href="standard-options.xml" xpointer="help" />
  77       <xi:include href="standard-options.xml" xpointer="version" />
  78
  79       <varlistentry>
  80         <term><option>--no-legend</option></term>
  81
  82         <listitem><para>Do not print column headers.</para></listitem>
  83       </varlistentry>
  84
  85       <xi:include href="standard-options.xml" xpointer="no-pager" />
  86
  87       <varlistentry>
  88         <term><option>-1</option></term>
  89
  90         <listitem><para>Show information of a single core dump only, instead of listing
  91         all known core dumps.</para></listitem>
  92       </varlistentry>
  93
  94       <varlistentry>
  95         <term><option>-S</option></term>
  96         <term><option>--since</option></term>
  97
  98         <listitem><para>Only print entries which are since the specified date.</para></listitem>
  99       </varlistentry>
 100
 101       <varlistentry>
 102         <term><option>-U</option></term>
 103         <term><option>--until</option></term>
 104
 105         <listitem><para>Only print entries which are until the specified date.</para></listitem>
 106       </varlistentry>
 107
 108       <varlistentry>
 109         <term><option>-r</option></term>
 110         <term><option>--reverse</option></term>
 111
 112         <listitem><para>Reverse output so that the newest entries are displayed first.
 113         </para></listitem>
 114       </varlistentry>
 115
 116       <varlistentry>
 117         <term><option>-F</option> <replaceable>FIELD</replaceable></term>
 118         <term><option>--field=</option><replaceable>FIELD</replaceable></term>
 119
 120         <listitem><para>Print all possible data values the specified
 121         field takes in matching core dump entries of the
 122         journal.</para></listitem>
 123       </varlistentry>
 124
 125       <varlistentry>
 126         <term><option>-o</option> <replaceable>FILE</replaceable></term>
 127         <term><option>--output=</option><replaceable>FILE</replaceable></term>
 128
 129         <listitem><para>Write the core to <option>FILE</option>.
 130         </para></listitem>
 131       </varlistentry>
 132
 133       <varlistentry>
 134         <term><option>-D</option> <replaceable>DIR</replaceable></term>
 135         <term><option>--directory=</option><replaceable>DIR</replaceable></term>
 136
 137         <listitem><para>Use the journal files in the specified <option>DIR</option>.
 138         </para></listitem>
 139       </varlistentry>
 140
 141       <varlistentry>
 142         <term><option>-q</option></term>
 143         <term><option>--quiet</option></term>
 144
 145         <listitem><para>Suppresses info messages about lack
 146         of access to journal files and possible in-flight coredumps.
 147         </para></listitem>
 148       </varlistentry>
 149     </variablelist>
 150   </refsect1>
 151
 152   <refsect1>
 153     <title>Commands</title>
 154
 155     <para>The following commands are understood:</para>
 156
 157     <variablelist>
 158       <varlistentry>
 159         <term><command>list</command></term>
 160
 161         <listitem><para>List core dumps captured in the journal
 162         matching specified characteristics. If no command is
 163         specified, this is the implied default.</para>
 164
 165         <para>The output is designed to be human readable and contains list contains
 166         a table with the following columns:</para>
 167         <variablelist>
 168           <varlistentry>
 169             <term>TIME</term>
 170             <listitem><para>The timestamp of the crash, as reported by the kernel.</para>
 171             </listitem>
 172           </varlistentry>
 173
 174           <varlistentry>
 175             <term>PID</term>
 176             <listitem><para>The identifier of the process that crashed.</para>
 177             </listitem>
 178           </varlistentry>
 179
 180           <varlistentry>
 181             <term>UID</term>
 182             <term>GID</term>
 183             <listitem><para>The user and group identifiers of the process that crashed.</para>
 184             </listitem>
 185           </varlistentry>
 186
 187           <varlistentry>
 188             <term>SIGNAL</term>
 189             <listitem><para>The signal that caused the process to crash, when applicable.
 190             </para></listitem>
 191           </varlistentry>
 192
 193           <varlistentry>
 194             <term>COREFILE</term>
 195             <listitem><para>Information whether the coredump was stored, and whether
 196             it is still accessible: <literal>none</literal> means the core was
 197             not stored, <literal>-</literal> means that it was not available (for
 198             example because the process was not terminated by a signal),
 199             <literal>present</literal> means that the core file is accessible by the
 200             current user, <literal>journal</literal> means that the core was stored
 201             in the <literal>journal</literal>, <literal>truncated</literal> is the
 202             same as one of the previous two, but the core was too large and was not
 203             stored in its entirety, <literal>error</literal> means that the core file
 204             cannot be accessed, most likely because of insufficient permissions, and
 205             <literal>missing</literal> means that the core was stored in a file, but
 206             this file has since been removed.</para></listitem>
 207           </varlistentry>
 208
 209           <varlistentry>
 210             <term>EXE</term>
 211             <listitem><para>The full path to the executable. For backtraces of scripts
 212             this is the name of the interpreter.</para></listitem>
 213           </varlistentry>
 214         </variablelist>
 215
 216         <para>It's worth noting that different restrictions apply to
 217         data saved in the journal and core dump files saved in
 218         <filename>/var/lib/systemd/coredump</filename>, see overview in
 219         <citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 220         Thus it may very well happen that a particular core dump is still listed
 221         in the journal while its corresponding core dump file has already been
 222         removed.</para></listitem>
 223       </varlistentry>
 224
 225       <varlistentry>
 226         <term><command>info</command></term>
 227
 228         <listitem><para>Show detailed information about core dumps
 229         captured in the journal.</para></listitem>
 230       </varlistentry>
 231
 232       <varlistentry>
 233         <term><command>dump</command></term>
 234
 235         <listitem><para>Extract the last core dump matching specified
 236         characteristics. The core dump will be written on standard
 237         output, unless an output file is specified with
 238         <option>--output=</option>. </para></listitem>
 239       </varlistentry>
 240
 241       <varlistentry>
 242         <term><command>gdb</command></term>
 243
 244         <listitem><para>Invoke the GNU debugger on the last core dump
 245         matching specified characteristics. </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>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 gdb</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>