@title{The Wine Reference Manual} @subtitle{Edition 0.0.5, February 1998}
@author{The Wine Team}
Copyright (C) 1997, 1998 The Wine authors.
See section The Wine Authors,
for a list of the copyright holders.
Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.
Permission is granted to copy and distribute modified versions of this manual under the conditions stated in the section entitled "License, Warranty, and Authors of Wine".
FIXME: UNIX and POSIX trademarks.
X11
Microsoft, Windows, MS-Windows, Windows-NT, Windows 95, and MS-DOS are
registered trademarks of Microsoft Corporation.
NT is a trademark of Northern Telecom Limited.
C++Builder is a trademark of Borland International, Inc.
Postscript is a registered trademark of Adobe Systems Inc.
Other trademarks are the property of their respective owners, which may
be registered in certain jurisdictions.
The Wine license, warranty, and list of authors together form the copyright for Wine. Read these sections carefully.
Wine is distributed under the following copyright.
You may without charge, royalty or other payment, copy and distribute copies of this work and derivative works of this work in source or binary form provided that: (1) you appropriately publish on each copy an appropriate copyright notice; (2) faithfully reproduce all prior copyright notices included in the original work (you may also add your own copyright notice); and (3) agree to indemnify and hold all prior authors, copyright holders and licensors of the work harmless from and against all damages arising from use of the work. You may distribute sources of derivative works of the work provided that (1) (a) all source files of the original work that have been modified, (b) all source files of the derivative work that contain any party of the original work, and (c) all source files of the derivative work that are necessary to compile, link and run the derivative work without unresolved external calls and with the same functionality of the original work ("Necessary Sources") carry a prominent notice explaining the nature and date of the modification and/or creation. You are encouraged to make the Necessary Sources available under this license in order to further the development and acceptance of the work.
EXCEPT AS OTHERWISE RESTRICTED BY LAW, THIS WORK IS PROVIDED WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES OF ANY KIND, INCLUDING BUT NOT LIMITED TO, ANY IMPLIED WARRANTIES OF FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY OR TITLE. EXCEPT AS OTHERWISE PROVIDED BY LAW, NO AUTHOR, COPYRIGHT HOLDER OR LICENSOR SHALL BE LIABLE TO YOU FOR DAMAGES OF ANY KIND, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
Wine is available thanks to the work of: Bob Amstadt, Dag Asheim, Martin Ayotte, Karl Backström, Peter Bajusz, Marcel Baur, Georg Beyerle, Ross Biro, Martin Boehme, Uwe Bonnes, Erik Bos, Fons Botman, John Brezak, Andrew Bulhak, John Burton, Niels de Carpentier, Gordon Chaffee, Jimen Ching, David A. Cuthbert, Huw D. M. Davies, Roman Dolejsi, Frans van Dorsselaer, Chris Faherty, Carsten Fallesen, Paul Falstad, David Faure, Claus Fischer, Olaf Flebbe, Chad Fraleigh, Peter Galbavy, Ramon Garcia, Matthew Ghio, Jody Goldberg, Hans de Graaff, Charles M. Hannum, Adrian Harvey, John Harvey, Cameron Heide, Jochen Hoenicke, Onno Hovers, Jeffrey Hsu, Miguel de Icaza, Jukka Iivonen, Lee Jaekil, Alexandre Julliard, Bang Jun-Young, Pavel Kankovsky, Jochen Karrer, Andreas Kirschbaum, Albrecht Kleine, Eric Kohl, Jon Konrath, Alex Korobka, Greg Kreider, Anand Kumria, Scott A. Laird, David Lee Lambert, Andrew Lewycky, Martin von Loewis, Michiel van Loon, Kenneth MacDonald, Peter MacDonald, William Magro, Juergen Marquardt, Ricardo Massaro, Marcus Meissner, Graham Menhennitt, David Metcalfe, Bruce Milner, Steffen Moeller, Andreas Mohr, James Moody, Philippe De Muyter, Itai Nahshon, Kristian Nielsen, Henrik Olsen, Michael Patra, Dimitrie O. Paun, Jim Peterson, Robert Pouliot, Keith Reynolds, Slaven Rezic, John Richardson, Rick Richardson, Doug Ridgway, Bernhard Rosenkraenzer, Johannes Ruscheinski, Thomas Sandford, Constantine Sapuntzakis, Pablo Saratxaga, Daniel Schepler, Peter Schlaile, Ulrich Schmid, Bernd Schmidt, Ingo Schneider, Victor Schneider, Yngvi Sigurjonsson, Stephen Simmons, Rick Sladkey, William Smith, Dominik Strasser, Vadim Strizhevsky, Bertho Stultiens, Erik Svendsen, Tristan Tarrant, Andrew Taylor, Duncan C Thomson, Goran Thyni, Jimmy Tirtawangsa, Jon Tombs, Linus Torvalds, Gregory Trubetskoy, Petri Tuomola, Michael Veksler, Sven Verdoolaege, Ronan Waide, Eric Warnke, Manfred Weichel, Morten Welinder, Len White, Lawson Whitney, Jan Willamowius, Carl Williams, Karl Guenter Wuensch, Eric Youngdale, James Youngman, Nikita V. Youshchenko, Mikolaj Zalewski, John Zero, and Luiz Otavio L. Zorzella.
These persons also hold the copyright on Wine.
The overall coordination is done by
Alexandre Julliard
@email{julliard@lrc.epfl.ch}
Wine: the WINdows Emulator, or Wine Is Not an Emulator
FIXME: make an easy-readable fluent text out of this.
Welcome to The Wine Reference Manual. This is edition 0.0.4, last updated February 1998.
What is Wine?
Wine is a program that allows running MS-Windows programs under X11.
Wine incorporates two features, the program loader and Winelib:
Status
Wine is still at development stage. The file `ANNOUNCE' says, "This is still a developer's only release. There are many bugs and many unimplemented API features. Most applications still do not work correctly." See section The Wine Warranty, for additional information.
Requirements
Wine needs an 80x86 CPU to run on. Emulating the CPU is currently not possible.
Currently, you must have one of:
You need X11, and you must have `libXpm' installed on your system.
Availability
Wine is free software. The file `README' says, "Basically, you can do anything with it, except claim that you wrote it." See section License, Warranty, and Authors of Wine, for more information.
Performance
Wine is expected to run MS-Windows binaries about the same speed as MS-Windows would. However, be aware that the 16 bit versions of MS-Windows programs are generally slower than their 32 bit counterparts.
Further information
You should consult the files `README', `ANNOUNCE', `RELEASE-NOTES', `BUGS', `LICENSE', and `WARRANTY', in the root directory of the Wine distribution.
The Wine FAQ, available from
@url{ftp://ftp.asgardpro.com/wine/dave/Wine.FAQ},
@url{ftp://tsx-11.mit.edu/pub/linux/ALPHA/Wine/Wine.FAQ},
@url{ftp://rtfm.mit.edu/pub/usenet-by-group/comp.emulators.ms-windows.wine/WINE_(WINdows_Emulator)_Frequently_Asked_Questions},
@url{ftp://sunsite.unc.edu/pub/Linux/ALPHA/wine/Wine.FAQ},
@url{http://www.asgardpro.com/wine/index.html},
gives answer to a lot of questions.
The Wine USENET newsgroup is interesting for developers. It discusses technical matters about Wine. The address is: @url{news:comp.emulators.ms-windows.wine}.
See section The Wine project, if you consider contributing some work.
This section describes functions for manipulating dates and times. This includes the current time, the creation or manipulation times of files and other objects, and conversion between different time representations.
File times in Wine are specified by the data type FILETIME,
defined in `windows.h'.
The definition of FILETIME reads:
typedef struct
{
INT32 dwLowDateTime;
INT32 dwHighDateTime;
} FILETIME, *LPFILETIME;
The FILETIME structure may be used to hold absolute or relative
times. Absolute times are given as the number of 100 nanoseconds
intervals elapsed since 1 January 1601, 00:00:00 UTC (Coordinated
Universal Time, which is GMT, Greenwich Mean Time). This might be
called the epoch for file times. With a signed 64-bit value, this
representation covers absolute times of 29247 years around the epoch.
To convert this type to local time, use the function
FileTimeToLocalFileTime.
Differences to MS-Windows:
In MS-Windows, the elements of the structure are apparently of type
DWORD. Whether the full 64 bit value is interpreted as signed or
unsigned I do not know.
The Wine function CompareFileTime compares two file times, and
returns whether the first time is less than, equal to, or greater than
the second file time. It is defined in `windows.h'.
1, if time_1 is greater than
time_2, -1 if it is less, and 0 if both times are
equal.
Conformance to MS-Windows:
Present in Windows 95 and Windows NT.
Differences to MS-Windows:
No differences known.
Completion status:
Not yet implemented.
This section describes all input/output of a process, except for two topics: communication with other processes, and communication with the windowing system.
These functions are concerned with operating on files themselves, rather than on their contents.
The file information structure of Wine is used to obtain information about files. It is declared in the header `winedows.h'.
int dwFileAttributes
FILETIME ftCreationTime
FILETIME ftLastAccessTime
FILETIME ftLastWriteTime
int dwVolumeSerialNumber
int nFileSizeHigh
int nFileSizeLow
int nNumberOfLinks
int nFileIndexHigh
int nFileIndexLow
The definition of BY_HANDLE_FILE_INFORMATION reads:
typedef struct
{
int dwFileAttributes;
FILETIME ftCreationTime;
FILETIME ftLastAccessTime;
FILETIME ftLastWriteTime;
int dwVolumeSerialNumber;
int nFileSizeHigh;
int nFileSizeLow;
int nNumberOfLinks;
int nFileIndexHigh;
int nFileIndexLow;
} BY_HANDLE_FILE_INFORMATION ;
The BY_HANDLE_FILE_INFORMATION structure can be obtained by the
GetFileInformationByHandle function (see section Getting file information, for
details).
Differences to MS-Windows:
In MS-Windows, the int elements of the structure are apparently
of type DWORD.
The file attributes in a file information structure and in other structures are a logical or of one or more of the following constants:
The functions in this section describe how to get information about files.
The Wine function GetFileInformationByHandle returns a file
information structure. It is defined in `windows.h'.
TRUE on success, FALSE on failure.
Conformance to MS-Windows:
Present in Windows 95 and Windows NT.
Differences to MS-Windows:
The Wine function can of course only give back information that is
accessible in the UNIX file system. File times are produced in a
granularity of full seconds. Most file attributes are not present in the
UNIX file system. See section The file attributes in a file information structure, for details. The volume
serial number is set to 0.
The Wine function GetFileTime returns the creation time and
the times of last the read and modification access to a file. It is
defined in `windows.h'.
FILETIME
variables, which are filled with a value that indicates an absolute time
in UTC. See section Type FILETIME, for details. If you do not need some of
the times, you can pass a NULL pointer.
The function returns TRUE on
success, FALSE on failure.
Conformance to MS-Windows:
Present in Windows 95 and Windows NT.
Differences to MS-Windows:
The file times are produced in a granularity of full seconds, due to the
underlying UNIX file system.
The Wine function GetFileAttributes returns the file attributes
for a file. It is defined in `windows.h'.
Conformance to MS-Windows:
Present in Windows 95 and Windows NT.
Differences to MS-Windows:
Most file attributes are not present in the
UNIX file system. See section The file attributes in a file information structure, for details.
This section deals with API functions for handling DLL's (dynamic link libraries). It does not describe DLL's themselves; nor does it give information on how Wine handles DLL's. See section The `build' program, for information on how DLL's are integrated into Wine.
This chapter describes some of the tools that are used by Wine. These are not user-level programs which the user of Wine will run. See section Programs for such programs.
Tools are internal programs that are used to help compile or configure Wine.
Wine contains several modules that implement various DLL's which are required to run MS-Windows programs.
The `build' program, located in the `tools/' directory, is used to create the bindings for the DLL entry points of the API functions. This program reads a `.spec'-file in the `if1632' directory and creates the assembly code that translates the function arguments correctly.
FIXME: where in Wine are the DLL's affixed?
FIXME: write a description
See section Implementing an API function, for notes on using this program.
This subsection describes the format of the `.spec'-files.
A `.spec'-file contains the information about the functions, variables, and constants that are contained in a DLL (dynamic link library).
To be able to interpret the contents of a `.spec'-file, you must know about the concept of ordinals.
The `.spec'-file contains a header and a sequence of declarations. Each declaration describes an ordinal.
The header gives general information about the DLL and its properties.
Ordinal declarations are optional. That means that there is a default behaviour assigned to ordinals which are not mentioned in the `.spec'-file. The default handler function of an ordinal will print an error message when called.
Comments are indicated by hash marks (`#'); everything between a hash mark and the end of the line is ignored.
Empty lines are allowed.
FIXME: is that so?
All references to DLL objects like functions or variables are indexed by unique nonnegative numbers. These numbers are called ordinals. Apparently, a program can refer to a DLL function or variable by specifying its name or its ordinal. Although reference by name is the common usage, some program parts (notably DLL's themselves) sometimes refer to DLL entries by ordinal. Therefore, the ordinals cannot be chosen arbitrarily.
Regular programs that are compiled and linked against MS-Windows DLL's will import DLL functions by name. This is therefore the default behaviour. Most DLL functions will be imported by name in all cases. Apparently, the WIN32 DLL's even show some difference in the mapping of functions and ordinals on Windows NT and Windows 95. For most DLL functions, the ordinal number will not matter.
There are some exceptions to that. Notable the KERNEL32 ordinals below 100 are (presently) unnamed and undocumented functions which can only be imported by ordinal. These functions are called by some MS-Windows programs. Also the `shell32.dll' functions are reported to be imported by ordinal in some other DLL's.
See section Official and unofficial documentation on the MS-Windows API, for sources of further information.
The `.spec'-file starts with two mandatory definitions. The first line gives the name of the DLL which the `.spec'-file describes,
name NAME
where NAME is the name of the DLL. The next line defines the type of the DLL,
type TYPE
with TYPE being either `win16' or `win32'.
An optional statement of the form
base ORDINAL
can be used to define the offset of the first ordinal. ORDINAL
must be an integer number. If no base is specified, the offset is zero.
FIXME: is this the offset of the first or an offset that is added to all
ordinals?
what is the offset? Is it added to the ordinals, or is it an address, or
xxx?
An optional statement like
heap SIZE
can be used to define the size of the module local heap. This is only used for WIN16 DLL's. The local heap is the place where the segments of 16 bit programs can locally allocate memory, without interfering with one another. The default size of the local heap, if not specified, is 0.
FIXME: to my impression, a local heap in DLL's would only be required
if DLL functions used it. As all DLL functions in Wine are truly 32 bit
functions that are mapped from 16 bit on being called and back to 16 bit
on returning, a local heap should never be necessary.
If I receive a confirmation of that here, I will state so. Otherwise I
am missing some information on local heaps.
But why is a heap defined in user.spec and gdi.spec?
You can declare an ordinal that holds data. Data items may be of 8, 16, or 32 bit in size.
ORDINAL VARTYPE EXPORTNAME (DATA [DATA ...])
ORDINAL is the ordinal number corresponding to the variable. VARTYPE must be `byte', `word', or `long', for 8, 16, or 32 bits respectively. EXPORTNAME will be the name available for dynamic linking. DATA can be a decimal number or a hex number preceded by `0x'. Each DATA item defines a unit of storage.
The following example defines the variable `VariableA' at ordinal 2, containing 4 bytes:
2 byte VariableA(-1 0xff 0 0)
ORDINAL FUNCTYPE EXPORTNAME ([ARGTYPE ... ]) HANDLERNAME
ORDINAL is the ordinal number corresponding to the function. FUNCTYPE must be chosen from this table:
EXPORTNAME specifies the name (prototype) available for dynamic linking.
ARGTYPE must be chosen from this table:
HANDLERNAME is the name of the actual Wine function that will process the request in 32-bit mode.
Here are some examples. The first example defines an entry point for the
CreateWindow() call (the ordinal 100 is just an example):
100 pascal CreateWindow(ptr ptr long s_word s_word s_word s_word
word word word ptr) WIN_CreateWindow
The second example defines an entry point for the GetFocus() call
(again, the ordinal 100 is an example):
100 pascal GetFocus() WIN_GetFocus()
To declare a function that uses a variable number of arguments, specify
the function as taking no arguments. In this special case, in WIN32
the called function will be passed a pointer to the first arg; in
WIN16, the args are available as CURRENT_STACK16->args.
FIXME: create a reference here
See the wsprintf* functions in `user.spec' and
`user32.spec' for an example.
Sometimes it is not known how many arguments an undocumented DLL function takes. See section Official and unofficial documentation on the MS-Windows API, for some hints on how to proceed in such a case.
The `.spec'-files offer the possibility to use some special entries. These entries are used for stubs (which allow linking for non-existing functions), dummy functions that do not perform any operations, Wine symbols that must be referenced directly, and constant values.
Stub ordinals
This pseudo function type defines a stub function. It makes the name and ordinal available for dynamic linking, but will terminate execution with an error message if the function is ever called.
ORDINAL stub EXPORTNAME
ORDINAL is the ordinal number corresponding to the function. EXPORTNAME specifies the name (prototype) available for dynamic linking.
Return ordinals
This pseudo function type defines a function entry point whose handler should do nothing but return a value.
ORDINAL return EXPORTNAME ARGLENGTH RETVALUE
ORDINAL is replaced by the ordinal number corresponding to the function. ARGLENGTH is the number of bytes that need to be removed from the stack before returning to the caller. See section Investigating the undocumented API, for an explanation of the stdcall calling convention. RETVALUE is the return value which will be passed back to the caller.
Extern ordinals
ORDINAL extern EXPORTNAME SYMBOLNAME
This type defines an entry that simply maps to a Wine symbol (variable or function); EXPORTNAME will point to the symbol SYMBOLNAME that must be defined in C code. This type only works with WIN32.
Equate ordinals
ORDINAL equate EXPORTNAME DATA
This type defines an ordinal as an absolute value. ORDINAL is replaced by the ordinal number corresponding to the entry. EXPORTNAME will be the name available for dynamic linking. DATA can be a decimal number or a hex number preceeded by `0x'.
FIXME: write installation guide
See section Creating patches, for instructions on creating patches.
cd to the top source directory for Wine, and run
patch -p1 < patchfile.
What needs to be done next depends to some extent on what the
patch touches. For small patches which only alter C source, it can be
enough to rerun make. In general, the sequence configure,
make depend, make is sufficient, unless the patch alters
[config.in], in which case you must regenerate configure
via make configure (which just runs autoconf).
If you are new to Wine and want to support this project, here are some suggestions.
See section Debugging, for advice on how to debug Wine. See section Applying patches, for instructions on applying patches.
Official documentation
For documentation on WIN32 API functions, you might try one of these sources:
Unofficial documentation
Not all of the WIN32 API is well documented. Some functions are obscured, and undocumented. See section Ordinals, for information about undocumented functions imported by ordinal. Getting to know what these functions do can be tiresome and tedious. Here is a quote from a news posting concerning two books that might help:
Well actually, there are at least _two_ books that address these problems. One is by Matt Pietrek, "Windows 95 System Programming Secrets", which gives some auxiliary programs for helping ferret out the information, and the other is by Shulman, "Undocumented Windows 95".
See section Ordinals, for some notes on undocumented kernel functions.
But, all in all, @url{news:comp.emulators.ms-windows.wine} says
Unfortunately, short of getting something like NuMega's SoftIce, I don't think there's a "good" reference on the mystery <100 ordinals in KERNEL32.DLL.
Besides reading the documentation in section Official and unofficial documentation on the MS-Windows API, you can find out some properties of API functions on your own.
Sometimes it is not known how many arguments an undocumented DLL function takes. Here is a text from a news posting that gives some hints on how you might proceed in this case.
The problem with implementing stubs for WIN32 functions is that it is not sufficient to return a default value (usually 0) and leave the stack the way we found it. For most WIN32 functions -- those that use the stdcall calling convention -- the arguments sent to the function are removed from the stack.
Some background: On the i386 class of machines, stack entries are
usually dword (4 bytes) in size, little-endian. The stack grows
downward in memory. The stack pointer, maintained in the `esp'
register, points to the last valid entry; thus, the operation of
pushing a value onto the stack involves decrementing `esp' and then
moving the value into the memory pointed to by esp (i.e., push p
in assembly resembles *(--esp) = p; in C). Removing (popping)
values off the stack is the reverse (i.e., pop p corresponds to
p = *(esp++);).
In the stdcall calling convention, arguments are pushed onto the stack right-to-left. For example, the C call
myfunction(40, 20, 70, 30);
is expressed in Intel assembly as:
push 30
push 70
push 20
push 40
call myfunction
In addition, the called function is responsible for removing the arguments off the stack. Thus, before the call to myfunction, the stack would look like:
[local variable or temporary]
[local variable or temporary]
30
70
20
esp -> 40
After the call returns, it should look like:
[local variable or temporary]
esp -> [local variable or temporary]
To restore the stack to this state, the called function must know how many arguments to remove (which is the number of arguments it takes). This is a problem if the function is undocumented.
One way to attempt to document the number of arguments each function takes is to create a wrapper around that function that detects the stack offset. `WinRelay' (see below) was written to create such wrappers. Essentially, each wrapper assumes that the function will take a large number of arguments (by default, 64 in `WinRelay'). The wrapper copies each of these arguments into its stack, calls the actual function, and then calculates the number of arguments by checking esp before and after the call.
The main problem with this scheme is that the function must actually be called from another program. Many of these functions are seldom used. An attempt was made to aggressively query each function in a given library (`ntdll.dll') by passing 64 arguments, all 0, to each function. Unfortunately, Windows NT 4.0 quickly goes to a blue screen of death (bsod), even if the program is run from a non-administrator account.
Another method that has been much more successful is to attempt to
figure out how many arguments each function is removing from the
stack. This instruction, ret hhll (where `hhll' is the
number of bytes to remove, i.e. the number of arguments times 4), contains
the bytes `0xc2 ll hh' in memory. It is a reasonable assumption
that few, if any, functions take more than 16 arguments; therefore,
`hh' is 0x0 and `ll' is less than 0x40. This utility,
`MakeSpec' (see below), simply queries the address of a function
and looks for the first occurrence of the bytes `0xc2 ll 0x0',
where @math{`ll' <= 0x40}.
Of course, this is not without errors. ret 00ll is not the only
instruction that can have the byte sequence `0xc2 ll 0x0'; for
example, push 0x000040c2 has the byte sequence
`0x68 0xc2 0x40 0x0 0x0', which matches the above. Properly, the
utility should look for this sequence only on an instruction boundary;
unfortunately, finding instruction boundaries on an i386 requires
implementing a full disassemble -- quite a daunting task. Besides,
the probability of having such a byte sequence that is not the actual
return instruction is fairly low.
Much more troublesome is the non-linear flow of a function. For example, consider the following two functions:
somefunction1:
jmp somefunction1_impl
somefunction2:
ret 0004
somefunction1_impl:
ret 0008
`MakeSpec' would incorrectly list both somefunction1 and
somefunction2 as taking only a single argument, whereas
somefunction1 really takes two arguments.
With these limitations in mind, it is possible to implement more stubs in Wine and, eventually, the functions themselves.
The program `WinRelay' can be downloaded from @url{http://www.ece.cmu.edu/afs/ece/usr/dacut/www/src}, and `MakeSpec' will be available from the same location. You can compile them with Borland's C++Builder; you should not optimize when compiling (`WinRelay' needs the stack frames).
Here is a checklist that should help you writing your first API type. It will of course not tell you which elements to put into the type (assuming it is a structure), but it should help you along the way of integrating this type into Wine. See section Implementing an API function, for comparison.
Here is a checklist that should help you writing your first API function. It will of course not tell you what to do in the function, but it should help you along the way of integrating this function into Wine.
This section describes Wine's naming scheme for API functions and data types.
The purpose of these naming conventions is to ensure that
A function or data type whose name in the MS-Windows API is xxx will in the Wine code have the following name(s):
xxx16
xxx32
xxx32A
char type). This version always goes together with another
version, using the next suffix.
xxx32W
So, where the MS-Windows API offers one name, Wine actually has two or three different functions implemented (which will hopefully share a large part of the code).
Wine allows to use its API functions in two ways. The emulator part of Wine provides DLL's for the MS-Windows programs it can run. The library part of Wine provides a UNIX programmer with the facility to use the Wine API's in a standard UNIX program.
The emulator part of Wine provides the hooks for dynamically linking the API functions to the MS-Windows executables (`.EXE'-files). The Wine emulator contains all versions (16 or 32 bit, ASCII or Unicode) of the API functions in one executable. The emulator performs a mapping from the MS-Windows name of the function, by which the executable calls it, to one of the Wine internal names that have been used in coding it.
This mapping is done by the built-in DLL handling code of Wine. A programmer of Wine has to declare the function in one of the virtual DLL's that are provided by Wine. The declarations are done in the `.spec'-files in the `if1632/' directory. See section The `build' program, for details.
The MS-Windows application simply calls the API function by its standard MS-Windows name. Wine will apply the correct mapping according to Wine's selected appearance (as a 16 bit or 32 bit emulator, which is a parameter on invocation of Wine).
If Wine is built as a library, and linked to a user-level main program, the user will also use the standard MS-Windows names for the API functions.
Some macros are defined in `include/wintypes.h' which perform the necessary name mappings.
These macros are (see the examples below):
WINELIB16 and WINELIB32. xxx should
be the name of an API function that uses no string arguments.
Use this macro with a #define to establish the API name xxx.
WINELIB16, WINELIB32, and UNICODE. xxx should
be the name of an API function that uses string arguments.
Use this macro with a #define to establish the API name xxx.
WINELIB16 and WINELIB32. xxx should
be the name of an API data type that contains no string arguments.
WINELIB16, WINELIB32, and
UNICODE. xxx should be the name of an API data type that
contains string arguments.
If Wine is compiled as an emulator, these macros have no effect, for the mapping is then done by the DLL code. This means that within Wine the name xxx itself will not be defined.
Note: If the definition of xxx is exactly the same in WIN16 and WIN32, you can simply use the same name as MS-Windows.
Here are some examples:
/* A simple type without strings */
typedef short INT16;
typedef int INT32;
DECL_WINELIB_TYPE(INT);
/* A type with strings */
typedef struct { /* Win32 ASCII data structure */ } WNDCLASS32A;
typedef struct { /* Win32 Unicode data structure */ } WNDCLASS32W;
typedef struct { /* Win16 data structure */ } WNDCLASS16;
DECL_WINELIB_TYPE_AW(WNDCLASS);
/* A function with strings */
ATOM RegisterClass16( WNDCLASS16 * );
ATOM RegisterClass32A( WNDCLASS32A * );
ATOM RegisterClass32W( WNDCLASS32W * );
#define RegisterClass WINELIB_NAME_AW(RegisterClass)
The Winelib user can then say (in the application program):
INT i;
WNDCLASS wc = { ... };
RegisterClass( &wc );
and this will use the correct declaration depending on the definitions
WINELIB16, WINELIB32, and UNICODE.
Here are the primary defines that are used when Wine is compiled as a library:
#define is set, the Wine library is to be compiled in its
16 bit form. That means, the 16 bit variants of all functions will be
used and the appearance of the application linked with the Wine library
will be that of a 16 bit application. Of course, both the application
and the Wine library function really run in 32 bit mode. The switch only
selects the function with the name ending in ...16, which
will perhaps have a behaviour different from its 32 bit counterpart.
#define is set, the Wine library is to be compiled in its
32 bit form. That means, the 32 bit variants of all functions will be
used and the appearance of the application linked with the Wine library
will be that of a 32 bit application.
define is used to select one of two possible 32 bit
variants. Functions and data types of the 32 bit API come in two
flavours: one handling ASCII strings (or rather strings with
characters encoded in 8 bit), the other Unicode strings. This define
selects the correct variant. As a user of the Wine library, you are
responsible to use the correct character type in your part of the
application which accesses the Wine API functions and data types.
These switches are automatically set when Wine is compiled as a library.
Within Wine and during the compilation of Wine, you cannot rely on the MS-Windows names of the API functions and data types. If Wine is compiled as a library, they will be defined; if Wine is compiled as an emulator, they won't.
You therefore have to access all functions and data types by their full names, with the proper suffix explicitly appended. In Wine, the 16 bit and 32 bit versions of the functions are distinct entities, which might (theoretically) show a completely different behaviour. They may even call each other (and they will quite frequently).
Therefore Wine is a conglomerate that contains all two or three flavours of each function at once, and exports to the application whichever of these is appropriate. Remember that inside Wine, there is no memory segmentation, so all functions are 32 bit. The 16-to-32 bit mapping is done on exporting the DLL functions.
See section Applying patches, for instructions on applying patches.
Patches are created with the program diff. You need a copy
of clean source tree to diff against. The `-u' option, to create
unified diffs, is popular but not obligatory.
For changes to a single file,
diff -u wine990101/windows/win.c mywine/windows/win.c > win_patch
is sufficient.
To generate a complete diff between your tree and the distribution,
use diff -uR wine990101 mywine.
This assumes that the original distribution and your personal tree have the same parent directory, from which you make the diff. This ensures a consistent format for the diffs, which in turn is necessary so that they can be applied consistently as described in See section Applying patches.
These are my tips for adding documentation.
Do not simply copy documentation from MS-Windows related material. Except from risking copyright violations, which you would not want to do, there is another aspect to that: As Wine is a product to run on UNIX and UNIX-like workstations, it seems a good idea to me to organize this documentation primarily for the well-trained UNIX reader. Please keep that in mind when you add some documentation.
Finally, read the info pages for texinfo.
The rest of this section provides some templates which can serve as a start in writing documentation.
On the following pages you will find some texinfo templates, which
should help you collaborate on this documentation.
These templates give hints on how to document data types, functions, variables, constants etc. in Wine. As documentation evolves, you will find common features of data types that should be described in a unified fashion. In such a case, please add a corresponding style guide-line here, in this very place, to help keeping documentation of data types unified.
Start out the type or function with a new node. Write a comment before the node, listing all data types (and functions) described in the node, like this:
@c @c *** struct FILETIME *** @c @node Type FILETIME, NextNodeName, PreviousNodeName, ParentNodeName
The node command describes the node name and the names of the next node, the previous node, and the parent node. The parent node should contain a menu entry for this node. The previous node is the node that appears before this node in the parent node menu. The next node is the node succeeding this one in the parent node menu. If there is no previous or next node, omit the name (putting just a single space between the two commata).
The node name must be a unique sequence of words. Case is important, so Type and type are distinct. The node name must not contain special characters like `@, {, }' or the comma. If you need to give a node the same name as a function, data type, etc., use the words `Type', `Function', etc. before the identifier.
Always put the names of the node and its links on the same line, even if it gets rather long.
If there are two or more data types or functions described in the node, adapt the comment like this:
@c @c *** int X *** @c *** long Y() *** @c @node Ints and Longs, NextNodeName, PreviousNodeName, ParentNodeName
After the node name, put a sectioning command, such as `@chapter', `@section', `@subsection', or `@subsubsection'. Without that command, cross references to the node will fail.
@subsubsection Type FILETIME
Start the description of the type(s) or function(s) with a single non-indented paragraph that gives a one-line description of the type(s) or function(s) and states the include files that are required.
@noindent
File times in Wine are specified by the data type @code{FILETIME},
defined in @file{windows.h}.
If several types or functions are closely connected, use one paragraph as a common description. If more paragraphs are required for a proper description, indent all but the first of them.
Then start the definition of the data type or function. Use the proper macro, which you will find defined in the beginning of the texinfo file. If appropriate, add your own macros. Again, put everything that belongs to the header into a single line. Use continuation lines for additional headers.
@deftp_w32 FILETIME @deftpx_w32 LPFILETIME
In the definition, give a verbal explanation of the data type or function. The explanation should be rather complete, exact, and comprehensible, than well-structured. This is the point where you can tell everything you want. Do not be afraid of wasting space. Do not describe the MS-Windows situation but only say what Wine does. That is important. (Sometimes they might even do the same.)
This is the data type for specifying file times. The file times are stored with 64 bit precision. The actual data type is a structure with two 32 bit values which are interpreted as the low and high parts of a 64-bit value. This value gives a time measured in a granularity of 100 nanoseconds, so 1.5 seconds are specified by a value of 15,000,000. In Wine, this 64-bit value is signed, with the sign taken from the high part. The lower part is used as unsigned.
For data types, it is recommended to quote the definition from the header file. For a function, you might give a short example of its usage. You may also put one example in the end of a node that explains several of the functions in the node. Remember that cut-and-paste from a well prepared example will help the readers write their code.
The definition of @code{FILETIME} reads:
@example
typedef struct
@{
INT32 dwLowDateTime;
INT32 dwHighDateTime;
@} FILETIME, *LPFILETIME;
@end example
You could also use the cindex command which creates an entry in
the concept index. The texinfo manual recommends to keep concept
entries distinct, so that a single concept index entry puts to one
well-defined place in the document. Use lower case letters for index
entries, unless they are proper names or quotes from actual code.
@cindex epoch in file time
The @code{FILETIME} structure may be used to hold absolute or relative
times. Absolute times are given as the number of 100 nanoseconds
intervals elapsed since 1 January 1601, 00:00:00 UTC (Coordinated
Universal Time, which is GMT, Greenwich Mean Time). This might be
called the @dfn{epoch} for file times. With a signed 64-bit value, this
representation covers absolute times of 29247 years around the epoch.
After the verbal documentation, you can add some special fields describing bugs, implementation dependencies etc. Two of these are recommended to attach to all descriptions. One describes the conformance of the data type or function to MS-Windows products, i.e. whether the item is also present in Windows NT and Windows 95. The other one describes known differences of the Wine item to its MS-Windows counterpart. Both will greatly help in porting software from MS-Windows to Wine and vice versa.
@winconfall{}
@windiff{}
In @mswindows{}, the elements of the structure are apparently of type
@code{DWORD}. Whether the full 64 bit value is interpreted as signed or
unsigned I do not know.
If you find that more of these property attributes are necessary, feel free to create your own ones. But keep in mind that they should be applicable more or less to all described items. Very special properties will better be put into the verbal text.
Finally end the definition of the data type or function:
@end deftp
Do not forget to enter the node in the menu of its top node, and do properly link the node to its successor and predecessor.
Category: Data type
Functions should be given category names, to indicate which API they belong to. Please add items to the list of categories possible.
Category: WIN32 function
@c
@c ***GetFileTime() ***
@c
@node Get File Times, , Compare File Times, File Times
@noindent
The Wine function @code{GetFileTime} returns the creation time and
the times of last the read and modification access to a file. It is
defined in @file{windows.h}.
@deftypefn_w32 BOOL GetFileTime (@w{HANDLE @var{file},} @w{LPFILETIME @var{ctime},} @w{LPFILETIME @var{atime},} @w{LPFILETIME @var{mtime})}
This function obtains for the specified @var{file} the creation time
@var{ctime}, the time of the last access to the file @var{atime}, and
the time of the last modification (write) to the file, @var{mtime}.
The @var{file} handle must have been obtained by opening the file with
@code{GENERIC_READ} access. The file time arguments of this function are
pointers to @code{FILETIME} variables, which are filled with a value that
indicates an absolute time in UTC. To convert these values to local
times, use the function @code{FileTimeToLocalFileTime}. If you do not
need some of the times, you can pass a @code{NULL} pointer.
The function returns @code{TRUE} on success, @code{FALSE} on failure.
@winconfall{}
@windiffnone{}
@end deftypefn
FIXME:
Presently, all wide character strings in API functions of Wine are internally converted to 8 bit representation. Thus, the WIN32 API with Unicode strings is not fully functional for the application programmer at present.
Even so, application programmers might consider developing their applications in wide character format with Wine, as future versions might bring a change. This might come when a UNIX filesystem can handle Unicode file names.
Furthermore, the Unicode API is required to let Wine run MS-Windows applications which have been compiled for wide character strings.
In Wine, wide characters are strictly 16 bit; the wchar_t type of
standard C can therefore not be used.
This document was generated on 27 May 1998 using the texi2html translator version 1.51.