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>It's worth noting that different restrictions apply to
 158         data saved in the journal and core dump files saved in
 159         <filename>/var/lib/systemd/coredump</filename>, see overview in
 160         <citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 161         Thus it may very well happen that a particular core dump is still listed
 162         in the journal while its corresponding core dump file has already been
 163         removed.</para></listitem>
 164       </varlistentry>
 165
 166       <varlistentry>
 167         <term><command>info</command></term>
 168
 169         <listitem><para>Show detailed information about core dumps
 170         captured in the journal.</para></listitem>
 171       </varlistentry>
 172
 173       <varlistentry>
 174         <term><command>dump</command></term>
 175
 176         <listitem><para>Extract the last core dump matching specified
 177         characteristics. The core dump will be written on standard
 178         output, unless an output file is specified with
 179         <option>--output=</option>. </para></listitem>
 180       </varlistentry>
 181
 182       <varlistentry>
 183         <term><command>gdb</command></term>
 184
 185         <listitem><para>Invoke the GNU debugger on the last core dump
 186         matching specified characteristics. </para></listitem>
 187       </varlistentry>
 188
 189     </variablelist>
 190
 191   </refsect1>
 192
 193   <refsect1>
 194     <title>Matching</title>
 195
 196     <para>A match can be:</para>
 197
 198     <variablelist>
 199       <varlistentry>
 200         <term><replaceable>PID</replaceable></term>
 201
 202         <listitem><para>Process ID of the
 203         process that dumped
 204         core. An integer.</para></listitem>
 205       </varlistentry>
 206
 207       <varlistentry>
 208         <term><replaceable>COMM</replaceable></term>
 209
 210         <listitem><para>Name of the executable (matches
 211         <option>COREDUMP_COMM=</option>). Must not contain slashes.
 212         </para></listitem>
 213       </varlistentry>
 214
 215       <varlistentry>
 216         <term><replaceable>EXE</replaceable></term>
 217
 218         <listitem><para>Path to the executable (matches
 219         <option>COREDUMP_EXE=</option>). Must contain at least one
 220         slash. </para></listitem>
 221       </varlistentry>
 222
 223       <varlistentry>
 224         <term><replaceable>MATCH</replaceable></term>
 225
 226         <listitem><para>General journalctl predicates (see
 227         <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>).
 228         Must contain an equal sign. </para></listitem>
 229       </varlistentry>
 230     </variablelist>
 231   </refsect1>
 232
 233   <refsect1>
 234     <title>Exit status</title>
 235     <para>On success, 0 is returned; otherwise, a non-zero failure
 236     code is returned. Not finding any matching core dumps is treated as
 237     failure.
 238     </para>
 239   </refsect1>
 240
 241   <refsect1>
 242     <title>Examples</title>
 243
 244     <example>
 245       <title>List all the core dumps of a program named foo</title>
 246
 247       <programlisting># coredumpctl list foo</programlisting>
 248     </example>
 249
 250     <example>
 251       <title>Invoke gdb on the last core dump</title>
 252
 253       <programlisting># coredumpctl gdb</programlisting>
 254     </example>
 255
 256     <example>
 257       <title>Show information about a process that dumped core,
 258       matching by its PID 6654</title>
 259
 260       <programlisting># coredumpctl info 6654</programlisting>
 261     </example>
 262
 263     <example>
 264       <title>Extract the last core dump of /usr/bin/bar to a file named
 265       <filename noindex="true">bar.coredump</filename></title>
 266
 267       <programlisting># coredumpctl -o bar.coredump dump /usr/bin/bar</programlisting>
 268     </example>
 269   </refsect1>
 270
 271   <refsect1>
 272     <title>See Also</title>
 273     <para>
 274       <citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 275       <citerefentry><refentrytitle>coredump.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 276       <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 277       <citerefentry project='man-pages'><refentrytitle>gdb</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 278     </para>
 279   </refsect1>
 280
 281 </refentry>