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