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 currently under development. Since the
 215 algorithm used is not documented, it must be decoded. Many simple
 216 prototypes are already working however.
 217 .SH AUTHORS
 218 Jon P. Griffiths <jon_p_griffiths at yahoo dot com>
 219 .nf
 220 Michael Stefaniuc <mstefani at redhat dot com>
 221 .SH "SEE ALSO"
 222 .BR winedump "'s README file"
 223 .nf
 224 The Winelib User Guide
 225 .nf
 226 The Wine Developers Guide