2 As of May 2005, Valgrind can produce its output in XML form. The
3 intention is to provide an easily parsed, stable format which is
4 suitable for GUIs to read.
10 * Produce XML output which is easily parsed
12 * Have a stable output format which does not change much over time, so
13 that investments in parser-writing by GUI developers is not lost as
14 new versions of Valgrind appear.
16 * Have an extensive output format, so that future changes to the
17 format do not break backwards compatibility with existing parsers of
20 * Produce output in a form which suitable for both offline GUIs (run
21 all the way to the end, then examine output) and interactive GUIs
22 (parse XML incrementally, update display as we go).
24 * Put as much information as possible into the XML and let the GUIs
25 decide what to show the user (a.k.a provide mechanism, not policy).
27 * Make XML which is actually parseable by standard XML tools.
33 Run with flag --xml=yes. That`s all. Note however several
36 * At the present time only Memcheck is supported. The scheme extends
37 easily enough to cover Helgrind if needed.
39 * When XML output is selected, various other settings are made.
40 This is in order that the output format is more controlled.
41 The settings which are changed are:
43 - Suppression generation is disabled, as that would require user
46 - Attaching to GDB is disabled for the same reason.
48 - The verbosity level is set to 1 (-v).
50 - Error limits are disabled. Usually if the program generates a lot
51 of errors, Valgrind slows down and eventually stops collecting
52 them. When outputting XML this is not the case.
54 - VEX emulation warnings are not shown.
56 - File descriptor leak checking is disabled. This could be
57 re-enabled at some future point.
59 - Maximum-detail leak checking is selected (--leak-check=full).
64 For the most part this should be self descriptive. It is printed in a
65 sort-of human-readable way for easy understanding. You may want to
66 read the rest of this together with the results of "valgrind --xml=yes
67 memcheck/tests/xml1" as an example.
69 All tags are balanced: a <foo> tag is always closed by </foo>. Hence
70 in the description that follows, mention of a tag <foo> implicitly
71 means there is a matching closing tag </foo>.
73 Symbols in CAPITALS are nonterminals in the grammar and are defined
74 somewhere below. The root nonterminal is TOPLEVEL.
76 The following nonterminals are not described further:
77 INT is a 64-bit signed decimal integer.
78 TEXT is arbitrary text.
79 HEX64 is a 64-bit hexadecimal number, with leading "0x".
81 Text strings are escaped so as to remove the <, > and & characters
82 which would otherwise mess up parsing. They are replaced respectively
83 with the standard encodings "<", ">" and "&" respectively.
84 Note this is not (yet) done throughout, only for function names in
85 <frame>..</frame> tags-pairs.
91 The first line output is always this:
95 All remaining output is contained within the tag-pair
98 Inside that, the first entity is an indication of the protocol
99 version. This is provided so that existing parsers can identify XML
100 created by future versions of Valgrind merely by observing that the
101 protocol version is one they don`t understand. Hence TOPLEVEL is:
103 <?xml version="1.0"?>
105 <protocolversion>INT<protocolversion>
109 Valgrind versions 3.0.0 and 3.0.1 emit protocol version 1. Versions
110 3.1.X and 3.2.X emit protocol version 2. 3.4.X emits protocol version
114 PROTOCOL for version 3
115 ----------------------
116 Changes in 3.4.X (tentative): (jrs, 1 March 2008)
118 * There may be more than one <logfilequalifier> clause.
120 * Some errors may have two <auxwhat> blocks, rather than just one
121 (resulting from merge of the DATASYMS branch)
123 * Some errors may have an ORIGIN component, indicating the origins of
124 uninitialised values. This results from the merge of the
125 OTRACK_BY_INSTRUMENTATION branch.
128 PROTOCOL for version 2
129 ----------------------
130 Version 2 is identical in every way to version 1, except that the time
133 <time>human-readable-time-string</time>
135 has changed format, and is also elapsed wallclock time since process
136 start, and not local time or any such. In fact version 1 does not
137 define the format of the string so in some ways this revision is
141 PROTOCOL for version 1
142 ----------------------
143 This is the main top-level construction. Roughly speaking, it
144 contains a load of preamble, the errors from the run of the
145 program, and the result of the final leak check. Hence the
146 following in sequence:
148 * Various preamble lines which give version info for the various
149 components. The text in them can be anything; it is not intended
150 for interpretation by the GUI:
153 <line>Misc version/copyright text</line> (zero or more of)
156 * The PID of this process and of its parent:
161 * The name of the tool being used:
165 * OPTIONALLY, if --log-file-qualifier=VAR flag was given:
167 <logfilequalifier> <var>VAR</var> <value>$VAR</value>
170 That is, both the name of the environment variable and its value
172 [update: as of v3.3.0, this is not present, as the --log-file-qualifier
173 option has been removed, replaced by the %q format specifier in --log-file.]
175 * OPTIONALLY, if --xml-user-comment=STRING was given:
177 <usercomment>STRING</usercomment>
179 STRING is not escaped in any way, so that it itself may be a piece
180 of XML with arbitrary tags etc.
182 * The program and args: first those pertaining to Valgrind itself, and
183 then those pertaining to the program to be run under Valgrind (the
189 <arg>TEXT</arg> (zero or more of)
193 <arg>TEXT</arg> (zero or more of)
197 * The following, indicating that the program has now started:
199 <status> <state>RUNNING</state>
200 <time>human-readable-time-string</time>
203 * Zero or more of (either ERROR or ERRORCOUNTS).
205 * The following, indicating that the program has now finished, and
206 that the wrapup (leak checking) is happening.
208 <status> <state>FINISHED</state>
209 <time>human-readable-time-string</time>
212 * SUPPCOUNTS, indicating how many times each suppression was used.
214 * Zero or more ERRORs, each of which is a complaint from the
222 This shows an error, and is the most complex nonterminal. The format
226 <unique>HEX64</unique>
231 optionally: <leakedbytes>INT</leakedbytes>
232 optionally: <leakedblocks>INT</leakedblocks>
236 optionally: <auxwhat>TEXT</auxwhat>
242 * Each error contains a unique, arbitrary 64-bit hex number. This is
243 used to refer to the error in ERRORCOUNTS nonterminals (see below).
245 * The <tid> tag indicates the Valgrind thread number. This value
246 is arbitrary but may be used to determine which threads produced
247 which errors (at least, the first instance of each error).
249 * The <kind> tag specifies one of a small number of fixed error
250 types (enumerated below), so that GUIs may roughly categorise
251 errors by type if they want.
253 * The <what> tag gives a human-understandable description of the
256 * For <kind> tags specifying a KIND of the form "Leak_*", the
257 optional <leakedbytes> and <leakedblocks> indicate the number of
258 bytes and blocks leaked by this error.
260 * The primary STACK for this error, indicating where it occurred.
262 * Some error types may have auxiliary information attached:
264 <auxwhat>TEXT</auxwhat> gives an auxiliary human-readable
265 description (usually of invalid addresses)
267 STACK gives an auxiliary stack (usually the allocation/free
268 point of a block). If this STACK is present then
269 <auxwhat>TEXT</auxwhat> will precede it.
274 This is a small enumeration indicating roughly the nature of an error.
275 The possible values are:
279 free/delete/delete[] on an invalid pointer
283 free/delete/delete[] does not match allocation function
284 (eg doing new[] then free on the result)
288 read of an invalid address
292 write of an invalid address
296 jump to an invalid address
300 args overlap other otherwise bogus in eg memcpy
304 invalid mem pool specified in client request
308 conditional jump/move depends on undefined value
312 other use of undefined value (primarily memory addresses)
316 system call params are undefined or point to
317 undefined/unaddressible memory
321 "error" resulting from a client check request
325 memory leak; the referenced blocks are definitely lost
329 memory leak; the referenced blocks are lost because all pointers
330 to them are also in leaked blocks
334 memory leak; only interior pointers to referenced blocks were
339 memory leak; pointers to un-freed blocks are still available
344 STACK indicates locations in the program being debugged. A STACK
345 is one or more FRAMEs. The first is the innermost frame, the
346 next its caller, etc.
355 FRAME records a single program location:
359 optionally <obj>TEXT</obj>
360 optionally <fn>TEXT</fn>
361 optionally <dir>TEXT</dir>
362 optionally <file>TEXT</file>
363 optionally <line>INT</line>
366 Only the <ip> field is guaranteed to be present. It indicates a
367 code ("instruction pointer") address.
369 The optional fields, if present, appear in the order stated:
371 * obj: gives the name of the ELF object containing the code address
373 * fn: gives the name of the function containing the code address
375 * dir: gives the source directory associated with the name specified
376 by <file>. Note the current implementation often does not
377 put anything useful in this field.
379 * file: gives the name of the source file containing the code address
381 * line: gives the line number in the source file
386 ORIGIN shows the origin of uninitialised data in errors that involve
387 uninitialised data. STACK shows the origin of the uninitialised
388 value. TEXT gives a human-understandable hint as to the meaning of
389 the information in STACK.
399 This specifies, for each error that has been so far presented,
400 the number of occurrences of that error.
404 <pair> <count>INT</count> <unique>HEX64</unique> </pair>
407 Each <pair> gives the current error count <count> for the error with
408 unique tag </unique>. The counts do not have to give a count for each
409 error so far presented - partial information is allowable.
411 As at Valgrind rev 3793, error counts are only emitted at program
412 termination. However, it is perfectly acceptable to periodically emit
413 error counts as the program is running. Doing so would facilitate a
414 GUI to dynamically update its error-count display as the program runs.
419 A SUPPCOUNTS block appears exactly once, after the program terminates.
420 It specifies the number of times each error-suppression was used.
421 Suppressions not mentioned were used zero times.
425 <pair> <count>INT</count> <name>TEXT</name> </pair>
428 The <name> is as specified in the suppression name fields in .supp