| .\" -*- nroff -*- |
| .TH WINEDUMP 1 "October 2005" "@PACKAGE_STRING@" "Wine Developers Manual" |
| .SH NAME |
| winedump \- A Wine DLL tool |
| .SH SYNOPSIS |
| .BR "winedump " [ "-h " "| " |
| .BI "sym " "<sym> " |
| | |
| .BI "spec " "<dll> " |
| | |
| .BI "dump " "<file>" |
| .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 |
| B: Compiling a Win32 application with Winelib that uses x86 DLLs |
| .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 |
| Wine .so corresponding to the Windows DLL. The \fBwinebuild\fR program |
| 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 |
| addition you can have \fBwinedump\fR create code to help you re-implement a |
| DLL, by providing tracing of calls to the DLL, and (in some cases) |
| automatically determining the parameters, calling conventions, and |
| return values of the DLL's functions. |
| .PP |
| 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. |
| .SH MODES |
| .B winedump |
| can be used in several different modes. The first argument to the |
| program determines the mode winedump will run in. |
| .IP \fB-h\fR |
| Help mode. |
| Basic usage help is printed. |
| .IP \fBdump\fR |
| To dump the contents of a file. |
| .IP \fBspec\fR |
| For generating .spec files and stub DLLs. |
| .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. |
| The program prints the help info and than exits. |
| .PP |
| .B Dump mode: |
| .IP \fI<file>\fR |
| Dumps the content of the file named \fI<file>\fR. Various file |
| formats are supported (PE, NE, LE, Minidumps, .lnk). |
| .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. |
| .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, |
| tls and clr directories are implemented. |
| For NE files, currently the export and resource directories are |
| implemented. |
| .IP \fB-x\fR |
| Dumps everything. |
| This command prints all available information (including all |
| available directories - see \fB-j\fR option) about the file. You may |
| wish to pipe the output through more/less or into a file, since |
| a lot of output will be produced. |
| .IP \fB-G\fR |
| Dumps contents of debug section if any (for now, only stabs |
| information is supported). |
| .PP |
| .B Spec mode: |
| .IP \fI<dll>\fR |
| Use dll for input file and generate implementation code. |
| .IP "\fB-I \fIdir\fR" |
| Look for prototypes in '\fIdir\fR' (implies \fB-c\fR). In the case of |
| Windows DLLs, this could be either the standard include |
| 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. |
| The '\fIdir\fR' argument can also be a file specification (e.g. |
| "include/*"). If it contains wildcards you must quote it to |
| prevent the shell from expanding it. |
| If you have no prototypes, specify /dev/null for '\fIdir\fR'. |
| Winedump may still be able to generate some working stub |
| code for you. |
| .IP \fB-c\fR |
| Generate skeleton code (requires \fB-I\fR). |
| This option tells winedump to create function stubs for each |
| function in the DLL. As winedump reads each exported symbol |
| 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. |
| Structs that are passed by value are printed as "struct", |
| and functions that take variable argument lists print "...". |
| .IP "\fB-f \fIdll\fR" |
| Forward calls to '\fIdll\fR' (implies \fB-t\fR). |
| 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 |
| given as '\fIdll\fR'. |
| .IP \fB-D\fR |
| Generate documentation. |
| By default, winedump generates a standard comment at the |
| header of each function it generates. Passing this option |
| makes winedump output a full header template for standard |
| Wine documentation, listing the parameters and return value |
| of the function. |
| .IP "\fB-o \fIname\fR" |
| Set the output dll name (default: \fIdll\fR). |
| By default, if winedump is run on DLL 'foo', it creates |
| files 'foo.spec', 'foo_main.c' etc, and prefixes any |
| functions generated with 'FOO_'. If '-o bar' is given, |
| these will become 'bar.spec', 'bar_main.c' and 'BAR_' |
| respectively. |
| This option is mostly useful when generating a forwarding DLL. |
| .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 |
| function that winedump determines the calling convention |
| for and which does not match the assumed calling convention. |
| .IP "\fB-s \fInum\fR" |
| Start prototype search after symbol '\fInum\fR'. |
| .IP "\fB-e \fInum\fR" |
| End prototype search after symbol '\fInum\fR'. |
| By passing the \fB-s\fR or \fB-e\fR options you can have winedump try to |
| 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" |
| Search only prototype names found in '\fIsymfile\fR'. |
| 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). |
| There are 3 levels of output while winedump is running. The |
| default level, when neither -q or -v are given, prints the |
| number of exported functions found in the dll, followed by |
| the name of each function as it is processed, and a status |
| indication of whether it was processed OK. With -v given, a |
| lot of information is dumped while winedump works: this is |
| intended to help debug any problems. |
| .PP |
| .B Sym mode: |
| .IP \fI<sym>\fR |
| Demangles C++ symbol '\fI<sym>\fR' and then exits. |
| .SH FILES |
| .I function_grep.pl |
| .RS |
| Perl script used to retrieve a function prototype. |
| .RE |
| .PP |
| Files output in |
| .B spec mode |
| for |
| .I foo.dll: |
| .nf |
| .I foo.spec |
| .RS |
| This is the .spec file. |
| .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 |
| function, FOO_Init, which does nothing (but must be |
| present). |
| .RE |
| .I Makefile.in |
| .RS |
| This is a template for 'configure' to produce a makefile. It |
| is designed for a DLL that will be inserted into the Wine |
| source tree. |
| .SH BUGS |
| 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. |
| .SH AUTHORS |
| Jon P. Griffiths <jon_p_griffiths at yahoo dot com> |
| .nf |
| Michael Stefaniuc <mstefani at redhat dot com> |
| .SH "SEE ALSO" |
| .BR winedump "'s README file" |
| .nf |
| The Winelib User Guide |
| .nf |
| The Wine Developers Guide |
