ReactOS  0.4.15-dev-3187-ge372f2b
help.c
Go to the documentation of this file.
1 /*
2  * ReactOS log2lines
3  * Written by Jan Roeloffzen
4  *
5  * - Help text and functions
6  */
7 
8 #include <stdio.h>
9 
10 #include "version.h"
11 #include "compat.h"
12 #include "config.h"
13 #include "options.h"
14 #include "cmd.h"
15 #include "help.h"
16 
17 char *verboseUsage =
18 "\n"
19 "Description:\n"
20 " When <exefile> <offset> are given, log2lines works like raddr2line:\n"
21 " - The <exefile> <offset> combination can be repeated\n"
22 " - Also, <offset> can be repeated for each <exefile>\n"
23 " - NOTE: Some of the options below will have no effect in this form.\n"
24 " Otherwise it reads stdin and tries to translate lines of the form:\n"
25 " <IMAGENAME:ADDRESS>\n"
26 " The result is written to stdout.\n\n"
27 " <offset> or <ADDRESS> can be absolute or relative with the restrictions:\n"
28 " - An image with base < 0x400000 MUST be relocated to a > 0x400000 address.\n"
29 " - The offset of a relocated image MUST be relative.\n\n"
30 " log2lines uses a cache in order to avoid a directory scan at each\n"
31 " image lookup, greatly increasing performance. Only image path and its\n"
32 " base address are cached.\n\n"
33 "Options:\n"
34 " -b Use this combined with '-l'. Enable buffering on logFile.\n"
35 " This may solve loosing output on real hardware (ymmv).\n\n"
36 " -c Console mode. Outputs text per character instead of per line.\n"
37 " This is slightly slower but enables to see what you type.\n\n"
38 " -d <directory>|<ISO image>\n"
39 " <directory>: Directory to scan for images. (Do not append a '" PATH_STR "')\n"
40 " <ISO image>: This option also takes an ISO image as argument:\n"
41 " - The image is recognized by the '.iso' or '.7z' extension.\n"
42 " - NOTE: The '.7z' and extracted '.iso' basenames must be identical,\n"
43 " which is normally true for ReactOS trunk builds.\n"
44 " - The image will be unpacked to a directory with the same name.\n"
45 " - The embedded reactos.cab file will also be unpacked.\n"
46 " - Combined with -f the file will be re-unpacked.\n"
47 " - NOTE: this ISO unpack feature needs 7z to be in the PATH.\n"
48 " Default: " DEF_OPT_DIR "\n\n"
49 " -f Force creating new cache.\n\n"
50 " -F As -f but exits immediately after creating cache.\n\n"
51 " -h This text.\n\n"
52 " -l <logFile>\n"
53 " <logFile>: Append copy to specified logFile.\n"
54 " Default: no logFile\n\n"
55 " -L <logFile>\n"
56 " <logFile>: (Over)write copy to specified logFile.\n"
57 " Default: no logFile\n\n"
58 " -m Prefix (mark) each translated line with '* '.\n\n"
59 " -M Prefix (mark) each NOT translated line with '? '.\n"
60 " ( Only for lines of the form: <IMAGENAME:ADDRESS> )\n\n"
61 " -P <cmd line>\n"
62 " Pipeline command line. Spawn <cmd line> and pipeline its output to\n"
63 " log2lines (as stdin). This is for shells lacking support of (one of):\n"
64 " - Input file redirection.\n"
65 " - Pipelining byte streams, needed for the -c option.\n\n"
66 " -r Raw output without translation.\n\n"
67 " -s Statistics. A summary with the following info is printed after EOF:\n"
68 " *** LOG2LINES SUMMARY ***\n"
69 " - Translated: Translated lines.\n"
70 " - Reverted: Lines translated back. See -u option\n"
71 " - Retranslated: Lines retranslated. See -U option\n"
72 " - Skipped: Lines not translated.\n"
73 " - Differ: Lines where (addr-1) info differs. See -tT options\n"
74 " - Differ(func/src):Lines where also function or source info differ.\n"
75 " - Rev conflicts: Source files conflicting with build. See '-R check'\n"
76 " - Reg candidates: Regression candidates. See '-R regscan'\n"
77 " - Offset error: Image exists, but error retrieving offset info.\n"
78 " - Total: Total number of lines attempted to translate.\n"
79 " Also some version info is displayed.\n\n"
80 " -S <context>[+<add>][,<sources>]\n"
81 " Source line options:\n"
82 " <context>: Source lines. Display up to <context> lines until linenumber.\n"
83 " <add> : Optional. Display additional <add> lines after linenumber.\n"
84 " <sources>: Optional. Specify alternate source tree.\n"
85 " The environment variable " SOURCES_ENV " should be correctly set\n"
86 " or specify <sources>. Use double quotes if the path contains spaces.\n"
87 " For a reliable result, these sources should be up to date with\n"
88 " the tested revision (or try '-R check').\n"
89 " Can be combined with -tTR.\n"
90 " Implies -U (For retrieving source info) and -R check.\n\n"
91 " -t Translate twice. The address itself and for (address-1).\n"
92 " Show extra filename, func and linenumber between [..] if they differ\n"
93 " So if only the linenumbers differ, then only show the extra\n"
94 " linenumber.\n\n"
95 " -T As -t, but show only filename+func+linenumber for (address-1)\n\n"
96 " -u Undo translations.\n"
97 " Lines are translated back (reverted) to the form <IMAGENAME:ADDRESS>\n"
98 " Also removes all lines previously added by this tool (e.g. see -S)\n\n"
99 " -U Undo and reprocess.\n"
100 " Reverted to the form <IMAGENAME:ADDRESS>, and then retranslated\n"
101 " Implies -u.\n\n"
102 " -v Show detailed errors and tracing.\n"
103 " Repeating this option adds more verbosity.\n"
104 " Default: only (major) errors\n\n"
105 " -z <path to 7z>\n"
106 " <path to 7z>: Specify path to 7z. See also option -d.\n"
107 " Default: '7z'\n"
108 "\n"
109 "CLI escape commands:\n"
110 " It is possible to change options and perform actions from the 'kdb:>' prompt\n"
111 " By prepending the `(backquote) character to the option.\n"
112 " Example: 'kdb:> `l new.log' changes the current logfile to 'new.log'.\n"
113 " Flag options like 'b' are given a numeric value of 0 (off) or 1 (on).\n"
114 " Options accepting a string as argument can be cleared by the value '" KDBG_ESC_OFF "'.\n"
115 " Some ClI commands are read only or not (entirely) implemented.\n"
116 " If no value is provided, the current one is printed.\n"
117 " There are a few extra ClI commands or with different behaviour:\n"
118 " - `a <module>:<reladdress>:\n"
119 " - Outputs absolute address e.g. for setting breakpoints.\n"
120 " - Do a 'mod' first to retrieve relocation info.\n"
121 " - `h : shows this helptext (without exiting)\n"
122 " - `q : quits log2lines\n"
123 " - `s : the output is printed immediately\n"
124 " - `s clear : clears all statistics.\n"
125 " - `S : only <context> and <add> can be set.\n"
126 " - `v <level> : sets the current debug loglevel\n"
127 "\n"
128 "Option Examples:\n"
129 " Setup: A VMware machine with its serial port set to: '\\\\.\\pipe\\kdbg'.\n\n"
130 " Just recreate cache after a svn update or a new module has been added:\n"
131 " log2lines -F\n\n"
132 " Use kdbg debugger via console (interactive):\n"
133 " log2lines -c < \\\\.\\pipe\\kdbg\n\n"
134 " Use kdbg debugger via console, and append copy to logFile:\n"
135 " log2lines -c -l dbg.log < \\\\.\\pipe\\kdbg\n\n"
136 " Same as above, but for PowerShell:\n"
137 " log2lines -c -l dbg.log -P \"piperead -c \\\\.\\pipe\\kdbg\"\n\n"
138 " Use kdbg debugger to send output to logfile:\n"
139 " log2lines < \\\\.\\pipe\\kdbg > dbg.log\n\n"
140 " Re-translate a debug log:\n"
141 " log2lines -U -d bootcd-38701-dbg.iso < bugxxxx.log\n\n"
142 " Re-translate a debug log. Specify a 7z file, which wil be decompressed.\n"
143 " Also check for (address) - (address-1) differences:\n"
144 " log2lines -U -t -d bootcd-38701-dbg.7z < bugxxxx.log\n"
145 " Output:\n"
146 " <ntdll.dll:60f1 (dll/ntdll/ldr/utils.c:337[331] (LdrPEStartup))>\n\n"
147 " The following commands are equivalent:\n"
148 " log2lines msi.dll 2e35d msi.dll 2235 msiexec.exe 30a8 msiexec.exe 2e89\n"
149 " log2lines msi.dll 2e35d 2235 msiexec.exe 30a8 2e89\n\n"
150 " Generate source lines from backtrace ('bt') output. Show 2 lines of context:\n"
151 " log2lines -S 2 -d bootcd-38701-dbg.7z < bugxxxx.log\n"
152 " Output:\n"
153 " <msiexec.exe:2e89 (lib/3rdparty/mingw/crtexe.c:259 (__tmainCRTStartup))>\n"
154 " | 0258 #else\n"
155 " | 0259 mainret = main (\n"
156 " <msiexec.exe:2fad (lib/3rdparty/mingw/crtexe.c:160 (WinMainCRTStartup))>\n"
157 " | 0159 return __tmainCRTStartup ();\n"
158 " | 0160 }\n\n"
159 " Generate source lines. Show 2 lines of context plus 1 additional line and\n"
160 " specify an alternate source tree:\n"
161 " log2lines -S 2+1,\"c:\\ros trees\\r44000\" -d bootcd-44000-dbg < dbg.log\n"
162 " Output:\n"
163 " <msi.dll:2e35d (dll/win32/msi/msiquery.c:189 (MSI_IterateRecords))>\n"
164 " | 0188 {\n"
165 " | 0189 r = MSI_ViewFetch( view, &rec );\n"
166 " | ----\n"
167 " | 0190 if( r != ERROR_SUCCESS )\n\n"
168 " Use '-R check' to show that action.c has been changed after the build:\n"
169 " log2lines -s -d bootcd-43850-dbg.iso -R check -S 2 < dbg.log\n"
170 " Output:\n"
171 " <msi.dll:35821 (dll/win32/msi/registry.c:781 (MSIREG_OpenUserDataKey))>\n"
172 " | 0780 if (create)\n"
173 " | 0781 rc = RegCreateKeyW(HKEY_LOCAL_MACHINE, keypath, key);\n"
174 " <msi.dll:5262 (dll/win32/msi/action.c:2665 (ACTION_ProcessComponents))>\n"
175 " | R--- Conflict : source(44191) > build(43850)\n"
176 " | 2664 else\n"
177 " | 2665 rc = MSIREG_OpenUserDataKey(comp->ComponentId,\n\n"
178 "CLI Examples: (some are based on the option examples above)\n"
179 " Use '`R check' to show that action.c has been changed after the build:\n"
180 " kdb:> `R check\n"
181 " | L2L- -R is \"check\" (changed)\n"
182 " kdb:> bt\n"
183 " <msi.dll:35821 (dll/win32/msi/registry.c:781 (MSIREG_OpenUserDataKey))>\n"
184 " | 0780 if (create)\n"
185 " | 0781 rc = RegCreateKeyW(HKEY_LOCAL_MACHINE, keypath, key);\n"
186 " <msi.dll:5262 (dll/win32/msi/action.c:2665 (ACTION_ProcessComponents))>\n"
187 " | R--- Conflict : source(44191) > build(43850)\n"
188 " | 2664 else\n"
189 " | 2665 rc = MSIREG_OpenUserDataKey(comp->ComponentId,\n\n"
190 " kdb:>\n\n"
191 " Generate source lines. Show 2 lines of context plus 1 additional line.\n"
192 " The -Uu options are dependent on -S:\n"
193 " kdb:> `S 2+1\n"
194 " | L2L- -u Undo is 1 (changed)\n"
195 " | L2L- -U Undo and reprocess is 1 (changed)\n"
196 " | L2L- -S Sources option is 2+1,\"C:\\ROS\\reactos\\\" \n"
197 " | L2L- (Setting source tree not implemented)\n"
198 " kdb:> bt\n"
199 " <msi.dll:2e35d (dll/win32/msi/msiquery.c:189 (MSI_IterateRecords))>\n"
200 " | 0188 {\n"
201 " | 0189 r = MSI_ViewFetch( view, &rec );\n"
202 " | ----\n"
203 " | 0190 if( r != ERROR_SUCCESS )\n"
204 " kdb:>\n\n"
205 " Change logfile:\n"
206 " kdb:> `l\n"
207 " | L2L- -l logfile is "" (unchanged)\n"
208 " kdb:> `l new.log\n"
209 " | L2L- -l logfile is \"new.log\" (changed)\n"
210 " kdb:> `l off\n"
211 " | L2L- -l logfile is "" (changed)\n"
212 " kdb:>\n\n"
213 " Set a breakpoint with help of 'mod' and '`a':\n"
214 " <msi.dll:2e35d (dll/win32/msi/msiquery.c:189 (MSI_IterateRecords))>\n"
215 " kdb:> mod (for kernel tracing usually only needed once)\n"
216 " -- mod output with reloc info\n"
217 " kdb:> `a msi.dll:2e35d\n"
218 " | L2L- Address: 0x00096ca0\n"
219 " kdb:> bpx 0x00096ca0\n\n"
220 "\n";
221 
222 void
224 {
225  fprintf(stderr, "log2lines " LOG2LINES_VERSION "\n\n");
226  fprintf(stderr, "Usage: log2lines -%s {<exefile> <offset> {<offset>}}\n", optchars);
227  if (verbose)
228  fprintf(stderr, "%s", verboseUsage);
229  else
230  fprintf(stderr, "Try log2lines -h\n");
231 }
232 
233 /* EOF */
#define SOURCES_ENV
Definition: config.h:9
char * verboseUsage
Definition: help.c:17
#define verbose
Definition: rosglue.h:36
void usage(int verbose)
Definition: help.c:223
_Check_return_opt_ _CRTIMP int __cdecl fprintf(_Inout_ FILE *_File, _In_z_ _Printf_format_string_ const char *_Format,...)
#define LOG2LINES_VERSION
Definition: version.h:10
char * optchars
Definition: options.c:20
FILE * stderr
#define PATH_STR
Definition: compat.h:27
#define DEF_OPT_DIR
Definition: config.h:8
#define KDBG_ESC_OFF
Definition: cmd.h:16