diff options
Diffstat (limited to 'docs/manual/retrace/usage.html')
| -rw-r--r-- | docs/manual/retrace/usage.html | 117 |
1 files changed, 117 insertions, 0 deletions
diff --git a/docs/manual/retrace/usage.html b/docs/manual/retrace/usage.html new file mode 100644 index 0000000..88587ff --- /dev/null +++ b/docs/manual/retrace/usage.html @@ -0,0 +1,117 @@ +<!doctype html PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<html> +<head> +<meta http-equiv="content-type" content="text/html; charset=iso-8859-1"> +<meta http-equiv="content-style-type" content="text/css"> +<link rel="stylesheet" type="text/css" href="../style.css"> +<title>ReTrace Usage</title> +</head> +<body> + +<h2>Usage</h2> + +You can find the ReTrace jar in the <code>lib</code> directory of the +ProGuard distribution. To run ReTrace, just type: +<p> +<p class="code"> +<code><b>java -jar retrace.jar </b></code>[<i>options...</i>] + <i>mapping_file</i> [<i>stacktrace_file</i>] +</p> +These are the arguments: + +<dl> +<dt><i>mapping_file</i></dt> + +<dd>Specifies the name of the mapping file, produced by ProGuard with the + option + "<a href="../usage.html#printmapping"><code>-printmapping</code></a> <i>mapping_file</i>", + while obfuscating the application that produced the stack trace.</dd> + +<dt><i>stacktrace_file</i></dt> + +<dd>Optionally specifies the name of the file containing the stack trace. If + no file is specified, a stack trace is read from the standard input. Blank + lines and unrecognized lines are ignored, as far as possible.</dd> +</dl> + +The following options are supported: +<dl> +<dt><code><b>-verbose</b></code></dt> + +<dd>Specifies to print out more informative stack traces that include not only + method names, but also method return types and arguments.</dd> + +<dt><code><b>-regex</b></code> <i>regular_expression</i></dt> + +<dd>Specifies the regular expression that is used to parse the lines in the + stack trace. Specifying a different regular expression allows to + de-obfuscate more general types of input than just stack traces. The + default is suitable for stack traces produced by most JVMs: + <pre> + (?:\s*%c:.*)|(?:\s*at\s+%c.%m\s*\(.*?(?::%l)?\)\s*) + </pre> + The regular expression is a Java regular expression (cfr. the documentation + of <code>java.util.regex.Pattern</code>), with a few additional wildcards: + <table cellspacing="10"> + <tr><td valign="top"><code><b>%c</b></code></td> + <td>matches a class name (e.g. + "<code>myapplication.MyClass</code>").</td></tr> + <tr><td valign="top"><code><b>%C</b></code></td> + <td>matches a class name with slashes (e.g. + "<code>myapplication/MyClass</code>").</td></tr> + <tr><td valign="top"><code><b>%t</b></code></td> + <td>matches a field type or method return type (e.g. + "<code>myapplication.MyClass[]</code>").</td></tr> + <tr><td valign="top"><code><b>%f</b></code></td> + <td>matches a field name (e.g. + "<code>myField</code>").</td></tr> + <tr><td valign="top"><code><b>%m</b></code></td> + <td>matches a method name (e.g. + "<code>myMethod</code>").</td></tr> + <tr><td valign="top"><code><b>%a</b></code></td> + <td>matches a list of method arguments (e.g. + "<code>boolean,int</code>").</td></tr> + <tr><td valign="top"><code><b>%l</b></code></td> + <td>matches a line number inside a method (e.g. + "<code>123</code>").</td></tr> + </table> + Elements that match these wildcards are de-obfuscated, when possible. Note + that regular expressions must not contain any capturing groups. Use + non-capturing groups instead: <code>(?:</code>...<code>)</code> + </dd> +</dl> + +The restored stack trace is printed to the standard output. The completeness +of the restored stack trace depends on the presence of line number tables in +the obfuscated class files: + +<ul> +<li>If all line numbers have been preserved while obfuscating the application, + ReTrace will be able to restore the stack trace completely. + <p> + +<li>If the line numbers have been removed, mapping obfuscated method names + back to their original names has become ambiguous. Retrace will list all + possible original method names for each line in the stack trace. The user + can then try to deduce the actual stack trace manually, based on the logic + of the program. + +</ul> +<p> + +Preserving line number tables is explained in detail in this <a +href="../examples.html#stacktrace">example</a> in the ProGuard User Manual. +<p> + +Unobfuscated elements and obfuscated elements for which no mapping is available +will be left unchanged. +<p> + +<hr> +<address> +Copyright © 2002-2009 +<a href="http://www.graphics.cornell.edu/~eric/">Eric Lafortune</a>. +</address> +</body> +</html> + |