| <!-- |
| __ __ _ |
| ___\ \/ /_ __ __ _| |_ |
| / _ \\ /| '_ \ / _` | __| |
| | __// \| |_) | (_| | |_ |
| \___/_/\_\ .__/ \__,_|\__| |
| |_| XML parser |
| |
| Copyright (c) 2001 Scott Bronson <bronson@rinspin.com> |
| Copyright (c) 2002-2003 Fred L. Drake, Jr. <fdrake@users.sourceforge.net> |
| Copyright (c) 2009 Karl Waclawek <karl@waclawek.net> |
| Copyright (c) 2016-2021 Sebastian Pipping <sebastian@pipping.org> |
| Copyright (c) 2016 Ardo van Rangelrooij <ardo@debian.org> |
| Copyright (c) 2017 Rhodri James <rhodri@wildebeest.org.uk> |
| Copyright (c) 2020 Joe Orton <jorton@redhat.com> |
| Copyright (c) 2021 Tim Bray <tbray@textuality.com> |
| Unlike most of Expat, |
| this file is copyrighted under the GNU Free Documentation License 1.1. |
| --> |
| <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
| "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ |
| <!ENTITY dhfirstname "<firstname>Scott</firstname>"> |
| <!ENTITY dhsurname "<surname>Bronson</surname>"> |
| <!-- Please adjust the date whenever revising the manpage. --> |
| <!ENTITY dhdate "<date>December 19, 2021</date>"> |
| <!ENTITY dhsection "<manvolnum>1</manvolnum>"> |
| <!ENTITY dhemail "<email>bronson@rinspin.com</email>"> |
| <!ENTITY dhusername "Scott Bronson"> |
| <!ENTITY dhucpackage "<refentrytitle>XMLWF</refentrytitle>"> |
| <!ENTITY dhpackage "xmlwf"> |
| |
| <!ENTITY debian "<productname>Debian GNU/Linux</productname>"> |
| <!ENTITY gnu "<acronym>GNU</acronym>"> |
| ]> |
| |
| <refentry> |
| <refentryinfo> |
| <address> |
| &dhemail; |
| </address> |
| <author> |
| &dhfirstname; |
| &dhsurname; |
| </author> |
| <copyright> |
| <year>2001</year> |
| <holder>&dhusername;</holder> |
| </copyright> |
| &dhdate; |
| </refentryinfo> |
| <refmeta> |
| &dhucpackage; |
| |
| &dhsection; |
| </refmeta> |
| <refnamediv> |
| <refname>&dhpackage;</refname> |
| |
| <refpurpose>Determines if an XML document is well-formed</refpurpose> |
| </refnamediv> |
| <refsynopsisdiv> |
| <cmdsynopsis> |
| <command>&dhpackage;</command> |
| <arg><replaceable>OPTIONS</replaceable></arg> |
| <arg><replaceable>FILE</replaceable> ...</arg> |
| </cmdsynopsis> |
| <cmdsynopsis> |
| <command>&dhpackage;</command> |
| <arg choice="plain"><option>-h</option></arg> |
| </cmdsynopsis> |
| <cmdsynopsis> |
| <command>&dhpackage;</command> |
| <arg choice="plain"><option>-v</option></arg> |
| </cmdsynopsis> |
| </refsynopsisdiv> |
| |
| <refsect1> |
| <title>DESCRIPTION</title> |
| |
| <para> |
| <command>&dhpackage;</command> uses the Expat library to |
| determine if an XML document is well-formed. It is |
| non-validating. |
| </para> |
| |
| <para> |
| If you do not specify any files on the command-line, and you |
| have a recent version of <command>&dhpackage;</command>, the |
| input file will be read from standard input. |
| </para> |
| |
| </refsect1> |
| |
| <refsect1> |
| <title>WELL-FORMED DOCUMENTS</title> |
| |
| <para> |
| A well-formed document must adhere to the |
| following rules: |
| </para> |
| |
| <itemizedlist> |
| <listitem><para> |
| The file begins with an XML declaration. For instance, |
| <literal><?xml version="1.0" standalone="yes"?></literal>. |
| <emphasis>NOTE</emphasis>: |
| <command>&dhpackage;</command> does not currently |
| check for a valid XML declaration. |
| </para></listitem> |
| <listitem><para> |
| Every start tag is either empty (<tag/>) |
| or has a corresponding end tag. |
| </para></listitem> |
| <listitem><para> |
| There is exactly one root element. This element must contain |
| all other elements in the document. Only comments, white |
| space, and processing instructions may come after the close |
| of the root element. |
| </para></listitem> |
| <listitem><para> |
| All elements nest properly. |
| </para></listitem> |
| <listitem><para> |
| All attribute values are enclosed in quotes (either single |
| or double). |
| </para></listitem> |
| </itemizedlist> |
| |
| <para> |
| If the document has a DTD, and it strictly complies with that |
| DTD, then the document is also considered <emphasis>valid</emphasis>. |
| <command>&dhpackage;</command> is a non-validating parser -- |
| it does not check the DTD. However, it does support |
| external entities (see the <option>-x</option> option). |
| </para> |
| </refsect1> |
| |
| <refsect1> |
| <title>OPTIONS</title> |
| |
| <para> |
| When an option includes an argument, you may specify the argument either |
| separately ("<option>-d</option> <replaceable>output</replaceable>") or concatenated with the |
| option ("<option>-d</option><replaceable>output</replaceable>"). <command>&dhpackage;</command> |
| supports both. |
| </para> |
| |
| <variablelist> |
| |
| <varlistentry> |
| <term><option>-a</option> <replaceable>factor</replaceable></term> |
| <listitem> |
| <para> |
| Sets the maximum tolerated amplification factor |
| for protection against billion laughs attacks (default: 100.0). |
| The amplification factor is calculated as .. |
| </para> |
| <literallayout> |
| amplification := (direct + indirect) / direct |
| </literallayout> |
| <para> |
| .. while parsing, whereas |
| <direct> is the number of bytes read |
| from the primary document in parsing and |
| <indirect> is the number of bytes |
| added by expanding entities and reading of external DTD files, |
| combined. |
| </para> |
| <para> |
| <emphasis>NOTE</emphasis>: |
| If you ever need to increase this value for non-attack payload, |
| please file a bug report. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-b</option> <replaceable>bytes</replaceable></term> |
| <listitem> |
| <para> |
| Sets the number of output bytes (including amplification) |
| needed to activate protection against billion laughs attacks |
| (default: 8 MiB). |
| This can be thought of as an "activation threshold". |
| </para> |
| <para> |
| <emphasis>NOTE</emphasis>: |
| If you ever need to increase this value for non-attack payload, |
| please file a bug report. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-c</option></term> |
| <listitem> |
| <para> |
| If the input file is well-formed and <command>&dhpackage;</command> |
| doesn't encounter any errors, the input file is simply copied to |
| the output directory unchanged. |
| This implies no namespaces (turns off <option>-n</option>) and |
| requires <option>-d</option> to specify an output directory. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-d</option> <replaceable>output-dir</replaceable></term> |
| <listitem> |
| <para> |
| Specifies a directory to contain transformed |
| representations of the input files. |
| By default, <option>-d</option> outputs a canonical representation |
| (described below). |
| You can select different output formats using <option>-c</option>, |
| <option>-m</option> and <option>-N</option>. |
| </para> |
| <para> |
| The output filenames will |
| be exactly the same as the input filenames or "STDIN" if the input is |
| coming from standard input. Therefore, you must be careful that the |
| output file does not go into the same directory as the input |
| file. Otherwise, <command>&dhpackage;</command> will delete the |
| input file before it generates the output file (just like running |
| <literal>cat < file > file</literal> in most shells). |
| </para> |
| <para> |
| Two structurally equivalent XML documents have a byte-for-byte |
| identical canonical XML representation. |
| Note that ignorable white space is considered significant and |
| is treated equivalently to data. |
| More on canonical XML can be found at |
| http://www.jclark.com/xml/canonxml.html . |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-e</option> <replaceable>encoding</replaceable></term> |
| <listitem> |
| <para> |
| Specifies the character encoding for the document, overriding |
| any document encoding declaration. <command>&dhpackage;</command> |
| supports four built-in encodings: |
| <literal>US-ASCII</literal>, |
| <literal>UTF-8</literal>, |
| <literal>UTF-16</literal>, and |
| <literal>ISO-8859-1</literal>. |
| Also see the <option>-w</option> option. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-k</option></term> |
| <listitem> |
| <para> |
| When processing multiple files, <command>&dhpackage;</command> |
| by default halts after the the first file with an error. |
| This tells <command>&dhpackage;</command> to report the error |
| but to keep processing. |
| This can be useful, for example, when testing a filter that converts |
| many files to XML and you want to quickly find out which conversions |
| failed. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-m</option></term> |
| <listitem> |
| <para> |
| Outputs some strange sort of XML file that completely |
| describes the input file, including character positions. |
| Requires <option>-d</option> to specify an output file. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-n</option></term> |
| <listitem> |
| <para> |
| Turns on namespace processing. (describe namespaces) |
| <option>-c</option> disables namespaces. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-N</option></term> |
| <listitem> |
| <para> |
| Adds a doctype and notation declarations to canonical XML output. |
| This matches the example output used by the formal XML test cases. |
| Requires <option>-d</option> to specify an output file. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-p</option></term> |
| <listitem> |
| <para> |
| Tells <command>&dhpackage;</command> to process external DTDs and parameter |
| entities. |
| </para> |
| <para> |
| Normally <command>&dhpackage;</command> never parses parameter |
| entities. <option>-p</option> tells it to always parse them. |
| <option>-p</option> implies <option>-x</option>. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-r</option></term> |
| <listitem> |
| <para> |
| Normally <command>&dhpackage;</command> memory-maps the XML file |
| before parsing; this can result in faster parsing on many |
| platforms. |
| <option>-r</option> turns off memory-mapping and uses normal file |
| IO calls instead. |
| Of course, memory-mapping is automatically turned off |
| when reading from standard input. |
| </para> |
| <para> |
| Use of memory-mapping can cause some platforms to report |
| substantially higher memory usage for |
| <command>&dhpackage;</command>, but this appears to be a matter of |
| the operating system reporting memory in a strange way; there is |
| not a leak in <command>&dhpackage;</command>. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-s</option></term> |
| <listitem> |
| <para> |
| Prints an error if the document is not standalone. |
| A document is standalone if it has no external subset and no |
| references to parameter entities. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-t</option></term> |
| <listitem> |
| <para> |
| Turns on timings. This tells Expat to parse the entire file, |
| but not perform any processing. |
| This gives a fairly accurate idea of the raw speed of Expat itself |
| without client overhead. |
| <option>-t</option> turns off most of the output options |
| (<option>-d</option>, <option>-m</option>, <option>-c</option>, ...). |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-v</option></term> |
| <listitem> |
| <para> |
| Prints the version of the Expat library being used, including some |
| information on the compile-time configuration of the library, and |
| then exits. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-w</option></term> |
| <listitem> |
| <para> |
| Enables support for Windows code pages. |
| Normally, <command>&dhpackage;</command> will throw an error if it |
| runs across an encoding that it is not equipped to handle itself. With |
| <option>-w</option>, <command>&dhpackage;</command> will try to use a Windows code |
| page. See also <option>-e</option>. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-x</option></term> |
| <listitem> |
| <para> |
| Turns on parsing external entities. |
| </para> |
| <para> |
| Non-validating parsers are not required to resolve external |
| entities, or even expand entities at all. |
| Expat always expands internal entities (?), |
| but external entity parsing must be enabled explicitly. |
| </para> |
| <para> |
| External entities are simply entities that obtain their |
| data from outside the XML file currently being parsed. |
| </para> |
| <para> |
| This is an example of an internal entity: |
| <literallayout> |
| <!ENTITY vers '1.0.2'> |
| </literallayout> |
| </para> |
| <para> |
| And here are some examples of external entities: |
| |
| <literallayout> |
| <!ENTITY header SYSTEM "header-&vers;.xml"> (parsed) |
| <!ENTITY logo SYSTEM "logo.png" PNG> (unparsed) |
| </literallayout> |
| |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--</option></term> |
| <listitem> |
| <para> |
| (Two hyphens.) |
| Terminates the list of options. This is only needed if a filename |
| starts with a hyphen. For example: |
| </para> |
| <literallayout> |
| &dhpackage; -- -myfile.xml |
| </literallayout> |
| <para> |
| will run <command>&dhpackage;</command> on the file |
| <filename>-myfile.xml</filename>. |
| </para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| |
| <para> |
| Older versions of <command>&dhpackage;</command> do not support |
| reading from standard input. |
| </para> |
| </refsect1> |
| |
| <refsect1> |
| <title>OUTPUT</title> |
| <para> |
| <command>&dhpackage;</command> outputs nothing for files which are problem-free. |
| If any input file is not well-formed, or if the output for any |
| input file cannot be opened, <command>&dhpackage;</command> prints a single |
| line describing the problem to standard output. |
| </para> |
| <para> |
| If the <option>-k</option> option is not provided, <command>&dhpackage;</command> |
| halts upon encountering a well-formedness or output-file error. |
| If <option>-k</option> is provided, <command>&dhpackage;</command> continues |
| processing the remaining input files, describing problems found with any of them. |
| </para> |
| </refsect1> |
| |
| <refsect1> |
| <title>EXIT STATUS</title> |
| <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: |
| <variablelist> |
| <varlistentry> |
| <term><option>0</option></term> |
| <listitem><para>The input files are well-formed and the output (if requested) was written successfully.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><option>1</option></term> |
| <listitem><para>An internal error occurred.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><option>2</option></term> |
| <listitem><para>One or more input files were not well-formed or could not be parsed.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><option>3</option></term> |
| <listitem><para>If using the <option>-d</option> option, an error occurred opening an output file.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><option>4</option></term> |
| <listitem><para>There was a command-line argument error in how <command>&dhpackage;</command> was invoked.</para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| </para> |
| </refsect1> |
| |
| |
| <refsect1> |
| <title>BUGS</title> |
| <para> |
| The errors should go to standard error, not standard output. |
| </para> |
| <para> |
| There should be a way to get <option>-d</option> to send its |
| output to standard output rather than forcing the user to send |
| it to a file. |
| </para> |
| <para> |
| I have no idea why anyone would want to use the |
| <option>-d</option>, <option>-c</option>, and |
| <option>-m</option> options. If someone could explain it to |
| me, I'd like to add this information to this manpage. |
| </para> |
| </refsect1> |
| |
| <refsect1> |
| <title>SEE ALSO</title> |
| <para> |
| |
| <literallayout> |
| The Expat home page: https://libexpat.github.io/ |
| The W3 XML 1.0 specification (fourth edition): https://www.w3.org/TR/2006/REC-xml-20060816/ |
| Billion laughs attack: https://en.wikipedia.org/wiki/Billion_laughs_attack |
| </literallayout> |
| |
| </para> |
| </refsect1> |
| |
| <refsect1> |
| <title>AUTHOR</title> |
| <para> |
| This manual page was originally written by &dhusername; &dhemail; |
| in December 2001 for |
| the &debian; system (but may be used by others). Permission is |
| granted to copy, distribute and/or modify this document under |
| the terms of the <acronym>GNU</acronym> Free Documentation |
| License, Version 1.1. |
| </para> |
| </refsect1> |
| </refentry> |
