diff options
Diffstat (limited to '3rdparty/expat/doc/xmlwf.1')
-rw-r--r-- | 3rdparty/expat/doc/xmlwf.1 | 135 |
1 files changed, 105 insertions, 30 deletions
diff --git a/3rdparty/expat/doc/xmlwf.1 b/3rdparty/expat/doc/xmlwf.1 index ca56bf97650..61b302581ce 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 "November 6, 2024" "" "" .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-N\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,10 +82,42 @@ 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 @@ -73,7 +125,7 @@ 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 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 @@ -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. @@ -121,13 +192,17 @@ 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 @@ -156,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. @@ -165,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> @@ -210,24 +285,32 @@ 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. +\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 option \*(T<\fB\-v\fR\*(T> or \*(T<\fB\-h\fR\*(T>, \fBxmlwf\fR always exits with status code 0. For other cases, the following exit status codes are returned: +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. +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> -An input file was not well-formed or could not be parsed. +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 @@ -239,24 +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 |