Porting fixes.
[wine.git] / tools / winedump / winedump.man
blobe1986d3d7d35560fd0e3823ea2e4df1e8500ff41
1 .TH WINEDUMP 1 "February 2004" "Wine Manpage" "Wine Developers Manual"
2 .SH NAME
3 winedump \- A Wine DLL tool
4 .SH SYNOPSIS
5 .BR "winedump " [ "-h " "| "
6 .BI "sym " "<sym> "
8 .BI "spec " "<dll> "
10 .BI "dump " "<dll>"
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 .so 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 reimplement 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 DLLs functions.
33 .PP
34 \fBwinedump\fR can be also used to dump other information from PE files
35 or to demangle C++ symbols.
36 .SH MODES
37 .B winedump
38 can be used in several different modes.  The first argument to the
39 program determines the mode winedump will run in.
40 .IP \fB-h\fR
41 Help mode.
42 Basic usage help is printed.
43 .IP \fBdump\fR
44 To dump the contents of a PE file.
45 .IP \fBspec\fR
46 For generating .spec files and stub DLL's.
47 .IP \fBsym\fR
48 Symbol mode.
49 Used to demangle C++ symbols.
50 .SH OPTIONS
51 Mode options depend on the mode given as the first argument.
52 .PP
53 .B Help mode:
54 .nf
55 No options are used.
56 The program prints the help info and than exits.
57 .PP
58 .B Dump mode:
59 .IP \fI<dll>\fR
60 Dumps the content of the dll named \fI<dll>\fR.
61 .IP \fB-C\fR
62 Turns on symbol demangling.
63 .IP \fB-f\fR
64 Dumps file header information.
65 This option dumps only the standard PE header structures,
66 along with the COFF sections available in the file.
67 .IP "\fB-j \fIsect_name\fR"
68 Dumps only the content of section sect_name (import,
69 export, debug).
70 To dump only a given directory, specify them using this
71 option. Currently only the import, export and debug
72 directories are implemented.
73 .IP \fB-x\fR
74 Dumps everything.
75 .PP
76 .B Spec mode:
77 .IP \fI<dll>\fR
78 Use dll for input file and generate implementation code.
79 .IP "\fB-I \fIdir\fR"
80 Look for prototypes in '\fIdir\fR' (implies \fB-c\fR). In the case of
81 Windows DLLs, this could be either the standard include
82 directory from your compiler, or a SDK include directory.
83 If you have a text document with prototypes (such as
84 documentation) that can be used also, however you may need
85 to delete some non-code lines to ensure that prototypes are
86 parsed correctly.
87 The '\fIdir\fR' argument can also be a file specification (e.g.
88 "include/*"). If it contains wildcards you must quote it to
89 prevent the shell from expanding it.
90 If you have no prototypes, specify /dev/null for '\fIdir\fR'.
91 Winedump may still be able to generate some working stub
92 code for you.
93 .IP \fB-c\fR
94 Generate skeleton code (requires \fB-I\fR).
95 This option tells winedump to create function stubs for each
96 function in the DLL. As winedump reads each exported symbol
97 from the source DLL, it first tries to demangle the name. If
98 the name is a C++ symbol, the arguments, class and return
99 value are all encoded into the symbol name. Winedump
100 converts this information into a C function prototype. If
101 this fails, the file(s) specified in the \fB-I\fR argument are
102 scanned for a function prototype. If one is found it is used
103 for the next step of the process, code generation.
104 .IP \fB-t\fR
105 TRACE arguments (implies \fB-c\fR).
106 This option produces the same code as \fB-c\fR, except that
107 arguments are printed out when the function is called.
108 .IP "\fB-f \fIdll\fR"
109 Forward calls to '\fIdll\fR' (implies \fB-t\fR).
110 This is the most complicated level of code generation. The
111 same code is generated as \fB-t\fR, however support is added for
112 forwarding calls to another DLL. The DLL to forward to is
113 given as '\fIdll\fR'.
114 .IP \fB-D\fR
115 Generate documentation.
116 By default, winedump generates a standard comment at the
117 header of each function it generates. Passing this option
118 makes winedump output a full header template for standard
119 Wine documentation, listing the parameters and return value
120 of the function.
121 .IP "\fB-o \fIname\fR"
122 Set the output dll name (default: \fIdll\fR).
123 By default, if winedump is run on DLL 'foo', it creates
124 files 'foo.spec', 'foo_main.c' etc, and prefixes any
125 functions generated with 'FOO_'.  If '-o bar' is given,
126 these will become 'bar.spec', 'bar_main.c' and 'BAR_'
127 respectively.
128 .IP \fB-C\fR
129 Assume __cdecl calls (default: __stdcall).
130 If winebuild cannot determine the calling convention,
131 __stdcall is used by default, unless this option has
132 been given.
133 Unless \fB-q\fR is given, a warning will be printed for every
134 function that winedump determines the calling convention
135 for and which does not match the assumed calling convention.
136 .IP "\fB-s \fInum\fR"
137 Start prototype search after symbol '\fInum\fR'.
138 .IP "\fB-e \fInum\fR"
139 End prototype search after symbol '\fInum\fR'.
140 By passing the \fB-s\fR or \fB-e\fR options you can have winedump try to
141 generate code for only some functions in your DLL. This may
142 be used to generate a single function, for example, if you
143 wanted to add functionality to an existing DLL.
144 .IP "\fB-S \fIsymfile\fR"
145 Search only prototype names found in '\fIsymfile\fR'.
146 If you want to only generate code for a subset of exported
147 functions from your source DLL, you can use this option to
148 provide a text file containing the names of the symbols to
149 extract, one per line. Only the symbols present in this file
150 will be used in your output DLL.
151 .IP \fB-q\fR
152 Don't show progress (quiet).
153 No output is printed unless a fatal error is encountered.
154 .IP \fB-v\fR
155 Show lots of detail while working (verbose).
157 .B Sym mode:
158 .IP \fI<sym>\fR
159 Demangles C++ symbol '\fI<sym>\fR' and then exits.
160 .SH FILES
161 .I function_grep.pl
163 Perl script used to retrieve a function prototype.
166 Files output in
167 .B spec mode
169 .I foo.dll:
171 .I foo.spec
173 This is the .spec file.
175 .I foo_dll.h
177 .I foo_main.c
179 These are the source code files containing the minimum set
180 of code to build a stub DLL. The C file contains one
181 function, FOO_Init, which does nothing (but must be
182 present).
184 .I Makefile.in
186 This is a template for 'configure' to produce a makefile. It
187 is designed for a DLL that will be inserted into the Wine
188 source tree.
190 .I foo_install
192 A shell script for adding
193 .I foo
194 to the Wine source tree.
195 .SH BUGS
196 C++ name demangling is currently under development. Since the
197 algorithm used is not documented, it must be decoded. Many simple
198 prototypes are already working however.
199 .SH AUTHORS
200 Jon P. Griffiths <jon_p_griffiths at yahoo dot com>
202 Michael Stefaniuc <mstefani at redhat dot com>
203 .SH "SEE ALSO"
204 .BR winedump "'s README file"
206 The Winelib User Guide
208 The Wine Developers Guide