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