[thirdparty/systemd.git] / man / coredumpctl.xml

<?xml version='1.0'?> <!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<!--
  This file is part of systemd.

  Copyright 2012 Zbigniew Jędrzejewski-Szmek

  systemd is free software; you can redistribute it and/or modify it
  under the terms of the GNU Lesser General Public License as published by
  the Free Software Foundation; either version 2.1 of the License, or
  (at your option) any later version.

  systemd is distributed in the hope that it will be useful, but
  WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  Lesser General Public License for more details.

  You should have received a copy of the GNU Lesser General Public License
  along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->

<refentry id="coredumpctl" conditional='ENABLE_COREDUMP'
          xmlns:xi="http://www.w3.org/2001/XInclude">

        <refentryinfo>
                <title>coredumpctl</title>
                <productname>systemd</productname>

                <authorgroup>
                        <author>
                                <contrib>Developer</contrib>
                                <firstname>Zbigniew</firstname>
                                <surname>Jędrzejewski-Szmek</surname>
                                <email>zbyszek@in.waw.pl</email>
                        </author>
                </authorgroup>
        </refentryinfo>

        <refmeta>
                <refentrytitle>coredumpctl</refentrytitle>
                <manvolnum>1</manvolnum>
        </refmeta>

        <refnamediv>
                <refname>coredumpctl</refname>
                <refpurpose>Retrieve coredumps from the journal</refpurpose>
        </refnamediv>

        <refsynopsisdiv>
                <cmdsynopsis>
                        <command>coredumpctl</command>
                        <arg choice="opt" rep="repeat">OPTIONS</arg>
                        <arg choice="req">COMMAND</arg>
                        <arg choice="opt" rep="repeat">PID|COMM|EXE|MATCH</arg>
                </cmdsynopsis>
        </refsynopsisdiv>

        <refsect1>
                <title>Description</title>

                <para><command>coredumpctl</command> may be used to
                retrieve coredumps from
                <citerefentry><refentrytitle>systemd-journald</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
        </refsect1>

        <refsect1>
                <title>Options</title>

                <para>The following options are understood:</para>

                <variablelist>
                        <varlistentry>
                                <term><option>--no-legend</option></term>

                                <listitem><para>Do not print the column headers.
                                </para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>-1</option></term>

                                <listitem><para>Show information of a
                                single coredump only, instead of
                                listing all known coredumps.
                                </para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>-F</option></term>
                                <term><option>--field=</option></term>

                                <listitem><para>Print all possible
                                data values the specified field
                                takes in matching coredump entries of the
                                journal.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>-o</option></term>
                                <term><option>--output=FILE</option></term>

                                <listitem><para>Write the core to
                                <option>FILE</option>.</para></listitem>
                        </varlistentry>

                        <xi:include href="standard-options.xml" xpointer="help" />
                        <xi:include href="standard-options.xml" xpointer="version" />
                        <xi:include href="standard-options.xml" xpointer="no-pager" />

                </variablelist>

                <para>The following commands are understood:</para>

                <variablelist>
                        <varlistentry>
                                <term><command>list</command></term>

                                <listitem><para>List coredumps
                                captured in the journal matching
                                specified characteristics. If no
                                command is specified, this is the
                                implied default.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><command>info</command></term>

                                <listitem><para>Show detailed
                                information about coredumps captured
                                in the journal.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><command>dump</command></term>

                                <listitem><para>Extract the last coredump
                                matching specified characteristics.
                                The coredump will be written on standard output,
                                unless an output file is specified with
                                <option>-o/--output</option>.
                                </para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><command>gdb</command></term>

                                <listitem><para>Invoke the GNU
                                debugger on the last coredump matching
                                specified characteristics.
                                </para></listitem>
                        </varlistentry>

                </variablelist>

        </refsect1>

        <refsect1>
                <title>Matching</title>

                <para>A match can be:</para>

                <variablelist>
                        <varlistentry>
                                <term><replaceable>PID</replaceable></term>

                                <listitem><para>Process ID of the
                                process that dumped
                                core. An integer.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><replaceable>COMM</replaceable></term>

                                <listitem><para>Name of the executable
                                (matches <option>COREDUMP_COMM=</option>).
                                Must not contain slashes.
                                </para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><replaceable>EXE</replaceable></term>

                                <listitem><para>Path to the executable
                                (matches <option>COREDUMP_EXE=</option>).
                                Must contain at least one slash.
                                </para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><replaceable>MATCH</replaceable></term>

                                <listitem><para>General journalctl predicates
                                (see <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>).
                                Must contain an equal sign.
                                </para></listitem>
                        </varlistentry>
                </variablelist>
        </refsect1>

        <refsect1>
                <title>Exit status</title>
                <para>On success, 0 is returned; otherwise, a non-zero failure
                code is returned. Not finding any matching coredumps is treated
                as failure.
                </para>
        </refsect1>

        <refsect1>
                <title>Examples</title>

                <example>
                        <title>List all the coredumps of a program named foo</title>

                        <programlisting># coredumpctl list foo</programlisting>
                </example>

                <example>
                        <title>Invoke gdb on the last coredump</title>

                        <programlisting># coredumpctl gdb</programlisting>
                </example>

                <example>
                        <title>Show information about a process that dumped core, matching by its PID 6654</title>

                        <programlisting># coredumpctl info 6654</programlisting>
                </example>

                <example>
                        <title>Extract the last coredump of /usr/bin/bar to a file named bar.coredump</title>

                        <programlisting># coredumpctl -o bar.coredump dump /usr/bin/bar</programlisting>
                </example>
        </refsect1>

        <refsect1>
                <title>See Also</title>
                <para>
                        <citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
                        <citerefentry><refentrytitle>coredump.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                        <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
                        <citerefentry project='man-pages'><refentrytitle>gdb</refentrytitle><manvolnum>1</manvolnum></citerefentry>
                </para>
        </refsect1>

</refentry>
Commit	Line	Data
5de0409e ZJS	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
f4bab169	24	<refentry id="coredumpctl" conditional='ENABLE_COREDUMP'
dfdebb1b	25	xmlns:xi="http://www.w3.org/2001/XInclude">
5de0409e ZJS	26
5de0409e ZJS	27	<refentryinfo>
f4bab169	28	<title>coredumpctl</title>
5de0409e ZJS	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>
f4bab169	42	<refentrytitle>coredumpctl</refentrytitle>
5de0409e ZJS	43	<manvolnum>1</manvolnum>
	44	</refmeta>
	45
	46	<refnamediv>
f4bab169	47	<refname>coredumpctl</refname>
5de0409e ZJS	48	<refpurpose>Retrieve coredumps from the journal</refpurpose>
	49	</refnamediv>
	50
	51	<refsynopsisdiv>
	52	<cmdsynopsis>
f4bab169	53	<command>coredumpctl</command>
7e15bd33 ZJS	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>
5de0409e ZJS	57	</cmdsynopsis>
	58	</refsynopsisdiv>
	59
	60	<refsect1>
	61	<title>Description</title>
	62
f4bab169	63	<para><command>coredumpctl</command> may be used to
5de0409e ZJS	64	retrieve coredumps from
	65	<citerefentry><refentrytitle>systemd-journald</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
	66	</refsect1>
	67
	68	<refsect1>
	69	<title>Options</title>
	70
	71	<para>The following options are understood:</para>
	72
	73	<variablelist>
eca8701a LP	74	<varlistentry>
	75	<term><option>--no-legend</option></term>
	76
	77	<listitem><para>Do not print the column headers.
	78	</para></listitem>
	79	</varlistentry>
	80
	81	<varlistentry>
	82	<term><option>-1</option></term>
	83
	84	<listitem><para>Show information of a
	85	single coredump only, instead of
	86	listing all known coredumps.
	87	</para></listitem>
	88	</varlistentry>
	89
4f76ae1b	90	<varlistentry>
4f76ae1b	91	<term><option>-F</option></term>
a7f5bb1e	92	<term><option>--field=</option></term>
4f76ae1b ZJS	93
	94	<listitem><para>Print all possible
	95	data values the specified field
	96	takes in matching coredump entries of the
	97	journal.</para></listitem>
	98	</varlistentry>
	99
5de0409e	100	<varlistentry>
a7f5bb1e	101	<term><option>-o</option></term>
5de0409e	102	<term><option>--output=FILE</option></term>
5de0409e ZJS	103
	104	<listitem><para>Write the core to
	105	<option>FILE</option>.</para></listitem>
	106	</varlistentry>
	107
dfdebb1b ZJS	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" />
eca8701a	111
5de0409e ZJS	112	</variablelist>
	113
	114	<para>The following commands are understood:</para>
	115
	116	<variablelist>
	117	<varlistentry>
	118	<term><command>list</command></term>
	119
eca8701a LP	120	<listitem><para>List coredumps
	121	captured in the journal matching
	122	specified characteristics. If no
8d0e0ddd	123	command is specified, this is the
eca8701a LP	124	implied default.</para></listitem>
	125	</varlistentry>
	126
	127	<varlistentry>
	128	<term><command>info</command></term>
	129
	130	<listitem><para>Show detailed
	131	information about coredumps captured
	132	in the journal.</para></listitem>
5de0409e ZJS	133	</varlistentry>
	134
	135	<varlistentry>
	136	<term><command>dump</command></term>
	137
	138	<listitem><para>Extract the last coredump
	139	matching specified characteristics.
66f756d4	140	The coredump will be written on standard output,
6db27428	141	unless an output file is specified with
5de0409e ZJS	142	<option>-o/--output</option>.
	143	</para></listitem>
	144	</varlistentry>
	145
ada45c78 LP	146	<varlistentry>
	147	<term><command>gdb</command></term>
	148
	149	<listitem><para>Invoke the GNU
	150	debugger on the last coredump matching
	151	specified characteristics.
	152	</para></listitem>
	153	</varlistentry>
	154
5de0409e ZJS	155	</variablelist>
	156
	157	</refsect1>
	158
	159	<refsect1>
	160	<title>Matching</title>
	161
eca8701a	162	<para>A match can be:</para>
5de0409e ZJS	163
	164	<variablelist>
	165	<varlistentry>
6b76fa66	166	<term><replaceable>PID</replaceable></term>
5de0409e ZJS	167
	168	<listitem><para>Process ID of the
	169	process that dumped
	170	core. An integer.</para></listitem>
	171	</varlistentry>
	172
	173	<varlistentry>
6b76fa66	174	<term><replaceable>COMM</replaceable></term>
5de0409e ZJS	175
	176	<listitem><para>Name of the executable
	177	(matches <option>COREDUMP_COMM=</option>).
	178	Must not contain slashes.
	179	</para></listitem>
	180	</varlistentry>
	181
	182	<varlistentry>
6b76fa66	183	<term><replaceable>EXE</replaceable></term>
5de0409e ZJS	184
	185	<listitem><para>Path to the executable
	186	(matches <option>COREDUMP_EXE=</option>).
	187	Must contain at least one slash.
	188	</para></listitem>
	189	</varlistentry>
	190
	191	<varlistentry>
6b76fa66	192	<term><replaceable>MATCH</replaceable></term>
5de0409e ZJS	193
	194	<listitem><para>General journalctl predicates
	195	(see <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>).
eca8701a	196	Must contain an equal sign.
5de0409e ZJS	197	</para></listitem>
	198	</varlistentry>
	199	</variablelist>
	200	</refsect1>
	201
	202	<refsect1>
	203	<title>Exit status</title>
bcddd5bf JSJ	204	<para>On success, 0 is returned; otherwise, a non-zero failure
bcddd5bf JSJ	205	code is returned. Not finding any matching coredumps is treated
e9c1ea9d JSJ	206	as failure.
e9c1ea9d JSJ	207	</para>
5de0409e ZJS	208	</refsect1>
5de0409e ZJS	209
bb604b2f RC	210	<refsect1>
	211	<title>Examples</title>
	212
	213	<example>
	214	<title>List all the coredumps of a program named foo</title>
	215
	216	<programlisting># coredumpctl list foo</programlisting>
	217	</example>
	218
	219	<example>
	220	<title>Invoke gdb on the last coredump</title>
	221
	222	<programlisting># coredumpctl gdb</programlisting>
	223	</example>
	224
	225	<example>
08cb4bdd	226	<title>Show information about a process that dumped core, matching by its PID 6654</title>
bb604b2f RC	227
	228	<programlisting># coredumpctl info 6654</programlisting>
	229	</example>
	230
	231	<example>
	232	<title>Extract the last coredump of /usr/bin/bar to a file named bar.coredump</title>
	233
	234	<programlisting># coredumpctl -o bar.coredump dump /usr/bin/bar</programlisting>
	235	</example>
	236	</refsect1>
	237
5de0409e ZJS	238	<refsect1>
	239	<title>See Also</title>
	240	<para>
5146e7e8 ZJS	241	<citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
5146e7e8 ZJS	242	<citerefentry><refentrytitle>coredump.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
ada45c78	243	<citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
5aded369	244	<citerefentry project='man-pages'><refentrytitle>gdb</refentrytitle><manvolnum>1</manvolnum></citerefentry>
5de0409e ZJS	245	</para>
	246	</refsect1>
	247
	248	</refentry>