Add 436413 Warn about realloc of size zero to NEWS
[valgrind.git] / docs / internals / xml-output-protocol4.txt
blob461b8a50445a642badb898788911d177363a57a1
2 ====================================================================
4 14 October 2011
6 Protocols 1 through 3 supported Memcheck only.  Protocol 4 provides
7 XML output for Memcheck, Helgrind and DRD.  Technically there
8 are four variants of Protocol 4, one for each tool, since they
9 produce different errors.  The four variants differ only in the
10 definition of the ERROR nonterminal and are otherwise identical.
12 NOTE that Protocol 4 (for the current git master) is still under development.
13 The text herein should not be regarded as the final definition.
16 Identification of Protocols
17 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
19 In Protocols 1 through 3, a <protocolversion>INT<protocolversion>
20 close to the start of the stream makes it possible for parsers to
21 ascertain the version, so they can tell whether or not they can handle
22 it.  The presence of support for multiple tools brings a complication,
23 though: it is not enough merely to state the protocol version -- the
24 tool name must also be stated.  Hence in Protocol 4, the
25 <protocolversion>INT<protocolversion> is followed immediately by
26 <protocoltool>TEXT</protocoltool>, to identify the tool.
28 This duplicates the tool name present later in the preamble, but it
29 was felt important to place the tool name right at the front along
30 with the protocol number, for easy determination of parseability.
33 How this specification is structured
34 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
36 The TOPLEVEL nonterminal specifies top level XML output structure.  It
37 is common to all error producing tools.
39 TOPLEVEL references TOOLSPECIFICs for each tool, and these are defined
40 differently for each tool.  Each TOOLSPECIFIC is an error, which is
41 tool-specific.  For Helgrind and DRD, a TOOLSPECIFIC may also contain a
42 so-called thread-announcement record (described below).
44 Overall there is a very high degree of format commonality between the
45 three tools.  Once a GUI is able to display the output correctly for
46 one tool, it should be easy to extend it for the other two.
49 Protocol 4 changes for Memcheck
50 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
52 Protocol 4 for Memcheck is similar to Protocol 3, but has a number
53 of changes to make it fit in the common framework:
55 - the SUPPCOUNTS nonterminal now appears after the "Zero or more
56   ERRORs" block, and not before it.
58 - the abovementioned "Zero or more ERRORs" block now becomes
59   "Zero or more of (either ERROR or ERRORCOUNTS)".
61 - ERRORs for Memcheck may contain a SUPPRESSION field, which gives
62   the corresponding suppression for it.
64 - ERRORs for Memcheck now use the XWHAT and XAUXWHAT nonterminals, as
65   well as WHAT and XWHAT.
67 - The ad-hoc blocks <leakedbytes> and <leakedblocks> used by Memcheck
68   have been moved inside the XWHAT for the relevant error kinds.  This
69   facilitates a common definition of ERROR across all three tools.
71 The first two changes are required in order to correct a longstanding
72 design flaw in the way Memcheck interacts with Valgrind's error
73 management mechanism.  See bug #186790
74 (https://bugs.kde.org/show_bug.cgi?id=186790).  The third change was
75 requested in #191189 (https://bugs.kde.org/show_bug.cgi?id=191189).
77 For GUI authors upgrading from Protocol 3 or earlier, the most
78 significant new concept to grasp is the relationship between WHAT and
79 XWHAT, and between AUXWHAT and XAUXWHAT.
81 The definition of Protocol 4 now follows.  It is structured similarly
82 to that of the previous protocols, except that there is a separate
83 definition of a nonterminal called TOOLSPECIFIC for each of Memcheck,
84 Helgrind and DRD.  The XWHAT and XAUXWHAT nonterminals also
85 have tool-specific components.  Apart from that, the structure is
86 common to all supported tools.
89 ====================================================================
91 TOPLEVEL
92 --------
94 The first line output is always this:
96    <?xml version="1.0"?>
98 All remaining output is contained within the tag-pair
99 <valgrindoutput>.
101 Inside that, the first entity is an indication of the protocol
102 version.  This is provided so that existing parsers can identify XML
103 created by future versions of Valgrind merely by observing that the
104 protocol version is one they don't understand.  Hence TOPLEVEL is:
106   <?xml version="1.0"?>
107   <valgrindoutput>
108     <protocolversion>INT<protocolversion>
109     <protocoltool>TEXT</protocoltool>
110     PROTOCOL
111   </valgrindoutput>
113 Valgrind versions 3.0.0 and 3.0.1 emit protocol version 1.  Versions
114 3.1.X and 3.2.X [and 3.3.X ??] emit protocol version 2.  3.4.X emits
115 protocol version 3.  3.5.X emits version 4.
117 The TEXT in <protocoltool> is either "memcheck", "helgrind", "drd" or
118 "exp-ptrcheck" and determines the allowed format of the ERROR
119 nonterminal.  Note that <protocoltool> is only present when the
120 protocol version is 4 or above.
123 PROTOCOL for version 4
124 ----------------------
126 This is the main top-level construction.  Roughly speaking, it
127 contains a preamble, a program-started marker, the errors from the run
128 of the program, a program-ended marker, and any further errors
129 resulting from post-run analysis (eg, memory leak detection).  Hence
130 the following in sequence:
132 * Various preamble lines which give version info for the various
133   components.  The text in them can be anything; it is not intended
134   for interpretation by the GUI:
136      <preamble>
137         <line>Misc version/copyright text</line>  (zero or more of)
138      </preamble>
140 * The PID of this process and of its parent:
142      <pid>INT</pid>
143      <ppid>INT</ppid>
145 * The name of the tool being used:
147      <tool>TEXT</tool>
149   This can be anything, and it doesn't have to match the
150   <protocoltool> entry, although that might be wise.
152 * Zero or more bindings of environment variable names to actual
153   values.  These describe precisely the instantiations of %q format
154   specifiers used in the --xml-file= argument for the run, if any.
155   There is one <logfilequalifier> entry for each %q expanded:
157      <logfilequalifier> <var>VAR</var> <value>$VAR</value>
158      </logfilequalifier>
160 * OPTIONALLY, if --xml-user-comment=STRING was given:
162      <usercomment>STRING</usercomment>
164   STRING is not escaped in any way, so that it itself may be a piece
165   of XML with arbitrary tags etc.
167 * The program and args: first those pertaining to Valgrind itself, and
168   then those pertaining to the program to be run under Valgrind (the
169   client):
171      <args>
172        <vargv>
173          <exe>TEXT</exe>
174          <arg>TEXT</arg> (zero or more of)
175        </vargv>
176        <argv>
177          <exe>TEXT</exe>
178          <arg>TEXT</arg> (zero or more of)
179        </argv>
180      </args>
182 * The following, indicating that the program has now started:
184      <status> <state>RUNNING</state> 
185               <time>human-readable-time-string</time> 
186      </status>
188   The format of this string is not defined, but it is expected to be
189   human-understandable.  In current Valgrind versions it is the
190   elapsed wallclock time since process start.
192 * Zero or more of (either ERRORCOUNTS, TOOLSPECIFIC, or CLIENTMSG).
194 * The following, indicating that the program has now finished, and
195   that the any final wrapup (eg, for Memcheck, leak checking) is happening.
197      <status> <state>FINISHED</state> 
198               <time>human-readable-time-string</time> 
199      </status>
201 * Zero or more of (either ERRORCOUNTS or TOOLSPECIFIC).  In Memcheck's
202   case these will be complaints from the leak checker.  For Helgrind
203   we don't expect any output here (but the spec does not guarantee that
204   either).
206 * SUPPCOUNTS, indicating how many times each suppression was used.
209 That's it.  The tool-specific definitions for TOOLSPECIFIC are below;
210 however let's first continue with some smaller nonterminals used in
211 the construction of errors for all the tool types.
214 ====================================================================
216 Nonterminals used in construction of ERRORs
217 -------------------------------------------
219 STACK
220 -----
221 STACK indicates locations in the program being debugged.  A STACK
222 is one or more FRAMEs.  The first is the innermost frame, the
223 next its caller, etc.  
225    <stack>
226       one or more FRAME
227    </stack>
230 FRAME
231 -----
232 FRAME records a single program location:
234    <frame>
235       <ip>HEX64</ip>
236       optionally <obj>TEXT</obj>
237       optionally <fn>TEXT</fn>
238       optionally <dir>TEXT</dir>
239       optionally <file>TEXT</file>
240       optionally <line>INT</line>
241    </frame>
243 Only the <ip> field is guaranteed to be present.  It indicates a
244 code ("instruction pointer") address.
246 The optional fields, if present, appear in the order stated:
248 * obj: gives the name of the ELF object containing the code address
250 * fn: gives the name of the function containing the code address
252 * dir: gives the source directory associated with the name specified
253        by <file>.  Note the current implementation often does not
254        put anything useful in this field.
256 * file: gives the name of the source file containing the code address
258 * line: gives the line number in the source file
261 ERRORCOUNTS
262 -----------
263 This specifies, for each error that has been so far presented,
264 the number of occurrences of that error.
266   <errorcounts>
267      zero or more of
268         <pair> <count>INT</count> <unique>HEX64</unique> </pair>
269   </errorcounts>
271 Each <pair> gives the current error count <count> for the error with
272 unique tag </unique>.  The counts do not have to give a count for each
273 error so far presented - partial information is allowable.
275 As at Valgrind rev 3793, error counts are only emitted at program
276 termination.  However, it is perfectly acceptable to periodically emit
277 error counts as the program is running.  Doing so would facilitate a
278 GUI to dynamically update its error-count display as the program runs.
281 SUPPCOUNTS
282 ----------
283 A SUPPCOUNTS block appears exactly once, after the program terminates.
284 It specifies the number of times each error-suppression was used.
285 Suppressions not mentioned were used zero times.
287   <suppcounts>
288      zero or more of
289         <pair> <count>INT</count> <name>TEXT</name> </pair>
290   </suppcounts>
292 The <name> is as specified in the suppression name fields in .supp
293 files.
296 SUPPRESSION
297 -----------
298 These are optionally emitted as part of ERRORs, and specify the
299 suppression that would be needed to suppress the containing error.
300 For convenience, the suppression is presented twice, once in
301 a structured nicely wrapped up in tags, and once as raw text
302 suitable for direct copying and pasting into a suppressions file.
304   <suppression>
305     <sname>TEXT</sname>    name of the suppression
306     <skind>TEXT</skind>    kind, eg                 "Memcheck:Param"
307     <skaux>TEXT</skaux>    (optional) aux kind, eg  "write(buf)"
308     SFRAME                 (one or more) frames
309     <rawtext> CDATAS </rawtext>
310   </suppression>
312 where CDATAS is a sequence of one or more <![CDATA[ .. ]]> blocks
313 holding the raw text.  Unfortunately, CDATA provides no way to escape
314 the ending marker "]]>", which means that if the raw data contains
315 such a sequence, it has to be split between two CDATA blocks, one
316 ending with data "]]" and the other beginning with data "<".  This is
317 why the spec calls for one or more CDATA blocks rather than exactly
318 one.
320 Note that, so far, we cannot envisage a circumstance in which a
321 generated suppression would contain the string "]]>", since neither
322 "]" nor ">" appear to turn up in mangled symbol names.  Hence it is
323 not envisaged that there will ever be more than one CDATA block, and
324 indeed the implementation as of Valgrind 3.5.0 will only ever generate
325 one block (it ignores any possible escaping problems).  Nevertheless
326 the specification allows multiple blocks, as a matter of safety.
329 SFRAME
330 ------
331 Either
333   <sframe> <obj>TEXT</obj> </sframe>
335 eg denoting "obj:/usr/X11R6/lib*/libX11.so.6.2", or
337   <sframe> <fun>TEXT</fun> </sframe>
339 eg denoting "fun:*libc_write"
342 WHAT and XWHAT
343 --------------
345 WHAT supplies a single line of text, which is a human-understandable,
346 primary description of an error.
348 XWHAT is an extended version of WHAT.  It also contains a piece of
349 text intended for human reading, but in addition may contain arbitrary
350 other tagged data.  This extra data is tool-specific.  One of its
351 purposes is to supply GUIs with links to other data in the sequence of
352 TOOLSPECIFICs, that are associated with the error.  Another purpose is
353 wrap certain quantities (numbers, file names, etc) embedded in the
354 message, so that the GUIs can get hold of them without having to parse
355 the text itself.
357 For example, we could get:
359   <what>Possible data race on address 0x12345678</what>
361 or alternatively
363   <xwhat>
364      <text>Possible data race by thread #17 on address 0x12345678</text>
365      <threadid>17</threadid>
366   </xwhat>
368 And presumably the <threadid>17</threadid> refers to some previously
369 emitted entity in the stream of TOOLSPECIFICs for this tool.
371 In an XWHAT, the <text> tag-pair is mandatory.  GUIs which don't want
372 to handle the extra fields can just ignore them and display the text
373 part.  In this way they have the option to present at least something
374 useful to the user even in the case where the extra fields can't be
375 handled, for whatever reason.
377 A corollary of this is that the degenerate extended case
379    <xwhat> <text>T</text> </xwhat>
381 is exactly equivalent to
383    <what>T</what>
386 AUXWHAT and XAUXWHAT
387 --------------------
389 AUXWHAT is exactly like WHAT: a single line of text.  It provides
390 additional, secondary description of an error, that should be shown to
391 the user.
393 XAUXWHAT relates to AUXWHAT in the same way XWHAT relates to WHAT: it
394 wraps up extra tagged info along with the line of text that would be
395 in the AUXWHAT.
398 ====================================================================
400 ERROR definition -- common structure
401 ------------------------------------
403 ERROR defines an error, and is the most complex nonterminal.  For all
404 of the tools, the structure is common, and always conforms to the
405 following:
407   <error>
408      <unique>HEX64</unique>
409      <tid>INT</tid>
410      <threadname>NAME</threadname>    if set
411      <kind>KIND</kind>
413      (either WHAT or XWHAT)
414      optionally: (either WHAT or XWHAT)
416      STACK
418      zero or more: (either AUXWHAT or XAUXWHAT or STACK)
420      optionally: SUPPRESSION
421   </error>
424 * Each error contains a unique, arbitrary 64-bit hex number.  This is
425   used to refer to the error in ERRORCOUNTS nonterminals (see above).
427 * The <tid> tag indicates the Valgrind thread number.  This value
428   is arbitrary but may be used to determine which threads produced
429   which errors (at least, the first instance of each error).
431 * The <threadname> tag identifies the name of the thread if it was
432   set by the client application. If no name was set, the tag is
433   omitted.
435 * The <kind> tag specifies one of a small number of fixed error types,
436   so that GUIs may roughly categorise errors by type if they want.
437   The tags themselves are tool-specific and are defined further
438   below, for each tool.
440 * The "(either WHAT or XWHAT)" gives a primary description of the
441   error.  WHAT and XWHAT are defined earlier in this file.  Any XWHATs
442   appearing here may contain tool-specific subcomponents.
444 * Optionally, a second line of primary description may be present.
446 * A STACK gives the primary source location for the error.
448 * There then follow zero or more of "(either AUXWHAT or XAUXWHAT or
449   STACK)".  These give further (auxiliary) information about the
450   error, possibly including stack traces.  They should be shown to the
451   user in the order they appear.  AUXWHAT and XAUXWHAT are defined
452   earlier in this file.  Any XAUXWHATs appearing here may contain
453   tool-specific subcomponents.
455 * Optionally, as the last field, a SUPPRESSION may be provided.  This
456   contains a suppression that would hide the error.
459 ====================================================================
461 TOOLSPECIFIC definition for Memcheck
462 ------------------------------------
464 For Memcheck, a TOOLSPECIFIC is simply an ERROR:
466 TOOLSPECIFIC = ERROR
469 ERROR details for Memcheck
470 --------------------------
472 XWHATs (for definition, see above) may contain the following extra
473 components (along with the mandatory <text>...</text> component):
475 * <leakedbytes>INT</leakedbytes>
477 * <leakedblocks>INT</leakedblocks>
479 These fields are used in errors that have a <kind> tag specifying a
480 KIND of the form "Leak_*", to indicate the number of leaked bytes and
481 blocks.
484 XAUXWHATs (for definition, see above) may contain the following extra
485 components (along with the mandatory <text>...</text> component):
487 * <file>TEXT</file>, as defined in FRAME
489 * <line>INT</line>, as defined in FRAME
491 * <dir>TEXT</dir>, as defined in FRAME
494 KIND for Memcheck
495 -----------------
497 This is a small enumeration indicating roughly the nature of an error.
498 The possible values are:
500    UninitValue
502       other use of undefined value (primarily memory addresses)
504    UninitCondition
506       conditional jump/move depends on undefined value
508    CoreMemError
510       caused by unaddressable bytes in a signal handler frame
512    InvalidRead
514       read of an invalid address
516    InvalidWrite
518       write of an invalid address
520    InvalidJump
522       jump to an invalid address
524    SyscallParam
526       system call params are undefined or point to
527       undefined/unaddressible memory
529    ClientCheck
531       "error" resulting from a client check request
533    InvalidFree
535       free/delete/delete[] on an invalid pointer
537    MismatchedFree
539       free/delete/delete[] does not match allocation function
540       (eg doing new[] then free on the result)
542    Overlap
544       args overlap other otherwise bogus in eg memcpy
546    Leak_DefinitelyLost
548       memory leak; the referenced blocks are definitely lost
550    Leak_IndirectlyLost
552       memory leak; the referenced blocks are lost because all pointers
553       to them are also in leaked blocks
555    Leak_PossiblyLost
557       memory leak; only interior pointers to referenced blocks were
558       found
560    Leak_StillReachable
562       memory leak; pointers to un-freed blocks are still available
564    InvalidMemPool
566       invalid mem pool specified in client request
568    FishyValue
570       arguments to memory allocation function are very large,
571       indicating probable integer overflow or cast from negative signed
574 ====================================================================
576 TOOLSPECIFIC definition for Helgrind
577 -------------------------------------
579 For Helgrind, a TOOLSPECIFIC may be one of two things:
581 TOOLSPECIFIC = either ERROR or ANNOUNCETHREAD
584 ANNOUNCETHREAD
585 --------------
587 The definition is
589    <announcethread>
590       <hthreadid>INT</hthreadid>
591       STACK
592    </announcethread>
594 This states the creation point of a thread, and gives it a unique
595 "hthreadid", which may be referred to in subsequent ERRORs.  Note that
597 1. The appearance of ANNOUNCETHREAD does not mean that the thread was
598    actually created at that point relative to any preceding or
599    following ERRORs in the output stream -- in general the thread will
600    have been created arbitrarily earlier.  Helgrind only "announces" a
601    thread when it needs to refer to it for the first time, in a
602    subsequent ERROR.
604 2. The "hthreadid" is a number which uniquely identifies the thread
605    for the run - no other thread will have the same hthreadid.  The
606    hthreadid is a Helgrind-specific piece of information and is
607    unrelated to the <tid> fields in the common part of an ERROR.
608    Be careful not to confuse the two.
611 ERROR details for Helgrind
612 --------------------------
614 XWHATs (for definition, see above) may contain the following extra
615 components (along with the mandatory <text>...</text> component):
617 * <hthreadid>INT</hthreadid> fields.  These refer to ANNOUNCETHREADs
618   appearing previously in the scheme, and state the creation points of
619   the thread(s) concerned in the ERROR.  Hence it should be possible
620   for GUIs to show users stacks of the creation points of all threads
621   involved in each ERROR.
624 XAUXWHATs (for definition, see above) may contain the following extra
625 components (along with the mandatory <text>...</text> component):
627 * <hthreadid>INT</hthreadid>, same meaning as when referred to in
628   XWHAT
630 * <file>TEXT</file>, as defined in FRAME
632 * <line>INT</line>, as defined in FRAME
634 * <dir>TEXT</dir>, as defined in FRAME
637 KIND for Helgrind
638 -----------------
639 This is a small enumeration indicating roughly the nature of an error.
640 The possible values are:
642    Race
644       Data race.  Helgrind will try to show the stacks for both
645       conflicting accesses if it can; it will always show the stack
646       for at least one of them.
648    UnlockUnlocked
650       Unlocking a not-locked lock
652    UnlockForeign
654       Unlocking a lock held by some other thread
656    UnlockBogus
658       Unlocking an address which is not known to be a lock
660    PthAPIerror
662       One of the POSIX pthread_ functions that are intercepted
663       by Helgrind, failed with an error code.  Usually indicates
664       something bad happening.
666    LockOrder
668       An inconsistency in the acquisition order of locks was observed;
669       dangerous, as it can potentially lead to deadlocks
671    Misc
673       One of various miscellaneous noteworthy conditions was observed
674       (eg, thread exited whilst holding locks, "impossible" behaviour
675       from the underlying threading library, etc)
677 ====================================================================
679 CLIENTMSG
681 CLIENTMSG defines a message that was caused by one of the following
682 client requests:
684 - VALGRIND_PRINTF
685 - VALGRIND_PRINTF_BACKTRACE
687 Definition:
689 <clientmsg>
690   <tid>INT</tid>
691   <threadname>NAME</threadname>    if set
692   <text>...</text>
693 </clientmsg>
697 <clientmsg>
698   <tid>INT</tid>
699   <threadname>NAME</threadname>    if set
700   <text>...</text>
701   STACK
702 </clientmsg>
704 * The <tid> tag indicates the Valgrind thread number.
706 * The <threadname> tag identifies the name of the thread if it was
707   set by the client application. If no name was set, the tag is
708   omitted.
710 * The <text> tag indicates the message as specified in the client request
711   (properly translated to XML).
713 * STACK is only present in case of VALGRIND_PRINTF_BACKTRACE. See above
714   for a definition of STACK.
716 ====================================================================
718 FATAL_SIGNAL
720 FATAL_SIGNAL defines a message that was caused by a signal that killed them
721 process.
723 Definition:
725   <fatal_signal>
726      <tid>INT</tid>
727      <threadname>NAME</threadname>    if set
729      <signo>INT</signo>
730      <signame>NAME</signame>
732      <sicode>INT</sicode>
733      <event>NAME</event>
734      <siaddr>ADDR</siaddr>
736      STACK
738   </fatal_signal>
740 * The <tid> tag indicates the Valgrind thread number.  This value
741   is arbitrary but may be used to determine which threads produced
742   which errors (at least, the first instance of each error).
744 * The <threadname> tag identifies the name of the thread if it was
745   set by the client application. If no name was set, the tag is
746   omitted.
748 * The <signo> tag indicates signo value from struct siginfo.
750 * In <signame> tag there is the decoded name of signo.
752 * The <sicode> tag contains the sicode from struct siginfo.
754 * The <event> tag indicates the decoded name of the sicode. If sicode
755   has no name, the tag is omitted.
757 * The <siaddr> tag indicates the address that is the reason
758   why the signal was triggered. This can be an unaligned pointer value or
759   just the address of not mapped memory that is accessed nevertheless.
760   If the signal reason is not related to an address, the tag is omitted.
762 * STACK is defined above and shows where the thread was when it
763   caught the signal.  When sending the signal to itself using raise,
764   then raise is visible in this stack.