ReceiveTempSMS
/
Sweden-Number
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

- remove from README the stuff that's already in the man page 

- more stuff goes from README to the man page
- spelling fixes
This commit is contained in:
Michael Stefaniuc 2004-04-09 19:06:29 +00:00 committed by Alexandre Julliard
parent 062080d633
commit c95385a358
2 changed files with 48 additions and 227 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

246
tools/winedump/README
View File

@ -6,33 +6,33 @@ Background
Most of the functions available in Windows, and in Windows applications, are
made available to applications from DLL's. Wine implements the Win32 API by
providing replacement's for the essential Windows DLLs in the form of Unix
providing replacement's for the essential Windows DLL's in the form of Unix
shared library (.so) files, and provides a tool, winebuild, to allow Winelib
applications to link to functions exported from shared libraries/DLLs.
applications to link to functions exported from shared libraries/DLL's.
The first thing to note is that there are many DLLs that aren't yet
The first thing to note is that there are many DLL's that aren't yet
implemented in Wine. Mostly this doesn't present a problem because the native
Win32 versions of lots of DLLs can be used without problems, at least on
Win32 versions of lots of DLL's can be used without problems, at least on
x86 platforms. However, one of Wine's goals is the eventual replacement of
every essential O/S DLL so that the whole API is implemented. This not only
means that a copy of the real O/S is not needed, but also that non-x86
platforms can run most Win32 programs after recompiling.
The second thing to note is that applications commonly use their own or 3rd
party DLLs to provide functionality. In order to call these functions with
party DLL's to provide functionality. In order to call these functions with
a Winelib program, some 'glue' is needed. This 'glue' comes in the form of
a .spec file. The .spec file, along with some dummy code, is used to create
a Wine .so corresponding to the Windows DLL. The winebuild program can then
resolve calls made to DLL functions to call your dummy DLL. You then tell
Wine to only use the native Win32 version of the DLL, and at runtime your
calls will be made to the Win32 DLL. If you want to reimplement the dll,
calls will be made to the Win32 DLL. If you want to re-implement the dll,
you simply add the code for the DLL calls to your stub .so, and then tell
Wine to use the .so version instead [1].
These two factors mean that if you are:
A: Reimplementing a Win32 DLL for use within Wine, or
B: Compiling a Win32 application with Winelib that uses x86 DLLs
B: Compiling a Win32 application with Winelib that uses x86 DLL's
Then you will need to create a .spec file (amongst other things). If you
won't be doing either of the above, then you won't need winedump.
@ -40,9 +40,9 @@ won't be doing either of the above, then you won't need winedump.
Creating a .spec file is a labour intensive task during which it is easy
to make a mistake. The idea of winedump is to automate this task and create
the majority of the support code needed for your DLL. In addition you can
have winedump create code to help you reimplement a DLL, by providing
have winedump 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 DLLs functions.
the parameters, calling conventions, and return values of the DLL's functions.
You can think of winedump as somewhat similar to the IMPLIB tool when
only its basic functionality is used. In addition, winedump can be used to
@ -51,89 +51,10 @@ dump other information from PE files; See the section 'Dumping' below.
Usage
-----
Winedump is a command line tool. For the list of options and the basic usage
see the the winedump(1) man page.
Winedump is a command line tool. Running it with no arguments or passing
it '-h' on the command line lists the available options:
Usage: winedump [-h | sym <sym> | spec <dll> | dump <dll>] [mode options]
Winedump can be used in several different modes. The first argument to the
program determines the mode winedump will run in.
-h Help mode. Basic usage help is printed.
sym Symbol mode. Used to demangle C++ symbols
spec For generating .spec files and stub DLL's
dump To dump the contents of a PE file.
[mode options] depend on the mode given as the first argument.
Help mode:
No options are used. The program prints help and then exits
Sym mode:
<sym> Demangles C++ symbol <sym>' and then exits.
Spec mode:
<dll> Use dll for input file and generate implementation code
-I dir Look for prototypes in 'dir' (implies -c)
-c Generate skeleton code (requires -I)
-t TRACE arguments (implies -c)
-f dll Forward calls to 'dll' (implies -t)
-D Generate documentation
-o name Set the output dll name (default: dll)
-C Assume __cdecl calls (default: __stdcall)
-s num Start prototype search after symbol 'num'
-e num End prototype search after symbol 'num'
-S symfile Search only prototype names found in 'symfile'
-q Don't show progress (quiet).
-v Show lots of detail while working (verbose).
Dump mode:
<dll> Dumps the content of the dll named <dll>
-C Turns on symbol demangling
-f Dumps file header information
-j sect_name Dumps only the content of section sect_name (import, export, debug)
-x Dumps everything
Each modes options are explained below.
Spec mode: Basic options
------------------------
OPTION: -o name Set the output dll name (default: dll)
By default, if winedump is run on DLL 'foo', it creates files called
'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. See below
for more information.
OPTION: -q Don't show progress (quiet).
-v 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. Giving -q means nothing will be printed unless a fatal
error occurs, and could be used when calling winedump from a script.
OPTION: -C Assume __cdecl calls (default: __stdcall)
This option determines the default calling convention used by the functions
in the DLL. If specbuild cannot determine the convention, __stdcall is
used by default, unless this option has been given.
Unless -q 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.
Spec mode: Generating stub DLLS
Spec mode: Generating stub DLL's
-------------------------------
If all you want to do is generate a stub DLL to allow you to link your
@ -214,37 +135,25 @@ If you have problems with this step, you can post to the wine-devel mailing
list for help. The build process can change regularly and winebuild may lag
behind in support.
NOTE: **DO NOT** submit patches to Wine for 3rd party DLLs! Building DLLs
NOTE: **DO NOT** submit patches to Wine for 3rd party DLL's! Building DLL's
into your copy of the tree is just a simple way for you to link. When
you release your application you won't be distributing the Unix .so
anyway, just the Win32 DLL. As you update your version of Wine
you can simply re-run the procedure above (Since no patches are
involved, it should be pretty resiliant to changes).
involved, it should be pretty resilient to changes).
Spec mode: Advanced Options
---------------------------
This section discusses features of winedump that are useful to Wine Hackers
or developers looking to reimplement a Win32 DLL for Unix. Using these
or developers looking to re-implement a Win32 DLL for Unix. Using these
features means you will need to be able to resolve compilation problems and
have a general understanding of Wine programming.
OPTION: -I dir Look for prototypes in 'dir' (implies -c)
For all advanced functionality, you must give winedump a directory or file that
contains prototypes for the DLL. In the case of Windows DLLs, this could be
either the standard include directory from your compiler, or an 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 'dir' 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 'dir'. Winedump may still
be able to generate some working stub code for you.
contains prototypes for the DLL.
Once you have created your DLL, if you generated code (see below), you can
backup the DLL header file created and use it for rebuilding the DLL (you
@ -264,45 +173,6 @@ You can compile function_grep.pl for a slight increase in performance; see
'man perlcc' for details.
OPTION: -s num Start prototype search after symbol 'num'
-e num End prototype search after symbol 'num'
By passing the -s or -e 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.
They is also useful for debugging problems, in conjunction with -v.
OPTION: -S symfile Search only prototype names found in 'symfile'
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.
OPTION: -D 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.
OPTION: -c Generate skeleton code (requires -I)
This option tells winedump that you want to create function stubs for
each function in the DLL. This is the most basic level of code generation.
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 -I argument are scanned for a function prototype. If one is found it
is used for the next step of the process, code generation.
Note: C++ name demangling is currently under development. Since the algorithm
used is not documented, it must be decoded. Many simple prototypes are already
working however.
If winedump does not find a prototype, it emits code like the following:
In the .spec file:
@ -347,17 +217,6 @@ demangled C++, the first argument will be called '_this' if an implicit this
pointer is passed (i.e. the function is a non-static class member function).
OPTION: -t TRACE arguments (implies -c)
This option produces the same code as -c, except that arguments are printed
out when the function is called, so the FIXME in the above example becomes:
FIXME("(%s) stub", pszFileName);
Structs that are passed by value are printed as "struct", and functions
that take variable argument lists print "...".
OPTION: -f dll Forward calls to 'dll' (implies -t)
This is the most complicated level of code generation. The same code is
@ -380,7 +239,7 @@ As for -c.
.c
A variable "hDLL" is added to hold a pointer to the DLL to forward to, and
the initialisation code in ZIPEXTRA_Init is changed to load and free the
the initialization code in ZIPEXTRA_Init is changed to load and free the
forward DLL automatically:
HMODULE hDLL = 0; /* DLL to call through to */
@ -419,7 +278,7 @@ This allows you to investigate the workings of a DLL without interfering in
its operation in any way (unless you want to).
In the example I have been using, we probably should have used the -o option
to change the ouput name of our DLL to something else, and used the -f
to change the output name of our DLL to something else, and used the -f
option to forward to the real zipextra DLL:
winedump spec zipextra -f zipextra -o myzipextra -I "~/zipextra/include/*h"
@ -442,7 +301,7 @@ around. This is an aid in reimplementing the DLL, since we can add code for a
function, print the results, and then call the real DLL and compare. Only
when our code is the same do we need to remove the function pointer and the
call to the real DLL. A similar feature in wine is +relay debugging. Using a
fowarding DLL allows more granular reporting of arguments, because you can
forwarding DLL allows more granular reporting of arguments, because you can
write code to dump out the contents of types/structures rather than just
their address in memory. A future version of winedump may generate this
code automatically for common Win32 types.
@ -455,7 +314,7 @@ Spec mode: Problems compiling a DLL containing generated code
Unless you are very lucky, you will need to do a small amount of work to
get a DLL generated with -c, -t or -f to compile. The reason for this is
that most DLLs will use custom types such as structs whose definition
that most DLL's will use custom types such as structs whose definition
is not known to the code in the DLL.
Heres an example prototype from crtdll:
@ -471,7 +330,7 @@ general this is not an issue, but you need to be aware of such issues if you
encounter problems with your forwarding DLL).
For third party (non C++) DLL's, the header(s) supplied with the DLL can
normally be added as an include to the generated DLL header. For other DLLs
normally be added as an include to the generated DLL header. For other DLL's
I suggest creating a separate header in the DLL directory and adding any
needed types to that. This allows you to rebuild the DLL at whim, for example
if a new version of winedump brings increased functionality, then you
@ -547,7 +406,7 @@ Now uncomment the line that winedump inserted into msvcrt.spec:
And recompile Wine.
Finally, we must tell Wine to only use the builtin msvcrt.dll and to only use
Finally, we must tell Wine to only use the built in msvcrt.dll and to only use
the native (Win32) ms_msvcrt.dll. Add the following two lines to ~/.wine/config
under the [DllOverrides] section:
@ -564,61 +423,6 @@ arguments on the way.
At this point you are ready to start reimplementing the calls.
Sym mode: Demangling
--------------------
If you need to demangle a single C++ symbol, you can use the demangling mode
of winedump. This is useful for testing the demangler or implementing
C++ functions in partially implemented wine DLLS. As an example:
winedump sym "??3@YAXPAX@Z"
Gives:
void __cdecl _global_operator_delete_1(void * arg0)
Which is enough information to begin implementing the function.
Dump Mode: Dumping a PE file
----------------------------
Another use for this tool is to diplay information about a 32bit DLL or PE
format image file. When used in this way winedump functions similarly to tools
such as pedump provided by many Win32 compiler vendors.
Usage:
winedump dump <dllname.dll> [switches]
dump mode switches:
-h Display this help message
-C Turns on symbol demangling
-f Dump file header information
-j dir_name Dump only the contents of directory dir_name (import, export, debug)
-x Dump everything
Dump Mode: Options
------------------
OPTION: -x Dump everything
This command prints all available information 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.
If you are only interested in a subset of the available information, you can
use one of the following switches:
OPTION: -f Dump file header information-x Dump everything
This option dumps only the standard PE header structures, along with the COFF
sections available in the file.
OPTION: -j dir_name Dump directory dir_name (import, export, debug)
To dump only a given directory, specify them using this option. Currently only
the import, export and debug directories are implemented.
Final comments
--------------
@ -630,7 +434,7 @@ I want to know what _E and _G represent.
If you encounter a C++ symbol that doesn't demangle **AND** you have the
prototype for it, please send me the symbol as reported by winedump and the
prototype. The more examples I have the easier it is to decypher the scheme,
prototype. The more examples I have the easier it is to decipher the scheme,
and generating them myself is very slow.
Finally, although it is easy to generate a DLL, I _very strongly_ suggest that
@ -645,5 +449,5 @@ Please send questions and bug reports to jon_p_griffiths@yahoo.com.
References
----------
[1] See the Wine and Wine.conf man pages for details on how to tell Wine
whether to use native (Win32) or internal DLLs.
[1] See the wine and wine.conf man pages for details on how to tell Wine
whether to use native (Win32) or internal DLL's.

29
tools/winedump/winedump.man
View File

@ -15,7 +15,7 @@ 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
B: Compiling a Win32 application with Winelib that uses x86 DLL's
.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.
@ -26,13 +26,17 @@ can then resolve calls made to DLL functions.
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 reimplement a
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 DLLs functions.
return values of the DLL's functions.
.PP
\fBwinedump\fR can be also used to dump other information from PE files
or to demangle C++ symbols.
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
@ -72,13 +76,16 @@ option. Currently only the import, export and debug
directories are implemented.
.IP \fB-x\fR
Dumps everything.
This command prints all available information 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.
.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
Windows DLL's, 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
@ -105,6 +112,8 @@ for the next step of the process, code generation.
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
@ -125,6 +134,7 @@ 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,
@ -153,6 +163,13 @@ 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