]> git.ipfire.org Git - thirdparty/systemd.git/blame - man/coredumpctl.xml
Merge pull request #8822 from fbuihuu/rfc-tmpfiles-safe-upstream
[thirdparty/systemd.git] / man / coredumpctl.xml
CommitLineData
5de0409e
ZJS
1<?xml version='1.0'?> <!--*-nxml-*-->
2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
12b42c76 3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
5de0409e
ZJS
4
5<!--
572eb058 6 SPDX-License-Identifier: LGPL-2.1+
5de0409e
ZJS
7-->
8
f4bab169 9<refentry id="coredumpctl" conditional='ENABLE_COREDUMP'
798d3a52
ZJS
10 xmlns:xi="http://www.w3.org/2001/XInclude">
11
12 <refentryinfo>
13 <title>coredumpctl</title>
14 <productname>systemd</productname>
798d3a52
ZJS
15 </refentryinfo>
16
17 <refmeta>
18 <refentrytitle>coredumpctl</refentrytitle>
19 <manvolnum>1</manvolnum>
20 </refmeta>
21
22 <refnamediv>
23 <refname>coredumpctl</refname>
246ba4aa 24 <refpurpose>Retrieve and process saved core dumps and metadata</refpurpose>
798d3a52
ZJS
25 </refnamediv>
26
27 <refsynopsisdiv>
28 <cmdsynopsis>
29 <command>coredumpctl</command>
30 <arg choice="opt" rep="repeat">OPTIONS</arg>
31 <arg choice="req">COMMAND</arg>
32 <arg choice="opt" rep="repeat">PID|COMM|EXE|MATCH</arg>
33 </cmdsynopsis>
34 </refsynopsisdiv>
35
36 <refsect1>
37 <title>Description</title>
38
246ba4aa
PM
39 <para><command>coredumpctl</command> is a tool that can be used to retrieve and process core
40 dumps and metadata which were saved by
41 <citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
42 </para>
798d3a52
ZJS
43 </refsect1>
44
45 <refsect1>
46 <title>Options</title>
47
48 <para>The following options are understood:</para>
49
50 <variablelist>
246ba4aa
PM
51
52 <xi:include href="standard-options.xml" xpointer="help" />
53 <xi:include href="standard-options.xml" xpointer="version" />
54
798d3a52
ZJS
55 <varlistentry>
56 <term><option>--no-legend</option></term>
57
246ba4aa 58 <listitem><para>Do not print column headers.</para></listitem>
798d3a52
ZJS
59 </varlistentry>
60
246ba4aa
PM
61 <xi:include href="standard-options.xml" xpointer="no-pager" />
62
798d3a52
ZJS
63 <varlistentry>
64 <term><option>-1</option></term>
65
246ba4aa
PM
66 <listitem><para>Show information of a single core dump only, instead of listing
67 all known core dumps.</para></listitem>
798d3a52
ZJS
68 </varlistentry>
69
4ab2753e
GS
70 <varlistentry>
71 <term><option>-S</option></term>
72 <term><option>--since</option></term>
73
74 <listitem><para>Only print entries which are since the specified date.</para></listitem>
75 </varlistentry>
76
77 <varlistentry>
78 <term><option>-U</option></term>
79 <term><option>--until</option></term>
80
81 <listitem><para>Only print entries which are until the specified date.</para></listitem>
82 </varlistentry>
83
c1143c93
NK
84 <varlistentry>
85 <term><option>-r</option></term>
86 <term><option>--reverse</option></term>
87
88 <listitem><para>Reverse output so that the newest entries are displayed first.
89 </para></listitem>
90 </varlistentry>
91
798d3a52 92 <varlistentry>
f6a4dae6
LP
93 <term><option>-F</option> <replaceable>FIELD</replaceable></term>
94 <term><option>--field=</option><replaceable>FIELD</replaceable></term>
798d3a52
ZJS
95
96 <listitem><para>Print all possible data values the specified
246ba4aa 97 field takes in matching core dump entries of the
798d3a52
ZJS
98 journal.</para></listitem>
99 </varlistentry>
100
101 <varlistentry>
f6a4dae6
LP
102 <term><option>-o</option> <replaceable>FILE</replaceable></term>
103 <term><option>--output=</option><replaceable>FILE</replaceable></term>
798d3a52
ZJS
104
105 <listitem><para>Write the core to <option>FILE</option>.
106 </para></listitem>
107 </varlistentry>
108
c5896b6a
RG
109 <varlistentry>
110 <term><option>--debugger=</option><replaceable>DEBUGGER</replaceable></term>
111
112 <listitem><para>Use the given debugger for the <command>debug</command>
113 command. If not given and <varname>$SYSTEMD_DEBUGGER</varname> is unset, then
114 <citerefentry><refentrytitle>gdb</refentrytitle><manvolnum>1</manvolnum></citerefentry>
115 will be used. </para></listitem>
116 </varlistentry>
117
b73e9a02
SW
118 <varlistentry>
119 <term><option>-D</option> <replaceable>DIR</replaceable></term>
120 <term><option>--directory=</option><replaceable>DIR</replaceable></term>
121
122 <listitem><para>Use the journal files in the specified <option>DIR</option>.
123 </para></listitem>
124 </varlistentry>
125
b9aaa7f4
ZJS
126 <varlistentry>
127 <term><option>-q</option></term>
128 <term><option>--quiet</option></term>
129
db9b9fb9 130 <listitem><para>Suppresses informational messages about lack
b9aaa7f4
ZJS
131 of access to journal files and possible in-flight coredumps.
132 </para></listitem>
133 </varlistentry>
798d3a52 134 </variablelist>
246ba4aa
PM
135 </refsect1>
136
137 <refsect1>
138 <title>Commands</title>
798d3a52
ZJS
139
140 <para>The following commands are understood:</para>
141
142 <variablelist>
143 <varlistentry>
144 <term><command>list</command></term>
145
246ba4aa 146 <listitem><para>List core dumps captured in the journal
798d3a52 147 matching specified characteristics. If no command is
246ba4aa
PM
148 specified, this is the implied default.</para>
149
cc4419ed
ZJS
150 <para>The output is designed to be human readable and contains list contains
151 a table with the following columns:</para>
152 <variablelist>
153 <varlistentry>
154 <term>TIME</term>
155 <listitem><para>The timestamp of the crash, as reported by the kernel.</para>
156 </listitem>
157 </varlistentry>
158
159 <varlistentry>
160 <term>PID</term>
161 <listitem><para>The identifier of the process that crashed.</para>
162 </listitem>
163 </varlistentry>
164
165 <varlistentry>
166 <term>UID</term>
167 <term>GID</term>
168 <listitem><para>The user and group identifiers of the process that crashed.</para>
169 </listitem>
170 </varlistentry>
171
172 <varlistentry>
173 <term>SIGNAL</term>
174 <listitem><para>The signal that caused the process to crash, when applicable.
175 </para></listitem>
176 </varlistentry>
177
178 <varlistentry>
179 <term>COREFILE</term>
180 <listitem><para>Information whether the coredump was stored, and whether
785889e5 181 it is still accessible: <literal>none</literal> means the core was
cc4419ed
ZJS
182 not stored, <literal>-</literal> means that it was not available (for
183 example because the process was not terminated by a signal),
184 <literal>present</literal> means that the core file is accessible by the
185 current user, <literal>journal</literal> means that the core was stored
186 in the <literal>journal</literal>, <literal>truncated</literal> is the
187 same as one of the previous two, but the core was too large and was not
188 stored in its entirety, <literal>error</literal> means that the core file
189 cannot be accessed, most likely because of insufficient permissions, and
190 <literal>missing</literal> means that the core was stored in a file, but
191 this file has since been removed.</para></listitem>
192 </varlistentry>
193
194 <varlistentry>
195 <term>EXE</term>
196 <listitem><para>The full path to the executable. For backtraces of scripts
197 this is the name of the interpreter.</para></listitem>
198 </varlistentry>
199 </variablelist>
200
246ba4aa
PM
201 <para>It's worth noting that different restrictions apply to
202 data saved in the journal and core dump files saved in
203 <filename>/var/lib/systemd/coredump</filename>, see overview in
204 <citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
205 Thus it may very well happen that a particular core dump is still listed
206 in the journal while its corresponding core dump file has already been
207 removed.</para></listitem>
798d3a52
ZJS
208 </varlistentry>
209
210 <varlistentry>
211 <term><command>info</command></term>
212
2fafabfd
LY
213 <listitem><para>Show detailed information about the last core dump
214 or core dumps matching specified characteristics
798d3a52
ZJS
215 captured in the journal.</para></listitem>
216 </varlistentry>
217
218 <varlistentry>
219 <term><command>dump</command></term>
220
246ba4aa
PM
221 <listitem><para>Extract the last core dump matching specified
222 characteristics. The core dump will be written on standard
798d3a52 223 output, unless an output file is specified with
f6a4dae6 224 <option>--output=</option>. </para></listitem>
798d3a52
ZJS
225 </varlistentry>
226
227 <varlistentry>
c5896b6a
RG
228 <term><command>debug</command></term>
229
230 <listitem><para>Invoke a debugger on the last core dump
231 matching specified characteristics. By default,
232 <citerefentry><refentrytitle>gdb</refentrytitle><manvolnum>1</manvolnum></citerefentry>
233 will be used. This may be changed using the <option>--debugger=</option>
234 option or the <varname>$SYSTEMD_DEBUGGER</varname> environment
235 variable.</para></listitem>
798d3a52
ZJS
236 </varlistentry>
237
238 </variablelist>
239
240 </refsect1>
241
242 <refsect1>
243 <title>Matching</title>
244
245 <para>A match can be:</para>
246
247 <variablelist>
248 <varlistentry>
249 <term><replaceable>PID</replaceable></term>
250
251 <listitem><para>Process ID of the
252 process that dumped
253 core. An integer.</para></listitem>
254 </varlistentry>
255
256 <varlistentry>
257 <term><replaceable>COMM</replaceable></term>
258
259 <listitem><para>Name of the executable (matches
260 <option>COREDUMP_COMM=</option>). Must not contain slashes.
261 </para></listitem>
262 </varlistentry>
263
264 <varlistentry>
265 <term><replaceable>EXE</replaceable></term>
266
267 <listitem><para>Path to the executable (matches
268 <option>COREDUMP_EXE=</option>). Must contain at least one
269 slash. </para></listitem>
270 </varlistentry>
271
272 <varlistentry>
273 <term><replaceable>MATCH</replaceable></term>
274
f8fde9ab
ZJS
275 <listitem><para>General journalctl match filter, must contain an equals
276 sign (<literal>=</literal>). See
277 <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
278 </para></listitem>
798d3a52
ZJS
279 </varlistentry>
280 </variablelist>
281 </refsect1>
282
283 <refsect1>
284 <title>Exit status</title>
285 <para>On success, 0 is returned; otherwise, a non-zero failure
246ba4aa 286 code is returned. Not finding any matching core dumps is treated as
798d3a52
ZJS
287 failure.
288 </para>
289 </refsect1>
290
60e9682a
ZJS
291 <refsect1>
292 <title>Environment</title>
293
294 <variablelist class='environment-variables'>
295 <varlistentry>
296 <term><varname>$SYSTEMD_DEBUGGER</varname></term>
297 <listitem><para>Use the given debugger for the <command>debug</command>
298 command. See the <option>--debugger=</option> option.</para></listitem>
299 </varlistentry>
300 </variablelist>
301 </refsect1>
302
798d3a52
ZJS
303 <refsect1>
304 <title>Examples</title>
305
306 <example>
246ba4aa 307 <title>List all the core dumps of a program named foo</title>
798d3a52
ZJS
308
309 <programlisting># coredumpctl list foo</programlisting>
310 </example>
311
312 <example>
246ba4aa 313 <title>Invoke gdb on the last core dump</title>
798d3a52 314
c5896b6a 315 <programlisting># coredumpctl debug</programlisting>
798d3a52
ZJS
316 </example>
317
318 <example>
319 <title>Show information about a process that dumped core,
320 matching by its PID 6654</title>
321
322 <programlisting># coredumpctl info 6654</programlisting>
323 </example>
324
325 <example>
246ba4aa 326 <title>Extract the last core dump of /usr/bin/bar to a file named
798d3a52
ZJS
327 <filename noindex="true">bar.coredump</filename></title>
328
329 <programlisting># coredumpctl -o bar.coredump dump /usr/bin/bar</programlisting>
330 </example>
331 </refsect1>
332
333 <refsect1>
334 <title>See Also</title>
335 <para>
336 <citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
337 <citerefentry><refentrytitle>coredump.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
338 <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
339 <citerefentry project='man-pages'><refentrytitle>gdb</refentrytitle><manvolnum>1</manvolnum></citerefentry>
340 </para>
341 </refsect1>
5de0409e
ZJS
342
343</refentry>