]> git.vpit.fr Git - perl/modules/Test-Valgrind.git/blob - samples/xml-output.txt
Remove two misleading assigments in t/80-suppressions.t
[perl/modules/Test-Valgrind.git] / samples / xml-output.txt
1
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.
5
6
7 Design goals
8 ~~~~~~~~~~~~
9
10 * Produce XML output which is easily parsed
11
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.
15
16 * Have an extensive output format, so that future changes to the
17   format do not break backwards compatibility with existing parsers of
18   it.
19
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).
23
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).
26
27 * Make XML which is actually parseable by standard XML tools.
28
29
30 How to use
31 ~~~~~~~~~~
32
33 Run with flag --xml=yes.  That`s all.  Note however several
34 caveats.
35
36 * At the present time only Memcheck is supported.  The scheme extends
37   easily enough to cover Helgrind if needed.
38
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:
42
43   - Suppression generation is disabled, as that would require user
44     input.
45
46   - Attaching to GDB is disabled for the same reason.
47
48   - The verbosity level is set to 1 (-v).
49
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.
53
54   - VEX emulation warnings are not shown.
55
56   - File descriptor leak checking is disabled.  This could be
57     re-enabled at some future point.
58
59   - Maximum-detail leak checking is selected (--leak-check=full).
60
61
62 The output format
63 ~~~~~~~~~~~~~~~~~
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.
68
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>.
72
73 Symbols in CAPITALS are nonterminals in the grammar and are defined
74 somewhere below.  The root nonterminal is TOPLEVEL.
75
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".
80
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 "&lt;", "&gt;" and "&amp;" respectively.
84 Note this is not (yet) done throughout, only for function names in
85 <frame>..</frame> tags-pairs.
86
87
88 TOPLEVEL
89 --------
90
91 The first line output is always this:
92
93    <?xml version="1.0"?>
94
95 All remaining output is contained within the tag-pair
96 <valgrindoutput>.
97
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:
102
103   <?xml version="1.0"?>
104   <valgrindoutput>
105     <protocolversion>INT<protocolversion>
106     PROTOCOL
107   </valgrindoutput>
108
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
111 3.
112
113
114 PROTOCOL for version 3
115 ----------------------
116 Changes in 3.4.X (tentative): (jrs, 1 March 2008)
117
118 * There may be more than one <logfilequalifier> clause.
119
120 * Some errors may have two <auxwhat> blocks, rather than just one
121   (resulting from merge of the DATASYMS branch)
122
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.
126
127
128 PROTOCOL for version 2
129 ----------------------
130 Version 2 is identical in every way to version 1, except that the time
131 string in
132
133    <time>human-readable-time-string</time>
134
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
138 irrelevant.
139
140
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:
147
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:
151
152      <preamble>
153         <line>Misc version/copyright text</line>  (zero or more of)
154      </preamble>
155
156 * The PID of this process and of its parent:
157
158      <pid>INT</pid>
159      <ppid>INT</ppid>
160
161 * The name of the tool being used:
162
163      <tool>TEXT</tool>
164
165 * OPTIONALLY, if --log-file-qualifier=VAR flag was given:
166
167      <logfilequalifier> <var>VAR</var> <value>$VAR</value>
168      </logfilequalifier>
169
170   That is, both the name of the environment variable and its value
171   are given.
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.]
174
175 * OPTIONALLY, if --xml-user-comment=STRING was given:
176
177      <usercomment>STRING</usercomment>
178
179   STRING is not escaped in any way, so that it itself may be a piece
180   of XML with arbitrary tags etc.
181
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
184   client):
185
186      <args>
187        <vargv>
188          <exe>TEXT</exe>
189          <arg>TEXT</arg> (zero or more of)
190        </vargv>
191        <argv>
192          <exe>TEXT</exe>
193          <arg>TEXT</arg> (zero or more of)
194        </argv>
195      </args>
196
197 * The following, indicating that the program has now started:
198
199      <status> <state>RUNNING</state>
200               <time>human-readable-time-string</time>
201      </status>
202
203 * Zero or more of (either ERROR or ERRORCOUNTS).
204
205 * The following, indicating that the program has now finished, and
206   that the wrapup (leak checking) is happening.
207
208      <status> <state>FINISHED</state>
209               <time>human-readable-time-string</time>
210      </status>
211
212 * SUPPCOUNTS, indicating how many times each suppression was used.
213
214 * Zero or more ERRORs, each of which is a complaint from the
215   leak checker.
216
217 That's it.
218
219
220 ERROR
221 -----
222 This shows an error, and is the most complex nonterminal.  The format
223 is as follows:
224
225   <error>
226      <unique>HEX64</unique>
227      <tid>INT</tid>
228      <kind>KIND</kind>
229      <what>TEXT</what>
230
231      optionally: <leakedbytes>INT</leakedbytes>
232      optionally: <leakedblocks>INT</leakedblocks>
233
234      STACK
235
236      optionally: <auxwhat>TEXT</auxwhat>
237      optionally: STACK
238      optionally: ORIGIN
239
240   </error>
241
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).
244
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).
248
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.
252
253 * The <what> tag gives a human-understandable description of the
254   error.
255
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.
259
260 * The primary STACK for this error, indicating where it occurred.
261
262 * Some error types may have auxiliary information attached:
263
264      <auxwhat>TEXT</auxwhat> gives an auxiliary human-readable
265      description (usually of invalid addresses)
266
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.
270
271
272 KIND
273 ----
274 This is a small enumeration indicating roughly the nature of an error.
275 The possible values are:
276
277    InvalidFree
278
279       free/delete/delete[] on an invalid pointer
280
281    MismatchedFree
282
283       free/delete/delete[] does not match allocation function
284       (eg doing new[] then free on the result)
285
286    InvalidRead
287
288       read of an invalid address
289
290    InvalidWrite
291
292       write of an invalid address
293
294    InvalidJump
295
296       jump to an invalid address
297
298    Overlap
299
300       args overlap other otherwise bogus in eg memcpy
301
302    InvalidMemPool
303
304       invalid mem pool specified in client request
305
306    UninitCondition
307
308       conditional jump/move depends on undefined value
309
310    UninitValue
311
312       other use of undefined value (primarily memory addresses)
313
314    SyscallParam
315
316       system call params are undefined or point to
317       undefined/unaddressible memory
318
319    ClientCheck
320
321       "error" resulting from a client check request
322
323    Leak_DefinitelyLost
324
325       memory leak; the referenced blocks are definitely lost
326
327    Leak_IndirectlyLost
328
329       memory leak; the referenced blocks are lost because all pointers
330       to them are also in leaked blocks
331
332    Leak_PossiblyLost
333
334       memory leak; only interior pointers to referenced blocks were
335       found
336
337    Leak_StillReachable
338
339       memory leak; pointers to un-freed blocks are still available
340
341
342 STACK
343 -----
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.
347
348    <stack>
349       one or more FRAME
350    </stack>
351
352
353 FRAME
354 -----
355 FRAME records a single program location:
356
357    <frame>
358       <ip>HEX64</ip>
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>
364    </frame>
365
366 Only the <ip> field is guaranteed to be present.  It indicates a
367 code ("instruction pointer") address.
368
369 The optional fields, if present, appear in the order stated:
370
371 * obj: gives the name of the ELF object containing the code address
372
373 * fn: gives the name of the function containing the code address
374
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.
378
379 * file: gives the name of the source file containing the code address
380
381 * line: gives the line number in the source file
382
383
384 ORIGIN
385 ------
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.
390
391    <origin>
392       <what>TEXT<what>
393       STACK
394    </origin>
395
396
397 ERRORCOUNTS
398 -----------
399 This specifies, for each error that has been so far presented,
400 the number of occurrences of that error.
401
402   <errorcounts>
403      zero or more of
404         <pair> <count>INT</count> <unique>HEX64</unique> </pair>
405   </errorcounts>
406
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.
410
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.
415
416
417 SUPPCOUNTS
418 ----------
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.
422
423   <suppcounts>
424      zero or more of
425         <pair> <count>INT</count> <name>TEXT</name> </pair>
426   </suppcounts>
427
428 The <name> is as specified in the suppression name fields in .supp
429 files.
430