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>March 4, 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><?xml version="1.0" standalone="yes"?></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 (<tag/>) 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> 142When an option includes an argument, you may specify the argument either 143separately ("<option>-d</option> <replaceable>output</replaceable>") or concatenated with the 144option ("<option>-d</option><replaceable>output</replaceable>"). <command>&dhpackage;</command> 145supports 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 <direct> is the number of bytes read 164 from the primary document in parsing and 165 <indirect> 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 "activation threshold". 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 < file > 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<!ENTITY vers '1.0.2'> 407</literallayout> 408 </para> 409 <para> 410 And here are some examples of external entities: 411 412<literallayout> 413<!ENTITY header SYSTEM "header-&vers;.xml"> (parsed) 414<!ENTITY logo SYSTEM "logo.png" PNG> (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> 519The Expat home page: https://libexpat.github.io/ 520The W3 XML 1.0 specification (fourth edition): https://www.w3.org/TR/2006/REC-xml-20060816/ 521Billion 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> 539
