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 <!ENTITY % entities SYSTEM "custom-entities.ent" >
   5 %entities;
   6 ]>
   7
   8 <!--
   9   This file is part of systemd.
  10
  11   Copyright 2012 Zbigniew Jędrzejewski-Szmek
  12
  13   systemd is free software; you can redistribute it and/or modify it
  14   under the terms of the GNU Lesser General Public License as published by
  15   the Free Software Foundation; either version 2.1 of the License, or
  16   (at your option) any later version.
  17
  18   systemd is distributed in the hope that it will be useful, but
  19   WITHOUT ANY WARRANTY; without even the implied warranty of
  20   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  21   Lesser General Public License for more details.
  22
  23   You should have received a copy of the GNU Lesser General Public License
  24   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  25 -->
  26
  27 <refentry id="coredumpctl" conditional='ENABLE_COREDUMP'
  28     xmlns:xi="http://www.w3.org/2001/XInclude">
  29
  30   <refentryinfo>
  31     <title>coredumpctl</title>
  32     <productname>systemd</productname>
  33
  34     <authorgroup>
  35       <author>
  36         <contrib>Developer</contrib>
  37         <firstname>Zbigniew</firstname>
  38         <surname>Jędrzejewski-Szmek</surname>
  39         <email>zbyszek@in.waw.pl</email>
  40       </author>
  41     </authorgroup>
  42   </refentryinfo>
  43
  44   <refmeta>
  45     <refentrytitle>coredumpctl</refentrytitle>
  46     <manvolnum>1</manvolnum>
  47   </refmeta>
  48
  49   <refnamediv>
  50     <refname>coredumpctl</refname>
  51     <refpurpose>Retrieve coredumps from the journal</refpurpose>
  52   </refnamediv>
  53
  54   <refsynopsisdiv>
  55     <cmdsynopsis>
  56       <command>coredumpctl</command>
  57       <arg choice="opt" rep="repeat">OPTIONS</arg>
  58       <arg choice="req">COMMAND</arg>
  59       <arg choice="opt" rep="repeat">PID|COMM|EXE|MATCH</arg>
  60     </cmdsynopsis>
  61   </refsynopsisdiv>
  62
  63   <refsect1>
  64     <title>Description</title>
  65
  66     <para><command>coredumpctl</command> may be used to
  67     retrieve coredumps from
  68     <citerefentry><refentrytitle>systemd-journald</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
  69   </refsect1>
  70
  71   <refsect1>
  72     <title>Options</title>
  73
  74     <para>The following options are understood:</para>
  75
  76     <variablelist>
  77       <varlistentry>
  78         <term><option>--no-legend</option></term>
  79
  80         <listitem><para>Do not print column headers.
  81         </para></listitem>
  82       </varlistentry>
  83
  84       <varlistentry>
  85         <term><option>-1</option></term>
  86
  87         <listitem><para>Show information of a single coredump only,
  88         instead of listing all known coredumps. </para></listitem>
  89       </varlistentry>
  90
  91       <varlistentry>
  92         <term><option>-F</option></term>
  93         <term><option>--field=</option></term>
  94
  95         <listitem><para>Print all possible data values the specified
  96         field takes in matching coredump entries of the
  97         journal.</para></listitem>
  98       </varlistentry>
  99
 100       <varlistentry>
 101         <term><option>-o</option></term>
 102         <term><option>--output=FILE</option></term>
 103
 104         <listitem><para>Write the core to <option>FILE</option>.
 105         </para></listitem>
 106       </varlistentry>
 107
 108       <xi:include href="standard-options.xml" xpointer="help" />
 109       <xi:include href="standard-options.xml" xpointer="version" />
 110       <xi:include href="standard-options.xml" xpointer="no-pager" />
 111
 112     </variablelist>
 113
 114     <para>The following commands are understood:</para>
 115
 116     <variablelist>
 117       <varlistentry>
 118         <term><command>list</command></term>
 119
 120         <listitem><para>List coredumps captured in the journal
 121         matching specified characteristics. If no command is
 122         specified, this is the implied default.</para></listitem>
 123       </varlistentry>
 124
 125       <varlistentry>
 126         <term><command>info</command></term>
 127
 128         <listitem><para>Show detailed information about coredumps
 129         captured in the journal.</para></listitem>
 130       </varlistentry>
 131
 132       <varlistentry>
 133         <term><command>dump</command></term>
 134
 135         <listitem><para>Extract the last coredump matching specified
 136         characteristics. The coredump will be written on standard
 137         output, unless an output file is specified with
 138         <option>-o/--output</option>. </para></listitem>
 139       </varlistentry>
 140
 141       <varlistentry>
 142         <term><command>gdb</command></term>
 143
 144         <listitem><para>Invoke the GNU debugger on the last coredump
 145         matching specified characteristics. </para></listitem>
 146       </varlistentry>
 147
 148     </variablelist>
 149
 150   </refsect1>
 151
 152   <refsect1>
 153     <title>Matching</title>
 154
 155     <para>A match can be:</para>
 156
 157     <variablelist>
 158       <varlistentry>
 159         <term><replaceable>PID</replaceable></term>
 160
 161         <listitem><para>Process ID of the
 162         process that dumped
 163         core. An integer.</para></listitem>
 164       </varlistentry>
 165
 166       <varlistentry>
 167         <term><replaceable>COMM</replaceable></term>
 168
 169         <listitem><para>Name of the executable (matches
 170         <option>COREDUMP_COMM=</option>). Must not contain slashes.
 171         </para></listitem>
 172       </varlistentry>
 173
 174       <varlistentry>
 175         <term><replaceable>EXE</replaceable></term>
 176
 177         <listitem><para>Path to the executable (matches
 178         <option>COREDUMP_EXE=</option>). Must contain at least one
 179         slash. </para></listitem>
 180       </varlistentry>
 181
 182       <varlistentry>
 183         <term><replaceable>MATCH</replaceable></term>
 184
 185         <listitem><para>General journalctl predicates (see
 186         <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>).
 187         Must contain an equal sign. </para></listitem>
 188       </varlistentry>
 189     </variablelist>
 190   </refsect1>
 191
 192   <refsect1>
 193     <title>Exit status</title>
 194     <para>On success, 0 is returned; otherwise, a non-zero failure
 195     code is returned. Not finding any matching coredumps is treated as
 196     failure.
 197     </para>
 198   </refsect1>
 199
 200   <refsect1>
 201     <title>Examples</title>
 202
 203     <example>
 204       <title>List all the coredumps of a program named foo</title>
 205
 206       <programlisting># coredumpctl list foo</programlisting>
 207     </example>
 208
 209     <example>
 210       <title>Invoke gdb on the last coredump</title>
 211
 212       <programlisting># coredumpctl gdb</programlisting>
 213     </example>
 214
 215     <example>
 216       <title>Show information about a process that dumped core,
 217       matching by its PID 6654</title>
 218
 219       <programlisting># coredumpctl info 6654</programlisting>
 220     </example>
 221
 222     <example>
 223       <title>Extract the last coredump of /usr/bin/bar to a file named
 224       <filename noindex="true">bar.coredump</filename></title>
 225
 226       <programlisting># coredumpctl -o bar.coredump dump /usr/bin/bar</programlisting>
 227     </example>
 228   </refsect1>
 229
 230   <refsect1>
 231     <title>See Also</title>
 232     <para>
 233       <citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 234       <citerefentry><refentrytitle>coredump.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 235       <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 236       <citerefentry project='man-pages'><refentrytitle>gdb</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 237     </para>
 238   </refsect1>
 239
 240 </refentry>