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     </variablelist>
 142   </refsect1>
 143
 144   <refsect1>
 145     <title>Commands</title>
 146
 147     <para>The following commands are understood:</para>
 148
 149     <variablelist>
 150       <varlistentry>
 151         <term><command>list</command></term>
 152
 153         <listitem><para>List core dumps captured in the journal
 154         matching specified characteristics. If no command is
 155         specified, this is the implied default.</para>
 156
 157         <para>The output is designed to be human readable and contains list contains
 158         a table with the following columns:</para>
 159         <variablelist>
 160           <varlistentry>
 161             <term>TIME</term>
 162             <listitem><para>The timestamp of the crash, as reported by the kernel.</para>
 163             </listitem>
 164           </varlistentry>
 165
 166           <varlistentry>
 167             <term>PID</term>
 168             <listitem><para>The identifier of the process that crashed.</para>
 169             </listitem>
 170           </varlistentry>
 171
 172           <varlistentry>
 173             <term>UID</term>
 174             <term>GID</term>
 175             <listitem><para>The user and group identifiers of the process that crashed.</para>
 176             </listitem>
 177           </varlistentry>
 178
 179           <varlistentry>
 180             <term>SIGNAL</term>
 181             <listitem><para>The signal that caused the process to crash, when applicable.
 182             </para></listitem>
 183           </varlistentry>
 184
 185           <varlistentry>
 186             <term>COREFILE</term>
 187             <listitem><para>Information whether the coredump was stored, and whether
 188             it is still accessible: <literal>none</literal> means the the core was
 189             not stored, <literal>-</literal> means that it was not available (for
 190             example because the process was not terminated by a signal),
 191             <literal>present</literal> means that the core file is accessible by the
 192             current user, <literal>journal</literal> means that the core was stored
 193             in the <literal>journal</literal>, <literal>truncated</literal> is the
 194             same as one of the previous two, but the core was too large and was not
 195             stored in its entirety, <literal>error</literal> means that the core file
 196             cannot be accessed, most likely because of insufficient permissions, and
 197             <literal>missing</literal> means that the core was stored in a file, but
 198             this file has since been removed.</para></listitem>
 199           </varlistentry>
 200
 201           <varlistentry>
 202             <term>EXE</term>
 203             <listitem><para>The full path to the executable. For backtraces of scripts
 204             this is the name of the interpreter.</para></listitem>
 205           </varlistentry>
 206         </variablelist>
 207
 208         <para>It's worth noting that different restrictions apply to
 209         data saved in the journal and core dump files saved in
 210         <filename>/var/lib/systemd/coredump</filename>, see overview in
 211         <citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 212         Thus it may very well happen that a particular core dump is still listed
 213         in the journal while its corresponding core dump file has already been
 214         removed.</para></listitem>
 215       </varlistentry>
 216
 217       <varlistentry>
 218         <term><command>info</command></term>
 219
 220         <listitem><para>Show detailed information about core dumps
 221         captured in the journal.</para></listitem>
 222       </varlistentry>
 223
 224       <varlistentry>
 225         <term><command>dump</command></term>
 226
 227         <listitem><para>Extract the last core dump matching specified
 228         characteristics. The core dump will be written on standard
 229         output, unless an output file is specified with
 230         <option>--output=</option>. </para></listitem>
 231       </varlistentry>
 232
 233       <varlistentry>
 234         <term><command>gdb</command></term>
 235
 236         <listitem><para>Invoke the GNU debugger on the last core dump
 237         matching specified characteristics. </para></listitem>
 238       </varlistentry>
 239
 240     </variablelist>
 241
 242   </refsect1>
 243
 244   <refsect1>
 245     <title>Matching</title>
 246
 247     <para>A match can be:</para>
 248
 249     <variablelist>
 250       <varlistentry>
 251         <term><replaceable>PID</replaceable></term>
 252
 253         <listitem><para>Process ID of the
 254         process that dumped
 255         core. An integer.</para></listitem>
 256       </varlistentry>
 257
 258       <varlistentry>
 259         <term><replaceable>COMM</replaceable></term>
 260
 261         <listitem><para>Name of the executable (matches
 262         <option>COREDUMP_COMM=</option>). Must not contain slashes.
 263         </para></listitem>
 264       </varlistentry>
 265
 266       <varlistentry>
 267         <term><replaceable>EXE</replaceable></term>
 268
 269         <listitem><para>Path to the executable (matches
 270         <option>COREDUMP_EXE=</option>). Must contain at least one
 271         slash. </para></listitem>
 272       </varlistentry>
 273
 274       <varlistentry>
 275         <term><replaceable>MATCH</replaceable></term>
 276
 277         <listitem><para>General journalctl predicate (see
 278         <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>).
 279         Must contain an equals sign (<literal>=</literal>).</para></listitem>
 280       </varlistentry>
 281     </variablelist>
 282   </refsect1>
 283
 284   <refsect1>
 285     <title>Exit status</title>
 286     <para>On success, 0 is returned; otherwise, a non-zero failure
 287     code is returned. Not finding any matching core dumps is treated as
 288     failure.
 289     </para>
 290   </refsect1>
 291
 292   <refsect1>
 293     <title>Examples</title>
 294
 295     <example>
 296       <title>List all the core dumps of a program named foo</title>
 297
 298       <programlisting># coredumpctl list foo</programlisting>
 299     </example>
 300
 301     <example>
 302       <title>Invoke gdb on the last core dump</title>
 303
 304       <programlisting># coredumpctl gdb</programlisting>
 305     </example>
 306
 307     <example>
 308       <title>Show information about a process that dumped core,
 309       matching by its PID 6654</title>
 310
 311       <programlisting># coredumpctl info 6654</programlisting>
 312     </example>
 313
 314     <example>
 315       <title>Extract the last core dump of /usr/bin/bar to a file named
 316       <filename noindex="true">bar.coredump</filename></title>
 317
 318       <programlisting># coredumpctl -o bar.coredump dump /usr/bin/bar</programlisting>
 319     </example>
 320   </refsect1>
 321
 322   <refsect1>
 323     <title>See Also</title>
 324     <para>
 325       <citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 326       <citerefentry><refentrytitle>coredump.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 327       <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 328       <citerefentry project='man-pages'><refentrytitle>gdb</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 329     </para>
 330   </refsect1>
 331
 332 </refentry>