| MDT 2004 John Fleck | b1b3a77 | 2004-08-19 13:45:47 +0000 | [diff] [blame] | 1 | <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>xmllint</title><meta name="generator" content="DocBook XSL Stylesheets V1.61.2"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en"><a name="id2876302"></a><div class="titlepage"><div></div><div></div></div><div class="refnamediv"><h2>Name</h2><p>xmllint — command line <span class="acronym">XML</span> tool</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p><tt class="command">xmllint</tt> [[--version] | [--debug] | [--shell] | [--debugent] | [--copy] | [--recover] | [--noent] | [--noout] | [--nonet] | [--htmlout] | [--nowrap] | [--valid] | [--postvalid] | [--dtdvalid <i class="replaceable"><tt>URL</tt></i>] | [--dtdvalidfpi <i class="replaceable"><tt>FPI</tt></i>] | [--timing] | [--output <i class="replaceable"><tt>file</tt></i>] | [--repeat] | [--insert] | [--compress] | [--html] | [--xmlout] | [--push] | [--memory] | [--maxmem <i class="replaceable"><tt>nbbytes</tt></i>] | [--nowarning] | [--noblanks] | [--nocdata] | [--format] | [--encode <i class="replaceable"><tt>encoding</tt></i>] | [--dropdtd] | [--nsclean] | [--testIO] | [--catalogs] | [--nocatalogs] | [--auto] | [--xinclude] | [--noxincludenode] | [--loaddtd] | [--dtdattr] | [--stream] | [--walker] | [--pattern <i class="replaceable"><tt>patternvalue</tt></i>] | [--chkregister] | [--relaxng] | [--schema] | [--c14n]] [<tt class="option"><i class="replaceable"><tt>xmlfile</tt></i></tt>]</p></div></div><div class="refsect1" lang="en"><a name="introduction"></a><h2>Introduction</h2><p> |
| MDT 2003 John Fleck | 2ae05c7 | 2003-07-23 01:43:53 +0000 | [diff] [blame] | 2 | The xmllint program parses one or more XML files, specified on the |
| 3 | command line as <i class="replaceable"><tt>xmlfile</tt></i>. It prints various |
| 4 | types of output, depending upon the options selected. It is useful for |
| 5 | detecting errors both in <span class="acronym">XML</span> code and in the |
| 6 | <span class="acronym">XML</span> parser itself. |
| 7 | </p><p> |
| 8 | It is included in <span class="application">libxml2</span>. |
| 9 | </p></div><div class="refsect1" lang="en"><a name="options"></a><h2>Options</h2><div class="variablelist"><dl><dt><span class="term"><tt class="option">--version</tt></span></dt><dd> |
| 10 | Display the version of |
| 11 | <span class="application">libxml2</span> used. |
| 12 | </dd><dt><span class="term"><tt class="option">--debug</tt></span></dt><dd> |
| 13 | Parse a file and output an annotated tree of the |
| 14 | in-memory version of the document. |
| 15 | </dd><dt><span class="term"><tt class="option">--shell</tt></span></dt><dd> |
| 16 | Run a navigating shell. Details on available commands in shell mode |
| 17 | are below. |
| 18 | </dd><dt><span class="term"><tt class="option">--debugent</tt></span></dt><dd> |
| 19 | Debug the entities defined in the document. |
| 20 | </dd><dt><span class="term"><tt class="option">--copy</tt> </span></dt><dd> |
| 21 | Test the internal copy implementation. |
| 22 | </dd><dt><span class="term"><tt class="option">--recover</tt></span></dt><dd> |
| 23 | Output any parsable portions of an invalid |
| 24 | document. |
| 25 | </dd><dt><span class="term"><tt class="option">--noent</tt></span></dt><dd> |
| 26 | Substitute entity values for entity |
| 27 | references. By default, <span class="application">xmllint</span> leaves entity |
| 28 | references in place. |
| MST 2004 John Fleck | e42ae6f | 2004-02-27 03:26:30 +0000 | [diff] [blame] | 29 | </dd><dt><span class="term"><tt class="option">--nocdata</tt></span></dt><dd> |
| 30 | Substitute CDATA section by equivalent text nodes. |
| 31 | </dd><dt><span class="term"><tt class="option">--nsclean</tt></span></dt><dd> |
| 32 | Remove redundant namespace declarations. |
| MDT 2003 John Fleck | 2ae05c7 | 2003-07-23 01:43:53 +0000 | [diff] [blame] | 33 | </dd><dt><span class="term"><tt class="option">--noout</tt></span></dt><dd> |
| 34 | Suppress output. By default, |
| 35 | <span class="application">xmllint</span> outputs the result tree. |
| 36 | </dd><dt><span class="term"><tt class="option">--htmlout</tt></span></dt><dd> |
| 37 | Output results as an <span class="acronym">HTML</span> |
| 38 | file. This causes <span class="application">xmllint</span> to output |
| 39 | the necessary <span class="acronym">HTML</span> tags surrounding the result tree |
| 40 | output so the results can be displayed in a browser. |
| 41 | </dd><dt><span class="term"><tt class="option">--nowrap </tt></span></dt><dd> |
| 42 | Do not output HTML doc wrapper. |
| 43 | </dd><dt><span class="term"><tt class="option">--valid </tt></span></dt><dd> |
| 44 | Determine if the document is a valid instance |
| 45 | of the included Document Type Definition (<span class="acronym">DTD</span>). A |
| 46 | <span class="acronym">DTD</span> to be validated against also can be specified at |
| 47 | the command line using the <tt class="option">--dtdvalid</tt> option. By default, |
| 48 | <span class="application">xmllint</span> also checks to determine if the |
| 49 | document is well-formed. |
| 50 | </dd><dt><span class="term"><tt class="option">--postvalid</tt></span></dt><dd> |
| 51 | Validate after parsing is completed. |
| 52 | </dd><dt><span class="term"> <tt class="option">--dtdvalid</tt> <i class="replaceable"><tt>URL</tt></i></span></dt><dd> |
| 53 | Use the |
| 54 | <span class="acronym">DTD</span> specified by <i class="replaceable"><tt>URL</tt></i> for |
| 55 | validation. |
| MST 2004 John Fleck | e42ae6f | 2004-02-27 03:26:30 +0000 | [diff] [blame] | 56 | </dd><dt><span class="term"> <tt class="option">--dtdvalidfpi</tt> <i class="replaceable"><tt>FPI</tt></i></span></dt><dd> |
| 57 | Use the |
| 58 | <span class="acronym">DTD</span> specified by the Public Identifier |
| 59 | <i class="replaceable"><tt>FPI</tt></i> for validation, note that this |
| 60 | will require a Catalog exporting that Public Identifier to work. |
| MDT 2003 John Fleck | 2ae05c7 | 2003-07-23 01:43:53 +0000 | [diff] [blame] | 61 | </dd><dt><span class="term"><tt class="option">--timing</tt></span></dt><dd> |
| 62 | Output information about the time it takes |
| 63 | <span class="application">xmllint</span> to perform the various steps. |
| John Fleck | 3cbaa6d | 2004-08-15 00:47:45 +0000 | [diff] [blame] | 64 | </dd><dt><span class="term"><tt class="option">--output</tt> <i class="replaceable"><tt>file</tt></i></span></dt><dd>Define a file path where xmllint will save the result of |
| 65 | parsing. Usually the programs build a tree and save it on stdout, with |
| 66 | this option the result XML instance will be saved onto a file.</dd><dt><span class="term"><tt class="option">--repeat</tt></span></dt><dd> |
| MDT 2003 John Fleck | 2ae05c7 | 2003-07-23 01:43:53 +0000 | [diff] [blame] | 67 | Repeat 100 times, for timing or profiling. |
| 68 | </dd><dt><span class="term"><tt class="option">--insert</tt></span></dt><dd> |
| 69 | Test for valid insertions. |
| 70 | </dd><dt><span class="term"><tt class="option">--compress</tt></span></dt><dd> |
| 71 | Turn on gzip compression of output. |
| Daniel Veillard | 1afc9f3 | 2003-09-13 12:44:05 +0000 | [diff] [blame] | 72 | </dd><dt><span class="term"><tt class="option">--html</tt></span></dt><dd> |
| MDT 2003 John Fleck | 2ae05c7 | 2003-07-23 01:43:53 +0000 | [diff] [blame] | 73 | Use the <span class="acronym">HTML</span> parser. |
| Daniel Veillard | f10ae12 | 2005-07-10 19:03:16 +0000 | [diff] [blame] | 74 | </dd><dt><span class="term"><tt class="option">--xmlout</tt></span></dt><dd>Used in conjunction with <tt class="option">--html</tt>. Usually |
| John Fleck | 3cbaa6d | 2004-08-15 00:47:45 +0000 | [diff] [blame] | 75 | when HTML is parsed the document is saved with the HTML serializer, but with |
| 76 | this option the resulting document is saved with the XML serializer. This is |
| 77 | primarily used to generate XHTML from HTML input.</dd><dt><span class="term"><tt class="option">--push</tt></span></dt><dd> |
| MDT 2003 John Fleck | 2ae05c7 | 2003-07-23 01:43:53 +0000 | [diff] [blame] | 78 | Use the push mode of the parser. |
| 79 | </dd><dt><span class="term"><tt class="option">--memory</tt></span></dt><dd> |
| 80 | Parse from memory. |
| John Fleck | 3cbaa6d | 2004-08-15 00:47:45 +0000 | [diff] [blame] | 81 | </dd><dt><span class="term"><tt class="option">--maxmem</tt> <i class="replaceable"><tt>nnbytes</tt></i></span></dt><dd>Test the parser memory |
| 82 | support. <i class="replaceable"><tt>nnbytes</tt></i> is the maximum number of bytes the |
| 83 | library is allowed to allocate. This can also be used to make sure batch |
| 84 | processing of XML files will not exhaust the virtual memory of the server |
| 85 | running them.</dd><dt><span class="term"><tt class="option">--nowarning</tt></span></dt><dd> |
| MDT 2003 John Fleck | 2ae05c7 | 2003-07-23 01:43:53 +0000 | [diff] [blame] | 86 | Do not emit warnings from the parser and/or validator. |
| 87 | </dd><dt><span class="term"><tt class="option">--noblanks</tt></span></dt><dd> |
| 88 | Drop ignorable blank spaces. |
| 89 | </dd><dt><span class="term"><tt class="option">--format</tt></span></dt><dd> |
| 90 | Reformat and reindent the output. The $XMLLINT_INDENT |
| 91 | environment variable controls the indentation (default |
| 92 | value is two spaces " "). |
| 93 | </dd><dt><span class="term"><tt class="option">--testIO</tt></span></dt><dd> |
| 94 | Test user input/output support. |
| 95 | </dd><dt><span class="term"><tt class="option">--encode</tt> <i class="replaceable"><tt>encoding</tt></i></span></dt><dd> |
| 96 | Output in the given encoding. |
| 97 | </dd><dt><span class="term"><tt class="option">--catalogs</tt></span></dt><dd> |
| 98 | Use the catalogs from $SGML_CATALOG_FILES. Otherwise /etc/xml/catalog |
| 99 | is used by default. |
| 100 | </dd><dt><span class="term"><tt class="option">--nocatalogs</tt></span></dt><dd> |
| 101 | Do not use any catalogs. |
| 102 | </dd><dt><span class="term"><tt class="option">--auto</tt></span></dt><dd> |
| 103 | Generate a small document for testing purposes. |
| 104 | </dd><dt><span class="term"><tt class="option">--xinclude</tt></span></dt><dd> |
| 105 | Do XInclude processing. |
| MDT 2004 John Fleck | b1b3a77 | 2004-08-19 13:45:47 +0000 | [diff] [blame] | 106 | </dd><dt><span class="term"><tt class="option">--noxincludenode</tt></span></dt><dd> |
| 107 | Do XInclude processing but do not generate XInclude start and end |
| 108 | nodes. |
| MDT 2003 John Fleck | 2ae05c7 | 2003-07-23 01:43:53 +0000 | [diff] [blame] | 109 | </dd><dt><span class="term"><tt class="option">--loaddtd</tt></span></dt><dd> |
| 110 | Fetch external DTD. |
| 111 | </dd><dt><span class="term"><tt class="option">--dtdattr</tt></span></dt><dd> |
| 112 | Fetch external DTD and populate the tree with inherited attributes. |
| 113 | </dd><dt><span class="term"><tt class="option">--dropdtd</tt></span></dt><dd> |
| 114 | Remove <span class="acronym">DTD</span> from output. |
| 115 | </dd><dt><span class="term"><tt class="option">--stream</tt></span></dt><dd>Use streaming API - useful when used in combination with |
| 116 | --relaxng or --valid options for validation of files that are |
| John Fleck | 3cbaa6d | 2004-08-15 00:47:45 +0000 | [diff] [blame] | 117 | too large to be held in memory.</dd><dt><span class="term"><tt class="option">--walker</tt></span></dt><dd>Test the walker module, which is a reader interface but for a |
| 118 | document tree, instead of using the reader API on an unparsed document it |
| 119 | works on a existing in-memory tree. Used in debugging.</dd><dt><span class="term"><tt class="option">--chkregister</tt></span></dt><dd>Turn on node registration. Useful for developers testing |
| 120 | libxml2 node tracking code.</dd><dt><span class="term"><tt class="option">--pattern</tt> <i class="replaceable"><tt>patternvalue</tt></i></span></dt><dd>Used to exercise the pattern recognition engine, which can be |
| 121 | used with the reader interface to the parser. It allows to select some |
| 122 | nodes in the document based on an XPath (subset) expression. Used for |
| 123 | debugging.</dd><dt><span class="term"><tt class="option">--relaxng</tt> <i class="replaceable"><tt>schema</tt></i></span></dt><dd>Use RelaxNG file named <i class="replaceable"><tt>schema</tt></i> for |
| MDT 2004 John Fleck | b1b3a77 | 2004-08-19 13:45:47 +0000 | [diff] [blame] | 124 | validation.</dd><dt><span class="term"><tt class="option">--schema</tt> <i class="replaceable"><tt>schema</tt></i></span></dt><dd>Use a W3C XML Schema file named <i class="replaceable"><tt>schema</tt></i> for validation.</dd><dt><span class="term"> |
| 125 | <tt class="option">--c14n</tt></span></dt><dd>Use the W3C XML Canonicalisation (C14N) to |
| 126 | serialize the result of parsing to stdout. It keeps comments in |
| 127 | the result.</dd></dl></div></div><div class="refsect1" lang="en"><a name="shell"></a><h2>Shell</h2><p> |
| MDT 2003 John Fleck | 2ae05c7 | 2003-07-23 01:43:53 +0000 | [diff] [blame] | 128 | <span class="application">xmllint</span> offers an interactive shell mode |
| 129 | invoked with the <tt class="option">--shell</tt> command. Available commands in |
| 130 | shell mode include: |
| 131 | </p><div class="variablelist"><dl><dt><span class="term"><tt class="option">base</tt></span></dt><dd> |
| 132 | display XML base of the node |
| 133 | </dd><dt><span class="term"><tt class="option">bye</tt></span></dt><dd> |
| 134 | leave shell |
| 135 | </dd><dt><span class="term"><tt class="option">cat <i class="replaceable"><tt>node</tt></i></tt></span></dt><dd> |
| 136 | Display node if given or current node. |
| 137 | </dd><dt><span class="term"><tt class="option">cd <i class="replaceable"><tt>path</tt></i></tt></span></dt><dd> |
| 138 | Change the current node to <i class="replaceable"><tt>path</tt></i> (if given |
| 139 | and unique) or root if no argument given. |
| 140 | </dd><dt><span class="term"><tt class="option">dir <i class="replaceable"><tt>path</tt></i></tt></span></dt><dd> |
| 141 | Dumps information about the node (namespace, attributes, content). |
| 142 | </dd><dt><span class="term"><tt class="option">du <i class="replaceable"><tt>path</tt></i></tt></span></dt><dd> |
| 143 | Show the structure of the subtree under path or the current node. |
| 144 | </dd><dt><span class="term"><tt class="option">exit</tt></span></dt><dd> |
| 145 | Leave the shell. |
| 146 | </dd><dt><span class="term"><tt class="option">help</tt></span></dt><dd> |
| 147 | Show this help. |
| 148 | </dd><dt><span class="term"><tt class="option">free</tt></span></dt><dd> |
| 149 | Display memory usage. |
| 150 | </dd><dt><span class="term"><tt class="option">load <i class="replaceable"><tt>name</tt></i></tt></span></dt><dd> |
| 151 | Load a new document with the given name. |
| 152 | </dd><dt><span class="term"><tt class="option">ls <i class="replaceable"><tt>path</tt></i></tt></span></dt><dd> |
| 153 | List contents of <i class="replaceable"><tt>path</tt></i> (if given) or the |
| 154 | current directory. |
| 155 | </dd><dt><span class="term"><tt class="option">pwd</tt></span></dt><dd> |
| 156 | Display the path to the current node. |
| 157 | </dd><dt><span class="term"><tt class="option">quit</tt></span></dt><dd> |
| 158 | Leave the shell. |
| 159 | </dd><dt><span class="term"><tt class="option">save <i class="replaceable"><tt>name</tt></i></tt></span></dt><dd> |
| 160 | Saves the current document to <i class="replaceable"><tt>name</tt></i> if |
| 161 | given or to the original name. |
| 162 | </dd><dt><span class="term"><tt class="option">validate</tt></span></dt><dd> |
| 163 | Check the document for error. |
| 164 | </dd><dt><span class="term"><tt class="option">write <i class="replaceable"><tt>name</tt></i></tt></span></dt><dd> |
| 165 | Write the current node to the given filename. |
| MST 2004 John Fleck | e42ae6f | 2004-02-27 03:26:30 +0000 | [diff] [blame] | 166 | </dd></dl></div></div><div class="refsect1" lang="en"><h2>Catalogs</h2><p>Catalog behavior can be changed by redirecting |
| 167 | queries to the user's own set of catalogs. This can be done by setting the |
| 168 | <tt class="varname">XML_CATALOG_FILES</tt> environment variable to a list of |
| 169 | catalogs. An empty one should deactivate loading the default |
| 170 | <tt class="filename">/etc/xml/catalog</tt> default catalog.</p></div><div class="refsect1" lang="en"><h2>Debugging Catalogs</h2><p>Setting the environment variable <tt class="varname">XML_DEBUG_CATALOG</tt> |
| MDT 2003 John Fleck | 2ae05c7 | 2003-07-23 01:43:53 +0000 | [diff] [blame] | 171 | using the command <b class="command">"export XML_DEBUG_CATALOG="</b> |
| MDT 2004 John Fleck | 4c76c4f | 2004-06-20 00:36:06 +0000 | [diff] [blame] | 172 | outputs debugging information related to catalog operations.</p></div><div class="refsect1" lang="en"><h2>Error Return Codes</h2><p>On the completion of execution, <span class="application">Xmllint</span> |
| 173 | returns the following error codes:</p><div class="variablelist"><dl><dt><span class="term">0</span></dt><dd>No error</dd><dt><span class="term">1</span></dt><dd>Unclassified</dd><dt><span class="term">2</span></dt><dd>Error in DTD</dd><dt><span class="term">3</span></dt><dd>Validation error</dd><dt><span class="term">4</span></dt><dd>Validation error</dd><dt><span class="term">5</span></dt><dd>Error in schema compilation</dd><dt><span class="term">6</span></dt><dd>Error writing output</dd><dt><span class="term">7</span></dt><dd>Error in pattern (generated when |
| 174 | [<span class="optional">--pattern</span>] option is used)</dd><dt><span class="term">8</span></dt><dd>Error in Reader registration (generated when |
| 175 | [<span class="optional">--chkregister</span>] option is used)</dd><dt><span class="term">9</span></dt><dd>Out of memory error</dd></dl></div></div></div></body></html> |