doc/xmlwf.xml

   1 <!--
   2                             __  __            _
   3                          ___\ \/ /_ __   __ _| |_
   4                         / _ \\  /| '_ \ / _` | __|
   5                        |  __//  \| |_) | (_| | |_
   6                         \___/_/\_\ .__/ \__,_|\__|
   7                                  |_| XML parser
   8
   9    Copyright (c) 2001      Scott Bronson <bronson@rinspin.com>
  10    Copyright (c) 2002-2003 Fred L. Drake, Jr. <fdrake@users.sourceforge.net>
  11    Copyright (c) 2009      Karl Waclawek <karl@waclawek.net>
  12    Copyright (c) 2016-2024 Sebastian Pipping <sebastian@pipping.org>
  13    Copyright (c) 2016      Ardo van Rangelrooij <ardo@debian.org>
  14    Copyright (c) 2017      Rhodri James <rhodri@wildebeest.org.uk>
  15    Copyright (c) 2020      Joe Orton <jorton@redhat.com>
  16    Copyright (c) 2021      Tim Bray <tbray@textuality.com>
  17    Unlike most of Expat,
  18    this file is copyrighted under the GNU Free Documentation License 1.1.
  19 -->
  20 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
  21           "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
  22   <!ENTITY dhfirstname "<firstname>Scott</firstname>">
  23   <!ENTITY dhsurname   "<surname>Bronson</surname>">
  24   <!ENTITY dhdate      "<date>March 13, 2024</date>">
  25   <!-- Please adjust this^^ date whenever cutting a new release. -->
  26   <!ENTITY dhsection   "<manvolnum>1</manvolnum>">
  27   <!ENTITY dhemail     "<email>bronson@rinspin.com</email>">
  28   <!ENTITY dhusername  "Scott Bronson">
  29   <!ENTITY dhucpackage "<refentrytitle>XMLWF</refentrytitle>">
  30   <!ENTITY dhpackage   "xmlwf">
  31
  32   <!ENTITY debian      "<productname>Debian GNU/Linux</productname>">
  33   <!ENTITY gnu         "<acronym>GNU</acronym>">
  34 ]>
  35
  36 <refentry>
  37   <refentryinfo>
  38     <address>
  39       &dhemail;
  40     </address>
  41     <author>
  42       &dhfirstname;
  43       &dhsurname;
  44     </author>
  45     <copyright>
  46       <year>2001</year>
  47       <holder>&dhusername;</holder>
  48     </copyright>
  49     &dhdate;
  50   </refentryinfo>
  51   <refmeta>
  52     &dhucpackage;
  53
  54     &dhsection;
  55   </refmeta>
  56   <refnamediv>
  57     <refname>&dhpackage;</refname>
  58
  59     <refpurpose>Determines if an XML document is well-formed</refpurpose>
  60   </refnamediv>
  61   <refsynopsisdiv>
  62     <cmdsynopsis>
  63       <command>&dhpackage;</command>
  64       <arg><replaceable>OPTIONS</replaceable></arg>
  65       <arg><replaceable>FILE</replaceable> ...</arg>
  66     </cmdsynopsis>
  67     <cmdsynopsis>
  68       <command>&dhpackage;</command>
  69       <group choice="plain">
  70         <arg><option>-h</option></arg>
  71         <arg><option>--help</option></arg>
  72       </group>
  73     </cmdsynopsis>
  74     <cmdsynopsis>
  75       <command>&dhpackage;</command>
  76       <group choice="plain">
  77         <arg><option>-v</option></arg>
  78         <arg><option>--version</option></arg>
  79       </group>
  80     </cmdsynopsis>
  81   </refsynopsisdiv>
  82
  83   <refsect1>
  84     <title>DESCRIPTION</title>
  85
  86     <para>
  87         <command>&dhpackage;</command> uses the Expat library to
  88         determine if an XML document is well-formed.  It is
  89         non-validating.
  90         </para>
  91
  92         <para>
  93         If you do not specify any files on the command-line, and you
  94         have a recent version of <command>&dhpackage;</command>, the
  95         input file will be read from standard input.
  96         </para>
  97
  98   </refsect1>
  99
 100   <refsect1>
 101     <title>WELL-FORMED DOCUMENTS</title>
 102
 103         <para>
 104           A well-formed document must adhere to the
 105           following rules:
 106         </para>
 107
 108         <itemizedlist>
 109       <listitem><para>
 110             The file begins with an XML declaration.  For instance,
 111                 <literal>&lt;?xml version="1.0" standalone="yes"?&gt;</literal>.
 112                 <emphasis>NOTE</emphasis>:
 113                 <command>&dhpackage;</command> does not currently
 114                 check for a valid XML declaration.
 115       </para></listitem>
 116       <listitem><para>
 117                 Every start tag is either empty (&lt;tag/&gt;)
 118                 or has a corresponding end tag.
 119       </para></listitem>
 120       <listitem><para>
 121             There is exactly one root element.  This element must contain
 122                 all other elements in the document.  Only comments, white
 123                 space, and processing instructions may come after the close
 124                 of the root element.
 125       </para></listitem>
 126       <listitem><para>
 127                 All elements nest properly.
 128       </para></listitem>
 129       <listitem><para>
 130                 All attribute values are enclosed in quotes (either single
 131                 or double).
 132       </para></listitem>
 133     </itemizedlist>
 134
 135         <para>
 136           If the document has a DTD, and it strictly complies with that
 137           DTD, then the document is also considered <emphasis>valid</emphasis>.
 138           <command>&dhpackage;</command> is a non-validating parser --
 139           it does not check the DTD.  However, it does support
 140           external entities (see the <option>-x</option> option).
 141         </para>
 142   </refsect1>
 143
 144   <refsect1>
 145     <title>OPTIONS</title>
 146
 147 <para>
 148 When an option includes an argument, you may specify the argument either
 149 separately ("<option>-d</option> <replaceable>output</replaceable>") or concatenated with the
 150 option ("<option>-d</option><replaceable>output</replaceable>").  <command>&dhpackage;</command>
 151 supports both.
 152 </para>
 153
 154     <variablelist>
 155
 156       <varlistentry>
 157         <term><option>-a</option> <replaceable>factor</replaceable></term>
 158         <listitem>
 159           <para>
 160             Sets the maximum tolerated amplification factor
 161             for protection against billion laughs attacks (default: 100.0).
 162             The amplification factor is calculated as ..
 163           </para>
 164           <literallayout>
 165             amplification := (direct + indirect) / direct
 166           </literallayout>
 167           <para>
 168             .. while parsing, whereas
 169             &lt;direct&gt; is the number of bytes read
 170               from the primary document in parsing and
 171             &lt;indirect&gt; is the number of bytes
 172               added by expanding entities and reading of external DTD files,
 173               combined.
 174           </para>
 175           <para>
 176             <emphasis>NOTE</emphasis>:
 177             If you ever need to increase this value for non-attack payload,
 178             please file a bug report.
 179           </para>
 180         </listitem>
 181       </varlistentry>
 182
 183       <varlistentry>
 184         <term><option>-b</option> <replaceable>bytes</replaceable></term>
 185         <listitem>
 186           <para>
 187             Sets the number of output bytes (including amplification)
 188             needed to activate protection against billion laughs attacks
 189             (default: 8 MiB).
 190             This can be thought of as an &quot;activation threshold&quot;.
 191           </para>
 192           <para>
 193             <emphasis>NOTE</emphasis>:
 194             If you ever need to increase this value for non-attack payload,
 195             please file a bug report.
 196           </para>
 197         </listitem>
 198       </varlistentry>
 199
 200       <varlistentry>
 201         <term><option>-c</option></term>
 202         <listitem>
 203                 <para>
 204   If the input file is well-formed and <command>&dhpackage;</command>
 205   doesn't encounter any errors, the input file is simply copied to
 206   the output directory unchanged.
 207   This implies no namespaces (turns off <option>-n</option>) and
 208   requires <option>-d</option> to specify an output directory.
 209                 </para>
 210         </listitem>
 211       </varlistentry>
 212
 213       <varlistentry>
 214         <term><option>-d</option> <replaceable>output-dir</replaceable></term>
 215         <listitem>
 216                 <para>
 217   Specifies a directory to contain transformed
 218   representations of the input files.
 219   By default, <option>-d</option> outputs a canonical representation
 220   (described below).
 221   You can select different output formats using <option>-c</option>,
 222   <option>-m</option> and <option>-N</option>.
 223           </para>
 224           <para>
 225   The output filenames will
 226   be exactly the same as the input filenames or "STDIN" if the input is
 227   coming from standard input.  Therefore, you must be careful that the
 228   output file does not go into the same directory as the input
 229   file.  Otherwise, <command>&dhpackage;</command> will delete the
 230   input file before it generates the output file (just like running
 231   <literal>cat &lt; file &gt; file</literal> in most shells).
 232           </para>
 233           <para>
 234   Two structurally equivalent XML documents have a byte-for-byte
 235   identical canonical XML representation.
 236   Note that ignorable white space is considered significant and
 237   is treated equivalently to data.
 238   More on canonical XML can be found at
 239   http://www.jclark.com/xml/canonxml.html .
 240           </para>
 241         </listitem>
 242       </varlistentry>
 243
 244       <varlistentry>
 245         <term><option>-e</option> <replaceable>encoding</replaceable></term>
 246         <listitem>
 247                 <para>
 248    Specifies the character encoding for the document, overriding
 249    any document encoding declaration.  <command>&dhpackage;</command>
 250    supports four built-in encodings:
 251         <literal>US-ASCII</literal>,
 252         <literal>UTF-8</literal>,
 253         <literal>UTF-16</literal>, and
 254         <literal>ISO-8859-1</literal>.
 255    Also see the <option>-w</option> option.
 256            </para>
 257         </listitem>
 258       </varlistentry>
 259
 260       <varlistentry>
 261         <term><option>-g</option> <replaceable>bytes</replaceable></term>
 262         <listitem>
 263           <para>
 264             Sets the buffer size to request per call pair to
 265             <function>XML_GetBuffer</function> and <function>read</function>
 266             (default: 8 KiB).
 267           </para>
 268         </listitem>
 269       </varlistentry>
 270
 271       <varlistentry>
 272         <term><option>-h</option></term>
 273         <term><option>--help</option></term>
 274         <listitem>
 275           <para>
 276             Prints short usage information on command <command>&dhpackage;</command>,
 277             and then exits.
 278             Similar to this man page but more concise.
 279           </para>
 280         </listitem>
 281       </varlistentry>
 282
 283       <varlistentry>
 284         <term><option>-k</option></term>
 285         <listitem>
 286           <para>
 287             When processing multiple files, <command>&dhpackage;</command>
 288             by default halts after the the first file with an error.
 289             This tells <command>&dhpackage;</command> to report the error
 290             but to keep processing.
 291             This can be useful, for example, when testing a filter that converts
 292             many files to XML and you want to quickly find out which conversions
 293             failed.
 294           </para>
 295         </listitem>
 296       </varlistentry>
 297
 298       <varlistentry>
 299         <term><option>-m</option></term>
 300         <listitem>
 301                 <para>
 302   Outputs some strange sort of XML file that completely
 303   describes the input file, including character positions.
 304   Requires <option>-d</option> to specify an output file.
 305            </para>
 306         </listitem>
 307       </varlistentry>
 308
 309       <varlistentry>
 310         <term><option>-n</option></term>
 311         <listitem>
 312                 <para>
 313   Turns on namespace processing.  (describe namespaces)
 314   <option>-c</option> disables namespaces.
 315            </para>
 316         </listitem>
 317       </varlistentry>
 318
 319       <varlistentry>
 320         <term><option>-N</option></term>
 321         <listitem>
 322           <para>
 323   Adds a doctype and notation declarations to canonical XML output.
 324   This matches the example output used by the formal XML test cases.
 325   Requires <option>-d</option> to specify an output file.
 326           </para>
 327         </listitem>
 328       </varlistentry>
 329
 330       <varlistentry>
 331         <term><option>-p</option></term>
 332         <listitem>
 333                 <para>
 334     Tells <command>&dhpackage;</command> to process external DTDs and parameter
 335     entities.
 336          </para>
 337          <para>
 338    Normally <command>&dhpackage;</command> never parses parameter
 339    entities.  <option>-p</option> tells it to always parse them.
 340    <option>-p</option> implies <option>-x</option>.
 341            </para>
 342         </listitem>
 343       </varlistentry>
 344
 345       <varlistentry>
 346         <term><option>-q</option></term>
 347         <listitem>
 348           <para>
 349             Disable reparse deferral, and allow quadratic parse runtime
 350             on large tokens (default: reparse deferral enabled).
 351           </para>
 352         </listitem>
 353       </varlistentry>
 354
 355       <varlistentry>
 356         <term><option>-r</option></term>
 357         <listitem>
 358                 <para>
 359    Normally <command>&dhpackage;</command> memory-maps the XML file
 360    before parsing; this can result in faster parsing on many
 361    platforms.
 362    <option>-r</option> turns off memory-mapping and uses normal file
 363    IO calls instead.
 364    Of course, memory-mapping is automatically turned off
 365    when reading from standard input.
 366            </para>
 367                 <para>
 368    Use of memory-mapping can cause some platforms to report
 369    substantially higher memory usage for
 370    <command>&dhpackage;</command>, but this appears to be a matter of
 371    the operating system reporting memory in a strange way; there is
 372    not a leak in <command>&dhpackage;</command>.
 373            </para>
 374         </listitem>
 375       </varlistentry>
 376
 377       <varlistentry>
 378         <term><option>-s</option></term>
 379         <listitem>
 380                 <para>
 381   Prints an error if the document is not standalone.
 382   A document is standalone if it has no external subset and no
 383   references to parameter entities.
 384            </para>
 385         </listitem>
 386       </varlistentry>
 387
 388       <varlistentry>
 389         <term><option>-t</option></term>
 390         <listitem>
 391                 <para>
 392   Turns on timings.  This tells Expat to parse the entire file,
 393   but not perform any processing.
 394   This gives a fairly accurate idea of the raw speed of Expat itself
 395   without client overhead.
 396   <option>-t</option> turns off most of the output options
 397   (<option>-d</option>, <option>-m</option>, <option>-c</option>, ...).
 398            </para>
 399         </listitem>
 400       </varlistentry>
 401
 402       <varlistentry>
 403         <term><option>-v</option></term>
 404         <term><option>--version</option></term>
 405         <listitem>
 406                 <para>
 407   Prints the version of the Expat library being used, including some
 408   information on the compile-time configuration of the library, and
 409   then exits.
 410            </para>
 411         </listitem>
 412       </varlistentry>
 413
 414       <varlistentry>
 415         <term><option>-w</option></term>
 416         <listitem>
 417                 <para>
 418   Enables support for Windows code pages.
 419   Normally, <command>&dhpackage;</command> will throw an error if it
 420   runs across an encoding that it is not equipped to handle itself.  With
 421   <option>-w</option>, <command>&dhpackage;</command> will try to use a Windows code
 422   page.  See also <option>-e</option>.
 423            </para>
 424         </listitem>
 425       </varlistentry>
 426
 427       <varlistentry>
 428         <term><option>-x</option></term>
 429         <listitem>
 430                 <para>
 431   Turns on parsing external entities.
 432   </para>
 433 <para>
 434   Non-validating parsers are not required to resolve external
 435   entities, or even expand entities at all.
 436   Expat always expands internal entities (?),
 437   but external entity parsing must be enabled explicitly.
 438   </para>
 439   <para>
 440   External entities are simply entities that obtain their
 441   data from outside the XML file currently being parsed.
 442   </para>
 443   <para>
 444   This is an example of an internal entity:
 445 <literallayout>
 446 &lt;!ENTITY vers '1.0.2'&gt;
 447 </literallayout>
 448   </para>
 449   <para>
 450   And here are some examples of external entities:
 451
 452 <literallayout>
 453 &lt;!ENTITY header SYSTEM "header-&amp;vers;.xml"&gt;  (parsed)
 454 &lt;!ENTITY logo SYSTEM "logo.png" PNG&gt;         (unparsed)
 455 </literallayout>
 456
 457            </para>
 458         </listitem>
 459       </varlistentry>
 460
 461       <varlistentry>
 462         <term><option>--</option></term>
 463         <listitem>
 464                 <para>
 465     (Two hyphens.)
 466     Terminates the list of options.  This is only needed if a filename
 467     starts with a hyphen.  For example:
 468            </para>
 469 <literallayout>
 470 &dhpackage; -- -myfile.xml
 471 </literallayout>
 472                 <para>
 473     will run <command>&dhpackage;</command> on the file
 474     <filename>-myfile.xml</filename>.
 475            </para>
 476         </listitem>
 477       </varlistentry>
 478     </variablelist>
 479
 480         <para>
 481     Older versions of <command>&dhpackage;</command> do not support
 482     reading from standard input.
 483         </para>
 484   </refsect1>
 485
 486   <refsect1>
 487   <title>OUTPUT</title>
 488     <para>
 489         <command>&dhpackage;</command> outputs nothing for files which are problem-free.
 490         If any input file is not well-formed, or if the output for any
 491         input file cannot be opened, <command>&dhpackage;</command> prints a single
 492         line describing the problem to standard output.
 493     </para>
 494     <para>
 495         If the <option>-k</option> option is not provided, <command>&dhpackage;</command>
 496         halts upon encountering a well-formedness or output-file error.
 497         If <option>-k</option> is provided, <command>&dhpackage;</command> continues
 498         processing the remaining input files, describing problems found with any of them.
 499     </para>
 500   </refsect1>
 501
 502   <refsect1>
 503   <title>EXIT STATUS</title>
 504     <para>For options <option>-v</option>|<option>--version</option> or <option>-h</option>|<option>--help</option>, <command>&dhpackage;</command> always exits with status code 0.  For other cases, the following exit status codes are returned:
 505     <variablelist>
 506       <varlistentry>
 507         <term><option>0</option></term>
 508         <listitem><para>The input files are well-formed and the output (if requested) was written successfully.</para>
 509         </listitem>
 510       </varlistentry>
 511       <varlistentry>
 512         <term><option>1</option></term>
 513         <listitem><para>An internal error occurred.</para>
 514         </listitem>
 515       </varlistentry>
 516       <varlistentry>
 517         <term><option>2</option></term>
 518         <listitem><para>One or more input files were not well-formed or could not be parsed.</para>
 519         </listitem>
 520       </varlistentry>
 521       <varlistentry>
 522         <term><option>3</option></term>
 523         <listitem><para>If using the <option>-d</option> option, an error occurred opening an output file.</para>
 524         </listitem>
 525       </varlistentry>
 526       <varlistentry>
 527         <term><option>4</option></term>
 528         <listitem><para>There was a command-line argument error in how <command>&dhpackage;</command> was invoked.</para>
 529         </listitem>
 530       </varlistentry>
 531     </variablelist>
 532         </para>
 533   </refsect1>
 534
 535
 536   <refsect1>
 537     <title>BUGS</title>
 538         <para>
 539         The errors should go to standard error, not standard output.
 540         </para>
 541         <para>
 542         There should be a way to get <option>-d</option> to send its
 543         output to standard output rather than forcing the user to send
 544         it to a file.
 545         </para>
 546         <para>
 547         I have no idea why anyone would want to use the
 548         <option>-d</option>, <option>-c</option>, and
 549         <option>-m</option> options.  If someone could explain it to
 550         me, I'd like to add this information to this manpage.
 551         </para>
 552   </refsect1>
 553
 554   <refsect1>
 555     <title>SEE ALSO</title>
 556         <para>
 557
 558 <literallayout>
 559 The Expat home page:                            https://libexpat.github.io/
 560 The W3 XML 1.0 specification (fourth edition):  https://www.w3.org/TR/2006/REC-xml-20060816/
 561 Billion laughs attack:                          https://en.wikipedia.org/wiki/Billion_laughs_attack
 562 </literallayout>
 563
 564         </para>
 565   </refsect1>
 566
 567   <refsect1>
 568     <title>AUTHOR</title>
 569     <para>
 570       This manual page was originally written by &dhusername; &dhemail;
 571       in December 2001 for
 572       the &debian; system (but may be used by others).  Permission is
 573       granted to copy, distribute and/or modify this document under
 574       the terms of the <acronym>GNU</acronym> Free Documentation
 575       License, Version 1.1.
 576         </para>
 577   </refsect1>
 578 </refentry>