Release 1.5.29.
[wine] / tools / winedump / winedump.man.in
1 .\" -*- nroff -*-
2 .TH WINEDUMP 1 "October 2005" "@PACKAGE_STRING@" "Wine Developers Manual"
3 .SH NAME
4 winedump \- A Wine DLL tool
5 .SH SYNOPSIS
6 .BR "winedump " [ "-h " "| "
7 .BI "sym " "<sym> "
8 |
9 .BI "spec " "<dll> "
10 |
11 .BI "dump " "<file>"
12 .RI "] [" "mode_options" ]
13 .SH DESCRIPTION
14 .B winedump
15 is a Wine tool which aims to help:
16 .nf
17 A: Reimplementing a Win32 DLL for use within Wine, or
18 .nf
19 B: Compiling a Win32 application with Winelib that uses x86 DLLs
20 .PP
21 For both tasks in order to be able to link to the Win functions some
22 glue code is needed.  This 'glue' comes in the form of a \fI.spec\fR file.
23 The \fI.spec\fR file, along with some dummy code, is used to create a
24 Wine .so corresponding to the Windows DLL.  The \fBwinebuild\fR program
25 can then resolve calls made to DLL functions.
26 .PP
27 Creating a \fI.spec\fR file is a labour intensive task during which it is
28 easy to make a mistake. The idea of \fBwinedump\fR is to automate this task
29 and create the majority of the support code needed for your DLL. In
30 addition you can have \fBwinedump\fR create code to help you re-implement a
31 DLL, by providing tracing of calls to the DLL, and (in some cases)
32 automatically determining the parameters, calling conventions, and
33 return values of the DLL's functions.
34 .PP
35 Another use for this tool is to display (dump) information about a 32bit
36 DLL or PE format image file. When used in this way \fBwinedump\fR functions
37 similarly to tools such as pedump provided by many Win32 compiler
38 vendors.
39 .PP
40 Finally \fBwinedump\fR can be also used to demangle C++ symbols.
41 .SH MODES
42 .B winedump
43 can be used in several different modes.  The first argument to the
44 program determines the mode winedump will run in.
45 .IP \fB-h\fR
46 Help mode.
47 Basic usage help is printed.
48 .IP \fBdump\fR
49 To dump the contents of a file.
50 .IP \fBspec\fR
51 For generating .spec files and stub DLLs.
52 .IP \fBsym\fR
53 Symbol mode.
54 Used to demangle C++ symbols.
55 .SH OPTIONS
56 Mode options depend on the mode given as the first argument.
57 .PP
58 .B Help mode:
59 .nf
60 No options are used.
61 The program prints the help info and than exits.
62 .PP
63 .B Dump mode:
64 .IP \fI<file>\fR
65 Dumps the content of the file named \fI<file>\fR. Various file
66 formats are supported (PE, NE, LE, Minidumps, .lnk).
67 .IP \fB-C\fR
68 Turns on symbol demangling.
69 .IP \fB-f\fR
70 Dumps file header information.
71 This option dumps only the standard PE header structures,
72 along with the COFF sections available in the file.
73 .IP "\fB-j \fIdir_name\fR"
74 Dumps only the content of directory \fIdir_name\fR, for files
75 which header points to directories.
76 For PE files, currently the import, export, debug, resource,
77 tls and clr directories are implemented.
78 For NE files, currently the export and resource directories are
79 implemented.
80 .IP \fB-x\fR
81 Dumps everything.
82 This command prints all available information (including all
83 available directories - see \fB-j\fR option) about the file. You may
84 wish to pipe the output through more/less or into a file, since
85 a lot of output will be produced.
86 .IP \fB-G\fR
87 Dumps contents of debug section if any (for now, only stabs
88 information is supported).
89 .PP
90 .B Spec mode:
91 .IP \fI<dll>\fR
92 Use dll for input file and generate implementation code.
93 .IP "\fB-I \fIdir\fR"
94 Look for prototypes in '\fIdir\fR' (implies \fB-c\fR). In the case of
95 Windows DLLs, this could be either the standard include
96 directory from your compiler, or a SDK include directory.
97 If you have a text document with prototypes (such as
98 documentation) that can be used also, however you may need
99 to delete some non-code lines to ensure that prototypes are
100 parsed correctly.
101 The '\fIdir\fR' argument can also be a file specification (e.g.
102 "include/*"). If it contains wildcards you must quote it to
103 prevent the shell from expanding it.
104 If you have no prototypes, specify /dev/null for '\fIdir\fR'.
105 Winedump may still be able to generate some working stub
106 code for you.
107 .IP \fB-c\fR
108 Generate skeleton code (requires \fB-I\fR).
109 This option tells winedump to create function stubs for each
110 function in the DLL. As winedump reads each exported symbol
111 from the source DLL, it first tries to demangle the name. If
112 the name is a C++ symbol, the arguments, class and return
113 value are all encoded into the symbol name. Winedump
114 converts this information into a C function prototype. If
115 this fails, the file(s) specified in the \fB-I\fR argument are
116 scanned for a function prototype. If one is found it is used
117 for the next step of the process, code generation.
118 .IP \fB-t\fR
119 TRACE arguments (implies \fB-c\fR).
120 This option produces the same code as \fB-c\fR, except that
121 arguments are printed out when the function is called.
122 Structs that are passed by value are printed as "struct",
123 and functions that take variable argument lists print "...".
124 .IP "\fB-f \fIdll\fR"
125 Forward calls to '\fIdll\fR' (implies \fB-t\fR).
126 This is the most complicated level of code generation. The
127 same code is generated as \fB-t\fR, however support is added for
128 forwarding calls to another DLL. The DLL to forward to is
129 given as '\fIdll\fR'.
130 .IP \fB-D\fR
131 Generate documentation.
132 By default, winedump generates a standard comment at the
133 header of each function it generates. Passing this option
134 makes winedump output a full header template for standard
135 Wine documentation, listing the parameters and return value
136 of the function.
137 .IP "\fB-o \fIname\fR"
138 Set the output dll name (default: \fIdll\fR).
139 By default, if winedump is run on DLL 'foo', it creates
140 files 'foo.spec', 'foo_main.c' etc, and prefixes any
141 functions generated with 'FOO_'.  If '-o bar' is given,
142 these will become 'bar.spec', 'bar_main.c' and 'BAR_'
143 respectively.
144 This option is mostly useful when generating a forwarding DLL.
145 .IP \fB-C\fR
146 Assume __cdecl calls (default: __stdcall).
147 If winebuild cannot determine the calling convention,
148 __stdcall is used by default, unless this option has
149 been given.
150 Unless \fB-q\fR is given, a warning will be printed for every
151 function that winedump determines the calling convention
152 for and which does not match the assumed calling convention.
153 .IP "\fB-s \fInum\fR"
154 Start prototype search after symbol '\fInum\fR'.
155 .IP "\fB-e \fInum\fR"
156 End prototype search after symbol '\fInum\fR'.
157 By passing the \fB-s\fR or \fB-e\fR options you can have winedump try to
158 generate code for only some functions in your DLL. This may
159 be used to generate a single function, for example, if you
160 wanted to add functionality to an existing DLL.
161 .IP "\fB-S \fIsymfile\fR"
162 Search only prototype names found in '\fIsymfile\fR'.
163 If you want to only generate code for a subset of exported
164 functions from your source DLL, you can use this option to
165 provide a text file containing the names of the symbols to
166 extract, one per line. Only the symbols present in this file
167 will be used in your output DLL.
168 .IP \fB-q\fR
169 Don't show progress (quiet).
170 No output is printed unless a fatal error is encountered.
171 .IP \fB-v\fR
172 Show lots of detail while working (verbose).
173 There are 3 levels of output while winedump is running. The
174 default level, when neither -q or -v are given, prints the
175 number of exported functions found in the dll, followed by
176 the name of each function as it is processed, and a status
177 indication of whether it was processed OK.  With -v given, a
178 lot of information is dumped while winedump works: this is
179 intended to help debug any problems.
180 .PP
181 .B Sym mode:
182 .IP \fI<sym>\fR
183 Demangles C++ symbol '\fI<sym>\fR' and then exits.
184 .SH FILES
185 .I function_grep.pl
186 .RS
187 Perl script used to retrieve a function prototype.
188 .RE
189 .PP
190 Files output in
191 .B spec mode
192 for
193 .I foo.dll:
194 .nf
195 .I foo.spec
196 .RS
197 This is the .spec file.
198 .RE
199 .I foo_dll.h
200 .nf
201 .I foo_main.c
202 .RS
203 These are the source code files containing the minimum set
204 of code to build a stub DLL. The C file contains one
205 function, FOO_Init, which does nothing (but must be
206 present).
207 .RE
208 .I Makefile.in
209 .RS
210 This is a template for 'configure' to produce a makefile. It
211 is designed for a DLL that will be inserted into the Wine
212 source tree.
213 .SH BUGS
214 C++ name demangling is not fully in sync with the implementation in msvcrt.
215 It might be useful to submit your C++ name to the testsuite for msvcrt.
216 .SH AUTHORS
217 Jon P. Griffiths <jon_p_griffiths at yahoo dot com>
218 .nf
219 Michael Stefaniuc <mstefani at redhat dot com>
220 .SH "SEE ALSO"
221 .BR winedump "'s README file"
222 .nf
223 The Winelib User Guide
224 .nf
225 The Wine Developers Guide