     START-INFO-DIR-ENTRY
     * wine: (wine.info).             The Windows Emulator.
     END-INFO-DIR-ENTRY

This file documents Wine, the Windows Emulator.

Copyright © 1997,1998 The Wine authors.

See 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: X11 and POSIX trademarks.

UNIX is a registered trademark of the Open Group. 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.

Wine
****

This is edition 0.0.4, last updated February 1998, of The Wine Reference Manual.

Wine (Wine Is Not an Emulator, or the WINdows Emulator) is both an emulator that runs MS-Windows executables and a library that can be used to compile MS-Windows source code.

Wine is free software. Wine is still in development-only state.

License, Warranty, and Authors of Wine
**************************************

The Wine license, warranty, and list of authors together form the copyright for Wine. Read these sections carefully.

The Wine License
================

Wine is distributed under the following copyright.

          [file LICENSE not included]

The Wine Warranty
=================

          [file WARRANTY not included]

The Wine Authors
================

          [file AUTHORS not included]

These persons also hold the copyright on Wine.

The overall coordination is done by

Alexandre Julliard

julliard@lrc.epfl.ch

Introduction
************

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:

 1. You can run MS-Windows binaries (programs) in Wine. Wine contains a program loader which loads and executes an MS-Windows binary. It uses the Winelib features of Wine to translate WIN32 and WIN16 calls to their UNIX/X11 equivalent.

     Both 16 bit and 32 bit binaries can be loaded.

 2. Winelib: Wine can also be used as a library which implements the MS-Windows API on top of a UNIX or UNIX-like operating system with X11. Winelib (i.e. the Wine library) translates WIN16 or WIN32 API calls to their UNIX/X11 equivalent.

     You can write a user-level application program that calls the WIN16 or WIN32 API functions and compile it on a UNIX box.

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 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:

  * Linux version 0.99.13 or above

  * NetBSD-current

  * FreeBSD-current or FreeBSD 1.1

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 Copying, 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

ftp://ftp.asgardpro.com/wine/dave/Wine.FAQ,

ftp://tsx-11.mit.edu/pub/linux/ALPHA/Wine/Wine.FAQ,

ftp://rtfm.mit.edu/pub/usenet-by-group/comp.emulators.ms-windows.wine/WINE_(WINdows_Emulator)_Frequently_Asked_Questions,

ftp://sunsite.unc.edu/pub/Linux/ALPHA/wine/Wine.FAQ,

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: news:comp.emulators.ms-windows.wine.

See The Wine Project, if you consider contributing some work.

The WIN32 Reference Manual
**************************

Kernel Objects
==============

Processes and Threads
=====================

Users and Groups
================

Date and Time
=============

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
----------

Type FILETIME
.............

File times in Wine are specified by the data type FILETIME, defined in windows.h. _w32  FILETIME _w32 LPFILETIME 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.

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. _w32 LONG CompareFileTime (CONST FILETIME* TIME_1, CONST FILETIME* TIME_2) This function returns 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.

System Information
==================

Memory Management
=================

I/O Facilities
==============

This section describes all input/output of a process, except for two topics: communication with other processes, and communication with the windowing system.

I/O on Files
------------

File System Interface
---------------------

These functions are concerned with operating on files themselves, rather than on their contents.

The file information structure
..............................

The file information structure of Wine is used to obtain information about files. It is declared in the header winedows.h. _w32 BY_HANDLE_FILE_INFORMATION This is the data type for specifying information about files as objects of the file system. It contains the following members:

int dwFileAttributes
     See File attributes, for details.

FILETIME ftCreationTime
     The time when the file was created. See Type FILETIME, for details.

FILETIME ftLastAccessTime
     The time when the file was last accessed. See Type FILETIME, for details.

FILETIME ftLastWriteTime
     The time when the file was last written to. See Type FILETIME, for details.

int dwVolumeSerialNumber
     The serial number of the volume containing the file. In Wine, currently 0.

int nFileSizeHigh
     A 32 bit value which contains the high part of the 64 bit file size.

int nFileSizeLow
     A 32 bit value which contains the low part of the 64 bit file size.

int nNumberOfLinks
     This is the number of hard links to the file. In a file system which does not support hard links, this is 1.

int nFileIndexHigh
     A 32 bit value which contains the high part of the 64 bit file index. The file index is a unique number for a file on a volume. This identifier cannot change while the file is opened by a process. Together with the volume number, the file index is a unique identifier for the file. This can be used by an application to check whether two handles refer to the same file. Wine currently uses the inode number for the file index.

int nFileIndexLow
     A 32 bit value which contains the low part of the 64 bit file index.

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 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
...................................................

The file attributes in a file information structure and in other structures are a logical or of one or more of the following constants:

_cw32 FILE_ATTRIBUTE_READONLY The file is a read-only file. (Wine value: 0x0001).

_cw32 FILE_ATTRIBUTE_HIDDEN The file is a hidden file. Files in Wine do not have this attribute. (Wine value: 0x0002).

_cw32 FILE_ATTRIBUTE_SYSTEM The file belongs to the operating system. Files in Wine do not have this attribute. (Wine value: 0x0004).

_cw32 FILE_ATTRIBUTE_LABEL This is not present in the MS-Windows API. (Wine value: 0x0008).

_cw32 FILE_ATTRIBUTE_DIRECTORY The file is a directory. (Wine value: 0x0010).

_cw32 FILE_ATTRIBUTE_ARCHIVE The file is an archive file. Currently, all non-directory files are reported by Wine to have this attribute. This attribute is normally set by MS-Windows to indicate that a file is to be archived; when the file is archived, the flag is cleared. (Wine value: 0x0020).

_cw32 FILE_ATTRIBUTE_NORMAL The file does not have any other attributes set. This value must be used alone. In Wine, normal files are reported as archive files. (Wine value: 0x0080).

_cw32 FILE_ATTRIBUTE_TEMPORARY The file is used as a temporary storage. Files in Wine do not have this attribute. (Wine value: 0x0100).

_cw32 FILE_ATTRIBUTE_ATOMIC_WRITE This is reserved for future use. Files in Wine do not have this attribute. (Wine value: 0x0200).

_cw32 FILE_ATTRIBUTE_XACTION_WRITE This is reserved for future use. Files in Wine do not have this attribute. (Wine value: 0x0400).

_cw32 FILE_ATTRIBUTE_COMPRESSED The file is compressed. Files in Wine do not have this attribute. (Wine value: 0x0800).

Getting file information
........................

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.

_w32 BOOL GetFileInformationByHandle (HFILE32 FILE, BY_HANDLE_FILE_INFORMATION *INFO) This function obtains for the specified FILE the file information, and stores it in INFO. The file information contains the file attributes, the file times, the volume serial number, the file size, the number of links, and a unique file identifier. 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 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 File attributes, 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.

_w32 BOOL GetFileTime (HANDLE FILE, LPFILETIME CTIME, LPFILETIME ATIME, LPFILETIME MTIME) This function obtains for the specified FILE the creation time CTIME, the time of the last access to the file ATIME, and the time of the last modification (write) to the file, MTIME. The file time arguments of this function are pointers to FILETIME variables, which are filled with a value that indicates an absolute time in UTC. See 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.

_w32 DWORD GetFileAttributes (LPCTSTR NAME) This function looks up the file with name NAME, and returns the attributes of the file. See File attributes, for details on the file attributes. If the function is not successful, it returns a word with all bits set (0xffffffff).

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 File attributes, for details.

Communication
=============

Windows and Graphics
====================

Errors and Exceptions
=====================

Resources
=========

The Registry
============

Dynamic Link Libraries (DLL's)
==============================

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 The build program, for information on how DLL's are integrated into Wine.

Resources and INI Files
***********************

Metafiles --- Icons --- Bitmaps
*******************************

Debugging
*********

Programs
********

Tools
*****

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 Programs for such programs.

Tools are internal programs that are used to help compile or configure Wine.

The build program
=================

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 Implementing an API function, for notes on using this program.

The .spec-files
---------------

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 general format
..................

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?

Ordinals
........

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 Getting information on the API, for sources of further information.

The header of a .spec-file
..........................

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?

Variable entry points of .spec-files
....................................

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)

Function entry points of .spec-files
....................................

     ORDINAL FUNCTYPE EXPORTNAME ([ARGTYPE ... ]) HANDLERNAME

ORDINAL is the ordinal number corresponding to the function. FUNCTYPE must be chosen from this table:

pascal16
     A WIN16 function that returns a 16 bit value.

pascal
     A WIN16 function that returns a 32 bit value.

register
     A function using CPU registers to pass arguments.

stdcall
     A normal WIN32 function. See Investigating the undocumented API, for an explanation of the stdcall calling convention.

cdecl
     A WIN32 function using the C calling conventions. (This is presently only used for the built-in functions of the C runtime system).

EXPORTNAME specifies the name (prototype) available for dynamic linking.

ARGTYPE must be chosen from this table:

byte
     An 8 bit argument. Can be used in WIN16 functions only.

word
     A 16 bit argument. Can be used in WIN16 functions only.

long
     A 32 bit argument. Can be used in WIN16 or WIN32 functions.

ptr
     A linear pointer, unsegmented. Can be used in WIN16 or WIN32 functions.

str
     A linear pointer, unsegmented, pointing to a null-terminated string. Can be used in WIN16 or WIN32 functions.

s_byte
     A signed 8 bit argument. Can be used in WIN16 functions only.

s_word
     A signed 16 bit argument. Can be used in WIN16 functions only.

s_long
     A signed 32 bit argument. Can be used in WIN16 or WIN32 functions.

segptr
     A segmented pointer. Can be used in WIN16 functions only.

segstr
     A segmented pointer to a null-terminated string. Can be used in WIN16 functions only.

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 Getting information on the API, for some hints on how to proceed in such a case.

Special entries of .spec-files
..............................

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 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.

Wine installation and configuration
***********************************

FIXME: write installation guide

Applying patches
================

See 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).

The Wine project
****************

If you are new to Wine and want to support this project, here are some suggestions.

See Debugging, for advice on how to debug Wine. See Applying patches, for instructions on applying patches.

Official and unofficial documentation on the MS-Windows API
===========================================================

Official documentation

For documentation on WIN32 API functions, you might try one of these sources:

  * There is a free online version of the MSDN library (including documentation for the WIN32 API) on http://www.microsoft.com/msdn/.

  * The Windows NT DDK gives information about some kernel (``executive'') routines. Some of the function documentation might also apply to user accessible DLL's.

Unofficial documentation

Not all of the WIN32 API is well documented. Some functions are obscured, and undocumented. See 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 Ordinals, for some notes on undocumented kernel functions.

  * ``Windows 95 System Programming Secrets''

     by Matt Pietrek

     Book & Disk Edition

     Paperback, 778 pages

     Published by IDG Books Worldwide

     Publication date: November 1, 1995

     Dimensions (in inches): 9.25 x 7.42 x 2.06

     ISBN: 1568843186

  * ``Undocumented Windows; A Programmers Guide to Reserved Microsoft Windows API Functions''

     by Andrew Schulman

     Paperback, 715 pages

     Published by Addison-Wesley Pub Co

     Publication date: February 1, 1994

     Dimensions (in inches): 9.11 x 7.37 x 1.53

     ISBN: 0201608340

  * More books on these topics (including Schulman and Pietrik):

     http://www.sonic.net/~undoc/bookstore.html

  * More details about calling undocumented functions can be found at http://ftp.uni-mannheim.de/info/OReilly/windows/win95.update/dirty.html.

  * In 1993 Dr. Dobbs Journal published a column called ``Undocumented Corner''.

  * You might want to check out BYTE from December 1983 as well.

      FIXME: is that to be taken seriously?

  * And you might try to find out something on your own. See Investigating the undocumented API, for details.

But, all in all, 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.

Investigating the undocumented API
==================================

Besides reading the documentation in Getting information on the 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 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 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).

Implementing an API type
========================

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 Implementing an API function, for comparison.

 1. Find out how the type should be named in Wine and in the DLL's. See API function and type naming, for details.

 2. Find out where the type should go. Please try to keep the header files structure as similar to MS-Windows as possible.

 3. Prepare for the later patch (by saving the original files before you work on them). See Creating patches, for details.

 4. Put the type declaration into the header file.

 5. Make sure the declaration is syntactically correct, i.e. it does not keep Wine from compiling.

 6. Make sure the declared type is layout-compatible with MS-Windows-compiled types. Especially keep an eye on the packing of the structure.

      FIXME: a reference to packed structures here.

 7. Build Wine and test the type, if possible. If you cannot test the type by implementing a proper API function, write a small test program to test it on its own. Or rather stop here.

 8. Write the documentation of the type in the wine.texinfo file. See Adding Documentation, for details. With types, be especially careful and document all the details. Also document all constants or flags that are used in the type.

 9. Create an entry in the ChangeLog file.

 10. Collect some of these changes, and create a patch. See Creating patches, for details.

 11. Mail the patch to Alexandre Julliard, julliard@lrc.epfl.ch.

 12. Wait for the patch to appear in the official distribution.

Implementing an API function
============================

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.

 1. Make sure all data types that appear in function arguments are properly declared in Wine. Otherwise, start with the data types.

 2. Find out how the function should be named in Wine and in the DLL's. See API function and type naming, for details.

 3. Find out what the function should do. This may be tricky for undocumented functions. See Getting information on the API, for some hints.

 4. Find out where the function should go:

      1. Which header file for the prototype.

      2. Which C source file.

      3. Which DLL(s), and which ordinal the function will take there. Perhaps the function name is already present in one of the .spec-files in the if1632 directory.

 5. Prepare for the later patch (by saving the original files before you work on them). See Creating patches, for details.

 6. Put the prototype into the header file, and the code into the C file.

 7. Make sure the code compiles.

 8. Create or change the information for the DLL entry points in the .spec-file in the if1632 directory. See The build program, for details of the DLL spec files.

 9. Build Wine and test the function, if possible. If you cannot test the function in Wine, write a small test program to test it on its own.

 10. Write the documentation of the function in the wine.texinfo file. See Adding Documentation, for details.

 11. Create an entry in the ChangeLog file.

 12. Collect some of these changes, and create a patch. See Creating patches, for details.

 13. Mail the patch to Alexandre Julliard, julliard@lrc.epfl.ch.

 14. Wait for the patch to appear in the official distribution.

API function and data type naming conventions
=============================================

This section describes Wine's naming scheme for API functions and data types.

The purpose of these naming conventions is to ensure that

  * both the WIN16 and WIN32 API are supported within the same source code,

  * both wide character functions (with Unicode strings) and 8 bit character functions (with ASCII or extended ASCII encoding) are supported, and

  * the source code can be shared between the emulator and the library version of Wine.

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
     This is the version for the 16 bit API. You might call it the ``16 bit version'' except that the function itself of course runs in true 32 bit mode (being part of Wine). So, the correct meaning of the suffix is that this function is part of the 16 bit API.

XXX32
     This is the version for the 32 bit API. Use this suffix only if the function does not use character strings in its parameters or return values. Otherwise use the next two.

XXX32A
     This is the version for the 32 bit API which uses ASCII strings (or rather, strings with 8 bit character encodings, i.e. the standard C char type). This version always goes together with another version, using the next suffix.

XXX32W
     This is the version for the 32 bit API which uses Unicode strings, i.e. strings with wide characters. It goes together with the ASCII version.

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.

Accessing API functions and types from the emulator
---------------------------------------------------

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 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).

Accessing API functions and types in the library
------------------------------------------------

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): _winemacro WINELIB_NAME (XXX) This macro replaces XXX by one of XXX16 or XXX32, depending on the definition of the symbols 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.

_winemacro WINELIB_NAME_AW (XXX) This macro replaces XXX by one of XXX16, XXX32A, or XXX32W, depending on the definition of the symbols 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.

_winemacro DECL_WINELIB_TYPE (XXX) This macro declares XXX to be an equivalent to XXX16 or XXX32, depending on the definition of the symbols WINELIB16 and WINELIB32. XXX should be the name of an API data type that contains no string arguments.

_winemacro DECL_WINELIB_TYPE_AW (XXX) This macro declares the type XXX to be an equivalent to XXX16, XXX32A, or XXX32W, depending on the definition of the symbols 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: _cwine WINELIB16 If this #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.

_cwine WINELIB32 If this #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.

_cwine UNICODE This 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.

Accessing API functions from within Wine
----------------------------------------

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.

Creating patches
================

See 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 Applying patches.

Adding Documentation
====================

Here are some templates which should help you collaborate on this documentation. Read the text below before examining them.

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.

Template introduction
---------------------

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.

Data type template
------------------

Category: Data type

API function template
---------------------

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

MS-Windows and UNIX file names in Wine
======================================

FIXME:

Wide character strings in API functions
=======================================

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.