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