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