summaryrefslogtreecommitdiffstatshomepage
path: root/3rdparty/expat/doc/xmlwf.1
diff options
context:
space:
mode:
Diffstat (limited to '3rdparty/expat/doc/xmlwf.1')
-rw-r--r--3rdparty/expat/doc/xmlwf.1135
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