Note, 11 May 2009. The XML format evolved over several versions, as expected. This file describes 3 different versions of the format (called Protocols 1, 2 and 3 respectively). As of 11 May 09 a fourth version, Protocol 4, was defined, and that is described in xml-output-protocol4.txt. The original May 2005 introduction follows. These comments are correct up to and including Protocol 3, which was used in the Valgrind 3.4.x series. However, there were some more significant changes in the format and the required flags for Valgrind, in Protocol 4. ---------------------- As of May 2005, Valgrind can produce its output in XML form. The intention is to provide an easily parsed, stable format which is suitable for GUIs to read. Design goals ~~~~~~~~~~~~ * Produce XML output which is easily parsed * Have a stable output format which does not change much over time, so that investments in parser-writing by GUI developers is not lost as new versions of Valgrind appear. * Have an extensible output format, so that future changes to the format do not break backwards compatibility with existing parsers of it. * Produce output in a form which suitable for both offline GUIs (run all the way to the end, then examine output) and interactive GUIs (parse XML incrementally, update display as we go). * Put as much information as possible into the XML and let the GUIs decide what to show the user (a.k.a provide mechanism, not policy). * Make XML which is actually parseable by standard XML tools. How to use ~~~~~~~~~~ Run with flag --xml=yes. That's all. Note however several caveats. * At the present time only Memcheck is supported. The scheme extends easily enough to cover Helgrind if needed. * When XML output is selected, various other settings are made. This is in order that the output format is more controlled. The settings which are changed are: - Suppression generation is disabled, as that would require user input. - Attaching to GDB is disabled for the same reason. - The verbosity level is set to 1 (-v). - Error limits are disabled. Usually if the program generates a lot of errors, Valgrind slows down and eventually stops collecting them. When outputting XML this is not the case. - VEX emulation warnings are not shown. - File descriptor leak checking is disabled. This could be re-enabled at some future point. - Maximum-detail leak checking is selected (--leak-check=full). The output format ~~~~~~~~~~~~~~~~~ For the most part this should be self descriptive. It is printed in a sort-of human-readable way for easy understanding. You may want to read the rest of this together with the results of "valgrind --xml=yes memcheck/tests/xml1" as an example. All tags are balanced: a tag is always closed by . Hence in the description that follows, mention of a tag implicitly means there is a matching closing tag . Symbols in CAPITALS are nonterminals in the grammar and are defined somewhere below. The root nonterminal is TOPLEVEL. The following nonterminals are not described further: INT is a 64-bit signed decimal integer. TEXT is arbitrary text. HEX64 is a 64-bit hexadecimal number, with leading "0x". Text strings are escaped so as to remove the <, > and & characters which would otherwise mess up parsing. They are replaced respectively with the standard encodings "<", ">" and "&" respectively. Note this is not (yet) done throughout, only for function names in .. tags-pairs. TOPLEVEL -------- The first line output is always this: All remaining output is contained within the tag-pair . Inside that, the first entity is an indication of the protocol version. This is provided so that existing parsers can identify XML created by future versions of Valgrind merely by observing that the protocol version is one they don't understand. Hence TOPLEVEL is: INT PROTOCOL Valgrind versions 3.0.0 and 3.0.1 emit protocol version 1. Versions 3.1.X and 3.2.X emit protocol version 2. 3.4.X emits protocol version 3. PROTOCOL for version 3 ---------------------- Changes in 3.4.X (tentative): (jrs, 1 March 2008) * There may be more than one clause. * Some errors may have two blocks, rather than just one (resulting from merge of the DATASYMS branch) * Some errors may have an ORIGIN component, indicating the origins of uninitialised values. This results from the merge of the OTRACK_BY_INSTRUMENTATION branch. PROTOCOL for version 2 ---------------------- Version 2 is identical in every way to version 1, except that the time string in has changed format, and is also elapsed wallclock time since process start, and not local time or any such. In fact version 1 does not define the format of the string so in some ways this revision is irrelevant. PROTOCOL for version 1 ---------------------- This is the main top-level construction. Roughly speaking, it contains a load of preamble, the errors from the run of the program, and the result of the final leak check. Hence the following in sequence: * Various preamble lines which give version info for the various components. The text in them can be anything; it is not intended for interpretation by the GUI: Misc version/copyright text (zero or more of) * The PID of this process and of its parent: INT INT * The name of the tool being used: TEXT * OPTIONALLY, if --log-file-qualifier=VAR flag was given: VAR $VAR That is, both the name of the environment variable and its value are given. [update: as of v3.3.0, this is not present, as the --log-file-qualifier option has been removed, replaced by the %q format specifier in --log-file.] * OPTIONALLY, if --xml-user-comment=STRING was given: STRING STRING is not escaped in any way, so that it itself may be a piece of XML with arbitrary tags etc. * The program and args: first those pertaining to Valgrind itself, and then those pertaining to the program to be run under Valgrind (the client): TEXT TEXT (zero or more of) TEXT TEXT (zero or more of) * The following, indicating that the program has now started: RUNNING * Zero or more of (either ERROR or ERRORCOUNTS). * The following, indicating that the program has now finished, and that the wrapup (leak checking) is happening. FINISHED * SUPPCOUNTS, indicating how many times each suppression was used. * Zero or more ERRORs, each of which is a complaint from the leak checker. That's it. ERROR ----- This shows an error, and is the most complex nonterminal. The format is as follows: HEX64 INT KIND TEXT optionally: INT optionally: INT STACK optionally: TEXT optionally: STACK optionally: ORIGIN * Each error contains a unique, arbitrary 64-bit hex number. This is used to refer to the error in ERRORCOUNTS nonterminals (see below). * The tag indicates the Valgrind thread number. This value is arbitrary but may be used to determine which threads produced which errors (at least, the first instance of each error). * The tag specifies one of a small number of fixed error types (enumerated below), so that GUIs may roughly categorise errors by type if they want. * The tag gives a human-understandable description of the error. * For tags specifying a KIND of the form "Leak_*", the optional and indicate the number of bytes and blocks leaked by this error. * The primary STACK for this error, indicating where it occurred. * Some error types may have auxiliary information attached: TEXT gives an auxiliary human-readable description (usually of invalid addresses) STACK gives an auxiliary stack (usually the allocation/free point of a block). If this STACK is present then TEXT will precede it. KIND ---- This is a small enumeration indicating roughly the nature of an error. The possible values are: InvalidFree free/delete/delete[] on an invalid pointer MismatchedFree free/delete/delete[] does not match allocation function (eg doing new[] then free on the result) InvalidRead read of an invalid address InvalidWrite write of an invalid address InvalidJump jump to an invalid address Overlap args overlap other otherwise bogus in eg memcpy InvalidMemPool invalid mem pool specified in client request UninitCondition conditional jump/move depends on undefined value UninitValue other use of undefined value (primarily memory addresses) SyscallParam system call params are undefined or point to undefined/unaddressible memory ClientCheck "error" resulting from a client check request Leak_DefinitelyLost memory leak; the referenced blocks are definitely lost Leak_IndirectlyLost memory leak; the referenced blocks are lost because all pointers to them are also in leaked blocks Leak_PossiblyLost memory leak; only interior pointers to referenced blocks were found Leak_StillReachable memory leak; pointers to un-freed blocks are still available STACK ----- STACK indicates locations in the program being debugged. A STACK is one or more FRAMEs. The first is the innermost frame, the next its caller, etc. one or more FRAME FRAME ----- FRAME records a single program location: HEX64 optionally TEXT optionally TEXT optionally TEXT optionally TEXT optionally INT Only the field is guaranteed to be present. It indicates a code ("instruction pointer") address. The optional fields, if present, appear in the order stated: * obj: gives the name of the ELF object containing the code address * fn: gives the name of the function containing the code address * dir: gives the source directory associated with the name specified by . Note the current implementation often does not put anything useful in this field. * file: gives the name of the source file containing the code address * line: gives the line number in the source file ORIGIN ------ ORIGIN shows the origin of uninitialised data in errors that involve uninitialised data. STACK shows the origin of the uninitialised value. TEXT gives a human-understandable hint as to the meaning of the information in STACK. TEXT STACK ERRORCOUNTS ----------- This specifies, for each error that has been so far presented, the number of occurrences of that error. zero or more of INT HEX64 Each gives the current error count for the error with unique tag . The counts do not have to give a count for each error so far presented - partial information is allowable. As at Valgrind rev 3793, error counts are only emitted at program termination. However, it is perfectly acceptable to periodically emit error counts as the program is running. Doing so would facilitate a GUI to dynamically update its error-count display as the program runs. SUPPCOUNTS ---------- A SUPPCOUNTS block appears exactly once, after the program terminates. It specifies the number of times each error-suppression was used. Suppressions not mentioned were used zero times. zero or more of INT TEXT The is as specified in the suppression name fields in .supp files.