view release on metacpan or  search on metacpan

samples/xml-output-protocol4.txt  view on Meta::CPAN

why the spec calls for one or more CDATA blocks rather than exactly
one.

Note that, so far, we cannot envisage a circumstance in which a
generated suppression would contain the string "]]>", since neither
"]" nor ">" appear to turn up in mangled symbol names.  Hence it is
not envisaged that there will ever be more than one CDATA block, and
indeed the implementation as of Valgrind 3.5.0 will only ever generate
one block (it ignores any possible escaping problems).  Nevertheless
the specification allows multiple blocks, as a matter of safety.


SFRAME
------
Either

  <sframe> <obj>TEXT</obj> </sframe>

eg denoting "obj:/usr/X11R6/lib*/libX11.so.6.2", or

  <sframe> <fun>TEXT</fun> </sframe>

eg denoting "fun:*libc_write"


WHAT and XWHAT
--------------

WHAT supplies a single line of text, which is a human-understandable,
primary description of an error.

XWHAT is an extended version of WHAT.  It also contains a piece of
text intended for human reading, but in addition may contain arbitrary
other tagged data.  This extra data is tool-specific.  One of its
purposes is to supply GUIs with links to other data in the sequence of
TOOLSPECIFICs, that are associated with the error.  Another purpose is
wrap certain quantities (numbers, file names, etc) embedded in the
message, so that the GUIs can get hold of them without having to parse
the text itself.

For example, we could get:

  <what>Possible data race on address 0x12345678</what>

or alternatively

  <xwhat>
     <text>Possible data race by thread #17 on address 0x12345678</text>
     <threadid>17</threadid>
  </xwhat>

And presumably the <threadid>17</threadid> refers to some previously
emitted entity in the stream of TOOLSPECIFICs for this tool.

In an XWHAT, the <text> tag-pair is mandatory.  GUIs which don't want
to handle the extra fields can just ignore them and display the text
part.  In this way they have the option to present at least something
useful to the user even in the case where the extra fields can't be
handled, for whatever reason.

A corollary of this is that the degenerate extended case

   <xwhat> <text>T</text> </xwhat>

is exactly equivalent to

   <what>T</what>


AUXWHAT and XAUXWHAT
--------------------

AUXWHAT is exactly like WHAT: a single line of text.  It provides
additional, secondary description of an error, that should be shown to
the user.

XAUXWHAT relates to AUXWHAT in the same way XWHAT relates to WHAT: it
wraps up extra tagged info along with the line of text that would be
in the AUXWHAT.


====================================================================

ERROR definition -- common structure
------------------------------------

ERROR defines an error, and is the most complex nonterminal.  For all
of the tools, the structure is common, and always conforms to the
following:

  <error>
     <unique>HEX64</unique>
     <tid>INT</tid>
     <kind>KIND</kind>

     (either WHAT or XWHAT)
     optionally: (either WHAT or XWHAT)

     STACK

     zero or more: (either AUXWHAT or XAUXWHAT or STACK)

     optionally: SUPPRESSION
  </error>


* Each error contains a unique, arbitrary 64-bit hex number.  This is
  used to refer to the error in ERRORCOUNTS nonterminals (see above).

* The <tid> 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 <kind> tag specifies one of a small number of fixed error types,
  so that GUIs may roughly categorise errors by type if they want.
  The tags themselves are tool-specific and are defined further
  below, for each tool.

* The "(either WHAT or XWHAT)" gives a primary description of the
  error.  WHAT and XWHAT are defined earlier in this file.  Any XWHATs
  appearing here may contain tool-specific subcomponents.