diff options
Diffstat (limited to '3rdparty/expat/doc/xmlwf.1')
-rw-r--r-- | 3rdparty/expat/doc/xmlwf.1 | 164 |
1 files changed, 128 insertions, 36 deletions
diff --git a/3rdparty/expat/doc/xmlwf.1 b/3rdparty/expat/doc/xmlwf.1 index f45aea9cb4d..76aa7e30d07 100644 --- a/3rdparty/expat/doc/xmlwf.1 +++ b/3rdparty/expat/doc/xmlwf.1 @@ -5,7 +5,7 @@ \\$2 \(la\\$1\(ra\\$3 .. .if \n(.g .mso www.tmac -.TH XMLWF 1 "March 11, 2016" "" "" +.TH XMLWF 1 "March 27, 2025" "" "" .SH NAME xmlwf \- Determines if an XML document is well-formed .SH SYNOPSIS @@ -15,7 +15,27 @@ xmlwf \- Determines if an XML document is well-formed \fBxmlwf\fR \kx .if (\nx>(\n(.l/2)) .nr x (\n(.l/5) 'in \n(.iu+\nxu -[\fB-s\fR] [\fB-n\fR] [\fB-p\fR] [\fB-x\fR] [\fB-e \fIencoding\fB\fR] [\fB-w\fR] [\fB-d \fIoutput-dir\fB\fR] [\fB-c\fR] [\fB-m\fR] [\fB-r\fR] [\fB-t\fR] [\fB-v\fR] [file ...] +[\fIOPTIONS\fR] [\fIFILE\fR ...] +'in \n(.iu-\nxu +.ad b +'hy +'nh +.fi +.ad l +\fBxmlwf\fR \kx +.if (\nx>(\n(.l/2)) .nr x (\n(.l/5) +'in \n(.iu+\nxu +\fB-h\fR | \fB--help\fR +'in \n(.iu-\nxu +.ad b +'hy +'nh +.fi +.ad l +\fBxmlwf\fR \kx +.if (\nx>(\n(.l/2)) .nr x (\n(.l/5) +'in \n(.iu+\nxu +\fB-v\fR | \fB--version\fR 'in \n(.iu-\nxu .ad b 'hy @@ -34,7 +54,7 @@ following rules: \(bu The file begins with an XML declaration. For instance, \*(T<<?xml version="1.0" standalone="yes"?>\*(T>. -\fINOTE:\fR +\fINOTE\fR: \fBxmlwf\fR does not currently check for a valid XML declaration. .TP 0.2i @@ -62,24 +82,56 @@ it does not check the DTD. However, it does support external entities (see the \*(T<\fB\-x\fR\*(T> option). .SH OPTIONS When an option includes an argument, you may specify the argument either -separately ("\*(T<\fB\-d\fR\*(T> output") or concatenated with the -option ("\*(T<\fB\-d\fR\*(T>output"). \fBxmlwf\fR +separately ("\*(T<\fB\-d\fR\*(T> \fIoutput\fR") or concatenated with the +option ("\*(T<\fB\-d\fR\*(T>\fIoutput\fR"). \fBxmlwf\fR supports both. .TP +\*(T<\fB\-a\fR\*(T> \fIfactor\fR +Sets the maximum tolerated amplification factor +for protection against billion laughs attacks (default: 100.0). +The amplification factor is calculated as .. + +.nf + + amplification := (direct + indirect) / direct + +.fi + +\&.. 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. + +\fINOTE\fR: +If you ever need to increase this value for non-attack payload, +please file a bug report. +.TP +\*(T<\fB\-b\fR\*(T> \fIbytes\fR +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". + +\fINOTE\fR: +If you ever need to increase this value for non-attack payload, +please file a bug report. +.TP \*(T<\fB\-c\fR\*(T> If the input file is well-formed and \fBxmlwf\fR doesn't encounter any errors, the input file is simply copied to the output directory unchanged. This implies no namespaces (turns off \*(T<\fB\-n\fR\*(T>) and -requires \*(T<\fB\-d\fR\*(T> to specify an output file. +requires \*(T<\fB\-d\fR\*(T> to specify an output directory. .TP -\*(T<\fB\-d output\-dir\fR\*(T> +\*(T<\fB\-d\fR\*(T> \fIoutput-dir\fR Specifies a directory to contain transformed representations of the input files. By default, \*(T<\fB\-d\fR\*(T> outputs a canonical representation (described below). -You can select different output formats using \*(T<\fB\-c\fR\*(T> -and \*(T<\fB\-m\fR\*(T>. +You can select different output formats using \*(T<\fB\-c\fR\*(T>, +\*(T<\fB\-m\fR\*(T> and \*(T<\fB\-N\fR\*(T>. The output filenames will be exactly the same as the input filenames or "STDIN" if the input is @@ -96,7 +148,7 @@ is treated equivalently to data. More on canonical XML can be found at http://www.jclark.com/xml/canonxml.html . .TP -\*(T<\fB\-e encoding\fR\*(T> +\*(T<\fB\-e\fR\*(T> \fIencoding\fR Specifies the character encoding for the document, overriding any document encoding declaration. \fBxmlwf\fR supports four built-in encodings: @@ -106,6 +158,25 @@ supports four built-in encodings: \*(T<ISO\-8859\-1\*(T>. Also see the \*(T<\fB\-w\fR\*(T> option. .TP +\*(T<\fB\-g\fR\*(T> \fIbytes\fR +Sets the buffer size to request per call pair to +\*(T<\fBXML_GetBuffer\fR\*(T> and \*(T<\fBread\fR\*(T> +(default: 8 KiB). +.TP +\*(T<\fB\-h\fR\*(T>, \*(T<\fB\-\-help\fR\*(T> +Prints short usage information on command \fBxmlwf\fR, +and then exits. +Similar to this man page but more concise. +.TP +\*(T<\fB\-k\fR\*(T> +When processing multiple files, \fBxmlwf\fR +by default halts after the the first file with an error. +This tells \fBxmlwf\fR 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. +.TP \*(T<\fB\-m\fR\*(T> Outputs some strange sort of XML file that completely describes the input file, including character positions. @@ -115,14 +186,23 @@ Requires \*(T<\fB\-d\fR\*(T> to specify an output file. Turns on namespace processing. (describe namespaces) \*(T<\fB\-c\fR\*(T> disables namespaces. .TP +\*(T<\fB\-N\fR\*(T> +Adds a doctype and notation declarations to canonical XML output. +This matches the example output used by the formal XML test cases. +Requires \*(T<\fB\-d\fR\*(T> to specify an output file. +.TP \*(T<\fB\-p\fR\*(T> -Tells xmlwf to process external DTDs and parameter +Tells \fBxmlwf\fR to process external DTDs and parameter entities. Normally \fBxmlwf\fR never parses parameter entities. \*(T<\fB\-p\fR\*(T> tells it to always parse them. \*(T<\fB\-p\fR\*(T> implies \*(T<\fB\-x\fR\*(T>. .TP +\*(T<\fB\-q\fR\*(T> +Disable reparse deferral, and allow quadratic parse runtime +on large tokens (default: reparse deferral enabled). +.TP \*(T<\fB\-r\fR\*(T> Normally \fBxmlwf\fR memory-maps the XML file before parsing; this can result in faster parsing on many @@ -151,7 +231,7 @@ without client overhead. \*(T<\fB\-t\fR\*(T> turns off most of the output options (\*(T<\fB\-d\fR\*(T>, \*(T<\fB\-m\fR\*(T>, \*(T<\fB\-c\fR\*(T>, ...). .TP -\*(T<\fB\-v\fR\*(T> +\*(T<\fB\-v\fR\*(T>, \*(T<\fB\-\-version\fR\*(T> Prints the version of the Expat library being used, including some information on the compile-time configuration of the library, and then exits. @@ -160,7 +240,7 @@ then exits. Enables support for Windows code pages. Normally, \fBxmlwf\fR will throw an error if it runs across an encoding that it is not equipped to handle itself. With -\*(T<\fB\-w\fR\*(T>, xmlwf will try to use a Windows code +\*(T<\fB\-w\fR\*(T>, \fBxmlwf\fR will try to use a Windows code page. See also \*(T<\fB\-e\fR\*(T>. .TP \*(T<\fB\-x\fR\*(T> @@ -177,12 +257,14 @@ data from outside the XML file currently being parsed. This is an example of an internal entity: .nf + <!ENTITY vers '1.0.2'> .fi And here are some examples of external entities: .nf + <!ENTITY header SYSTEM "header\-&vers;.xml"> (parsed) <!ENTITY logo SYSTEM "logo.png" PNG> (unparsed) .fi @@ -193,6 +275,7 @@ Terminates the list of options. This is only needed if a filename starts with a hyphen. For example: .nf + xmlwf \-\- \-myfile.xml .fi @@ -202,18 +285,33 @@ will run \fBxmlwf\fR on the file Older versions of \fBxmlwf\fR do not support reading from standard input. .SH OUTPUT -If an input file is not well-formed, -\fBxmlwf\fR prints a single line describing -the problem to standard output. If a file is well formed, -\fBxmlwf\fR outputs nothing. -Note that the result code is \fInot\fR set. -.SH BUGS -\fBxmlwf\fR returns a 0 - noerr result, -even if the file is not well-formed. There is no good way for -a program to use \fBxmlwf\fR to quickly -check a file -- it must parse \fBxmlwf\fR's -standard output. +\fBxmlwf\fR 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, \fBxmlwf\fR prints a single +line describing the problem to standard output. .PP +If the \*(T<\fB\-k\fR\*(T> option is not provided, \fBxmlwf\fR +halts upon encountering a well-formedness or output-file error. +If \*(T<\fB\-k\fR\*(T> is provided, \fBxmlwf\fR continues +processing the remaining input files, describing problems found with any of them. +.SH "EXIT STATUS" +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: +.TP +\*(T<\fB0\fR\*(T> +The input files are well-formed and the output (if requested) was written successfully. +.TP +\*(T<\fB1\fR\*(T> +An internal error occurred. +.TP +\*(T<\fB2\fR\*(T> +One or more input files were not well-formed or could not be parsed. +.TP +\*(T<\fB3\fR\*(T> +If using the \*(T<\fB\-d\fR\*(T> option, an error occurred opening an output file. +.TP +\*(T<\fB4\fR\*(T> +There was a command-line argument error in how \fBxmlwf\fR was invoked. +.SH BUGS The errors should go to standard error, not standard output. .PP There should be a way to get \*(T<\fB\-d\fR\*(T> to send its @@ -224,22 +322,16 @@ I have no idea why anyone would want to use the \*(T<\fB\-d\fR\*(T>, \*(T<\fB\-c\fR\*(T>, and \*(T<\fB\-m\fR\*(T> options. If someone could explain it to me, I'd like to add this information to this manpage. -.SH ALTERNATIVES -Here are some XML validators on the web: - -.nf -http://www.hcrc.ed.ac.uk/~richard/xml\-check.html -http://www.stg.brown.edu/service/xmlvalid/ -http://www.scripting.com/frontier5/xml/code/xmlValidator.html -http://www.xml.com/pub/a/tools/ruwf/check.html -.fi .SH "SEE ALSO" .nf -The Expat home page: http://www.libexpat.org/ -The W3 XML specification: http://www.w3.org/TR/REC\-xml + +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 .fi .SH AUTHOR -This manual page was written by Scott Bronson <\*(T<bronson@rinspin.com\*(T>> for +This manual page was originally written by Scott Bronson <\*(T<bronson@rinspin.com\*(T>> +in December 2001 for the Debian GNU/Linux system (but may be used by others). Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation |