jpayne@68: '\" -*- coding: us-ascii -*- jpayne@68: .if \n(.g .ds T< \\FC jpayne@68: .if \n(.g .ds T> \\F[\n[.fam]] jpayne@68: .de URL jpayne@68: \\$2 \(la\\$1\(ra\\$3 jpayne@68: .. jpayne@68: .if \n(.g .mso www.tmac jpayne@68: .TH XMLWF 1 "November 6, 2024" "" "" jpayne@68: .SH NAME jpayne@68: xmlwf \- Determines if an XML document is well-formed jpayne@68: .SH SYNOPSIS jpayne@68: 'nh jpayne@68: .fi jpayne@68: .ad l jpayne@68: \fBxmlwf\fR \kx jpayne@68: .if (\nx>(\n(.l/2)) .nr x (\n(.l/5) jpayne@68: 'in \n(.iu+\nxu jpayne@68: [\fIOPTIONS\fR] [\fIFILE\fR ...] jpayne@68: 'in \n(.iu-\nxu jpayne@68: .ad b jpayne@68: 'hy jpayne@68: 'nh jpayne@68: .fi jpayne@68: .ad l jpayne@68: \fBxmlwf\fR \kx jpayne@68: .if (\nx>(\n(.l/2)) .nr x (\n(.l/5) jpayne@68: 'in \n(.iu+\nxu jpayne@68: \fB-h\fR | \fB--help\fR jpayne@68: 'in \n(.iu-\nxu jpayne@68: .ad b jpayne@68: 'hy jpayne@68: 'nh jpayne@68: .fi jpayne@68: .ad l jpayne@68: \fBxmlwf\fR \kx jpayne@68: .if (\nx>(\n(.l/2)) .nr x (\n(.l/5) jpayne@68: 'in \n(.iu+\nxu jpayne@68: \fB-v\fR | \fB--version\fR jpayne@68: 'in \n(.iu-\nxu jpayne@68: .ad b jpayne@68: 'hy jpayne@68: .SH DESCRIPTION jpayne@68: \fBxmlwf\fR uses the Expat library to jpayne@68: determine if an XML document is well-formed. It is jpayne@68: non-validating. jpayne@68: .PP jpayne@68: If you do not specify any files on the command-line, and you jpayne@68: have a recent version of \fBxmlwf\fR, the jpayne@68: input file will be read from standard input. jpayne@68: .SH "WELL-FORMED DOCUMENTS" jpayne@68: A well-formed document must adhere to the jpayne@68: following rules: jpayne@68: .TP 0.2i jpayne@68: \(bu jpayne@68: The file begins with an XML declaration. For instance, jpayne@68: \*(T<\*(T>. jpayne@68: \fINOTE\fR: jpayne@68: \fBxmlwf\fR does not currently jpayne@68: check for a valid XML declaration. jpayne@68: .TP 0.2i jpayne@68: \(bu jpayne@68: Every start tag is either empty () jpayne@68: or has a corresponding end tag. jpayne@68: .TP 0.2i jpayne@68: \(bu jpayne@68: There is exactly one root element. This element must contain jpayne@68: all other elements in the document. Only comments, white jpayne@68: space, and processing instructions may come after the close jpayne@68: of the root element. jpayne@68: .TP 0.2i jpayne@68: \(bu jpayne@68: All elements nest properly. jpayne@68: .TP 0.2i jpayne@68: \(bu jpayne@68: All attribute values are enclosed in quotes (either single jpayne@68: or double). jpayne@68: .PP jpayne@68: If the document has a DTD, and it strictly complies with that jpayne@68: DTD, then the document is also considered \fIvalid\fR. jpayne@68: \fBxmlwf\fR is a non-validating parser -- jpayne@68: it does not check the DTD. However, it does support jpayne@68: external entities (see the \*(T<\fB\-x\fR\*(T> option). jpayne@68: .SH OPTIONS jpayne@68: When an option includes an argument, you may specify the argument either jpayne@68: separately ("\*(T<\fB\-d\fR\*(T> \fIoutput\fR") or concatenated with the jpayne@68: option ("\*(T<\fB\-d\fR\*(T>\fIoutput\fR"). \fBxmlwf\fR jpayne@68: supports both. jpayne@68: .TP jpayne@68: \*(T<\fB\-a\fR\*(T> \fIfactor\fR jpayne@68: Sets the maximum tolerated amplification factor jpayne@68: for protection against billion laughs attacks (default: 100.0). jpayne@68: The amplification factor is calculated as .. jpayne@68: jpayne@68: .nf jpayne@68: jpayne@68: amplification := (direct + indirect) / direct jpayne@68: jpayne@68: .fi jpayne@68: jpayne@68: \&.. while parsing, whereas jpayne@68: is the number of bytes read jpayne@68: from the primary document in parsing and jpayne@68: is the number of bytes jpayne@68: added by expanding entities and reading of external DTD files, jpayne@68: combined. jpayne@68: jpayne@68: \fINOTE\fR: jpayne@68: If you ever need to increase this value for non-attack payload, jpayne@68: please file a bug report. jpayne@68: .TP jpayne@68: \*(T<\fB\-b\fR\*(T> \fIbytes\fR jpayne@68: Sets the number of output bytes (including amplification) jpayne@68: needed to activate protection against billion laughs attacks jpayne@68: (default: 8 MiB). jpayne@68: This can be thought of as an "activation threshold". jpayne@68: jpayne@68: \fINOTE\fR: jpayne@68: If you ever need to increase this value for non-attack payload, jpayne@68: please file a bug report. jpayne@68: .TP jpayne@68: \*(T<\fB\-c\fR\*(T> jpayne@68: If the input file is well-formed and \fBxmlwf\fR jpayne@68: doesn't encounter any errors, the input file is simply copied to jpayne@68: the output directory unchanged. jpayne@68: This implies no namespaces (turns off \*(T<\fB\-n\fR\*(T>) and jpayne@68: requires \*(T<\fB\-d\fR\*(T> to specify an output directory. jpayne@68: .TP jpayne@68: \*(T<\fB\-d\fR\*(T> \fIoutput-dir\fR jpayne@68: Specifies a directory to contain transformed jpayne@68: representations of the input files. jpayne@68: By default, \*(T<\fB\-d\fR\*(T> outputs a canonical representation jpayne@68: (described below). jpayne@68: You can select different output formats using \*(T<\fB\-c\fR\*(T>, jpayne@68: \*(T<\fB\-m\fR\*(T> and \*(T<\fB\-N\fR\*(T>. jpayne@68: jpayne@68: The output filenames will jpayne@68: be exactly the same as the input filenames or "STDIN" if the input is jpayne@68: coming from standard input. Therefore, you must be careful that the jpayne@68: output file does not go into the same directory as the input jpayne@68: file. Otherwise, \fBxmlwf\fR will delete the jpayne@68: input file before it generates the output file (just like running jpayne@68: \*(T file\*(T> in most shells). jpayne@68: jpayne@68: Two structurally equivalent XML documents have a byte-for-byte jpayne@68: identical canonical XML representation. jpayne@68: Note that ignorable white space is considered significant and jpayne@68: is treated equivalently to data. jpayne@68: More on canonical XML can be found at jpayne@68: http://www.jclark.com/xml/canonxml.html . jpayne@68: .TP jpayne@68: \*(T<\fB\-e\fR\*(T> \fIencoding\fR jpayne@68: Specifies the character encoding for the document, overriding jpayne@68: any document encoding declaration. \fBxmlwf\fR jpayne@68: supports four built-in encodings: jpayne@68: \*(T, jpayne@68: \*(T, jpayne@68: \*(T, and jpayne@68: \*(T. jpayne@68: Also see the \*(T<\fB\-w\fR\*(T> option. jpayne@68: .TP jpayne@68: \*(T<\fB\-g\fR\*(T> \fIbytes\fR jpayne@68: Sets the buffer size to request per call pair to jpayne@68: \*(T<\fBXML_GetBuffer\fR\*(T> and \*(T<\fBread\fR\*(T> jpayne@68: (default: 8 KiB). jpayne@68: .TP jpayne@68: \*(T<\fB\-h\fR\*(T>, \*(T<\fB\-\-help\fR\*(T> jpayne@68: Prints short usage information on command \fBxmlwf\fR, jpayne@68: and then exits. jpayne@68: Similar to this man page but more concise. jpayne@68: .TP jpayne@68: \*(T<\fB\-k\fR\*(T> jpayne@68: When processing multiple files, \fBxmlwf\fR jpayne@68: by default halts after the the first file with an error. jpayne@68: This tells \fBxmlwf\fR to report the error jpayne@68: but to keep processing. jpayne@68: This can be useful, for example, when testing a filter that converts jpayne@68: many files to XML and you want to quickly find out which conversions jpayne@68: failed. jpayne@68: .TP jpayne@68: \*(T<\fB\-m\fR\*(T> jpayne@68: Outputs some strange sort of XML file that completely jpayne@68: describes the input file, including character positions. jpayne@68: Requires \*(T<\fB\-d\fR\*(T> to specify an output file. jpayne@68: .TP jpayne@68: \*(T<\fB\-n\fR\*(T> jpayne@68: Turns on namespace processing. (describe namespaces) jpayne@68: \*(T<\fB\-c\fR\*(T> disables namespaces. jpayne@68: .TP jpayne@68: \*(T<\fB\-N\fR\*(T> jpayne@68: Adds a doctype and notation declarations to canonical XML output. jpayne@68: This matches the example output used by the formal XML test cases. jpayne@68: Requires \*(T<\fB\-d\fR\*(T> to specify an output file. jpayne@68: .TP jpayne@68: \*(T<\fB\-p\fR\*(T> jpayne@68: Tells \fBxmlwf\fR to process external DTDs and parameter jpayne@68: entities. jpayne@68: jpayne@68: Normally \fBxmlwf\fR never parses parameter jpayne@68: entities. \*(T<\fB\-p\fR\*(T> tells it to always parse them. jpayne@68: \*(T<\fB\-p\fR\*(T> implies \*(T<\fB\-x\fR\*(T>. jpayne@68: .TP jpayne@68: \*(T<\fB\-q\fR\*(T> jpayne@68: Disable reparse deferral, and allow quadratic parse runtime jpayne@68: on large tokens (default: reparse deferral enabled). jpayne@68: .TP jpayne@68: \*(T<\fB\-r\fR\*(T> jpayne@68: Normally \fBxmlwf\fR memory-maps the XML file jpayne@68: before parsing; this can result in faster parsing on many jpayne@68: platforms. jpayne@68: \*(T<\fB\-r\fR\*(T> turns off memory-mapping and uses normal file jpayne@68: IO calls instead. jpayne@68: Of course, memory-mapping is automatically turned off jpayne@68: when reading from standard input. jpayne@68: jpayne@68: Use of memory-mapping can cause some platforms to report jpayne@68: substantially higher memory usage for jpayne@68: \fBxmlwf\fR, but this appears to be a matter of jpayne@68: the operating system reporting memory in a strange way; there is jpayne@68: not a leak in \fBxmlwf\fR. jpayne@68: .TP jpayne@68: \*(T<\fB\-s\fR\*(T> jpayne@68: Prints an error if the document is not standalone. jpayne@68: A document is standalone if it has no external subset and no jpayne@68: references to parameter entities. jpayne@68: .TP jpayne@68: \*(T<\fB\-t\fR\*(T> jpayne@68: Turns on timings. This tells Expat to parse the entire file, jpayne@68: but not perform any processing. jpayne@68: This gives a fairly accurate idea of the raw speed of Expat itself jpayne@68: without client overhead. jpayne@68: \*(T<\fB\-t\fR\*(T> turns off most of the output options jpayne@68: (\*(T<\fB\-d\fR\*(T>, \*(T<\fB\-m\fR\*(T>, \*(T<\fB\-c\fR\*(T>, ...). jpayne@68: .TP jpayne@68: \*(T<\fB\-v\fR\*(T>, \*(T<\fB\-\-version\fR\*(T> jpayne@68: Prints the version of the Expat library being used, including some jpayne@68: information on the compile-time configuration of the library, and jpayne@68: then exits. jpayne@68: .TP jpayne@68: \*(T<\fB\-w\fR\*(T> jpayne@68: Enables support for Windows code pages. jpayne@68: Normally, \fBxmlwf\fR will throw an error if it jpayne@68: runs across an encoding that it is not equipped to handle itself. With jpayne@68: \*(T<\fB\-w\fR\*(T>, \fBxmlwf\fR will try to use a Windows code jpayne@68: page. See also \*(T<\fB\-e\fR\*(T>. jpayne@68: .TP jpayne@68: \*(T<\fB\-x\fR\*(T> jpayne@68: Turns on parsing external entities. jpayne@68: jpayne@68: Non-validating parsers are not required to resolve external jpayne@68: entities, or even expand entities at all. jpayne@68: Expat always expands internal entities (?), jpayne@68: but external entity parsing must be enabled explicitly. jpayne@68: jpayne@68: External entities are simply entities that obtain their jpayne@68: data from outside the XML file currently being parsed. jpayne@68: jpayne@68: This is an example of an internal entity: jpayne@68: jpayne@68: .nf jpayne@68: jpayne@68: jpayne@68: .fi jpayne@68: jpayne@68: And here are some examples of external entities: jpayne@68: jpayne@68: .nf jpayne@68: jpayne@68: (parsed) jpayne@68: (unparsed) jpayne@68: .fi jpayne@68: .TP jpayne@68: \*(T<\fB\-\-\fR\*(T> jpayne@68: (Two hyphens.) jpayne@68: Terminates the list of options. This is only needed if a filename jpayne@68: starts with a hyphen. For example: jpayne@68: jpayne@68: .nf jpayne@68: jpayne@68: xmlwf \-\- \-myfile.xml jpayne@68: .fi jpayne@68: jpayne@68: will run \fBxmlwf\fR on the file jpayne@68: \*(T<\fI\-myfile.xml\fR\*(T>. jpayne@68: .PP jpayne@68: Older versions of \fBxmlwf\fR do not support jpayne@68: reading from standard input. jpayne@68: .SH OUTPUT jpayne@68: \fBxmlwf\fR outputs nothing for files which are problem-free. jpayne@68: If any input file is not well-formed, or if the output for any jpayne@68: input file cannot be opened, \fBxmlwf\fR prints a single jpayne@68: line describing the problem to standard output. jpayne@68: .PP jpayne@68: If the \*(T<\fB\-k\fR\*(T> option is not provided, \fBxmlwf\fR jpayne@68: halts upon encountering a well-formedness or output-file error. jpayne@68: If \*(T<\fB\-k\fR\*(T> is provided, \fBxmlwf\fR continues jpayne@68: processing the remaining input files, describing problems found with any of them. jpayne@68: .SH "EXIT STATUS" jpayne@68: For options \*(T<\fB\-v\fR\*(T>|\*(T<\fB\-\-version\fR\*(T> or \*(T<\fB\-h\fR\*(T>|\*(T<\fB\-\-help\fR\*(T>, \fBxmlwf\fR always exits with status code 0. For other cases, the following exit status codes are returned: jpayne@68: .TP jpayne@68: \*(T<\fB0\fR\*(T> jpayne@68: The input files are well-formed and the output (if requested) was written successfully. jpayne@68: .TP jpayne@68: \*(T<\fB1\fR\*(T> jpayne@68: An internal error occurred. jpayne@68: .TP jpayne@68: \*(T<\fB2\fR\*(T> jpayne@68: One or more input files were not well-formed or could not be parsed. jpayne@68: .TP jpayne@68: \*(T<\fB3\fR\*(T> jpayne@68: If using the \*(T<\fB\-d\fR\*(T> option, an error occurred opening an output file. jpayne@68: .TP jpayne@68: \*(T<\fB4\fR\*(T> jpayne@68: There was a command-line argument error in how \fBxmlwf\fR was invoked. jpayne@68: .SH BUGS jpayne@68: The errors should go to standard error, not standard output. jpayne@68: .PP jpayne@68: There should be a way to get \*(T<\fB\-d\fR\*(T> to send its jpayne@68: output to standard output rather than forcing the user to send jpayne@68: it to a file. jpayne@68: .PP jpayne@68: I have no idea why anyone would want to use the jpayne@68: \*(T<\fB\-d\fR\*(T>, \*(T<\fB\-c\fR\*(T>, and jpayne@68: \*(T<\fB\-m\fR\*(T> options. If someone could explain it to jpayne@68: me, I'd like to add this information to this manpage. jpayne@68: .SH "SEE ALSO" jpayne@68: .nf jpayne@68: jpayne@68: The Expat home page: https://libexpat.github.io/ jpayne@68: The W3 XML 1.0 specification (fourth edition): https://www.w3.org/TR/2006/REC\-xml\-20060816/ jpayne@68: Billion laughs attack: https://en.wikipedia.org/wiki/Billion_laughs_attack jpayne@68: .fi jpayne@68: .SH AUTHOR jpayne@68: This manual page was originally written by Scott Bronson <\*(T> jpayne@68: in December 2001 for jpayne@68: the Debian GNU/Linux system (but may be used by others). Permission is jpayne@68: granted to copy, distribute and/or modify this document under jpayne@68: the terms of the GNU Free Documentation jpayne@68: License, Version 1.1.