From 59bec5030123d18af7bdd2461d1a6e4495e95bbd Mon Sep 17 00:00:00 2001
From: "Dimitrie O. Paun" <dpaun@rogers.com>
Date: Thu, 25 Sep 2003 23:48:39 +0000
Subject: [PATCH] Merge the non-obsolete bits from wine.texinfo into the Wine
 Developers Guide.

---
 documentation/implementation.sgml |  126 ++
 documentation/wine-devel.sgml     |    4 +
 documentation/wine.texinfo        | 2285 -----------------------------
 3 files changed, 130 insertions(+), 2285 deletions(-)
 delete mode 100644 documentation/wine.texinfo

diff --git a/documentation/implementation.sgml b/documentation/implementation.sgml
index c2f7efc900d..c35587e1c9e 100644
--- a/documentation/implementation.sgml
+++ b/documentation/implementation.sgml
@@ -2,6 +2,132 @@
     <title>Low-level Implementation</title>
     <para>Details of Wine's Low-level Implementation...</para>
 
+    <sect1 id="undoc-func">
+      <title>Undocumented APIs</title>
+
+	<para>
+	  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 
+	  <literal>esp</literal> register, points to the last valid entry; 
+	  thus, the operation of pushing a value onto the stack involves 
+	  decrementing <literal>esp</literal> and then moving the value into 
+	  the memory pointed to by <literal>esp</literal>
+	  (i.e., <literal>push p</literal> in assembly resembles 
+	  <literal>*(--esp) = p;</literal> in C).  Removing (popping)
+	  values off the stack is the reverse (i.e., <literal>pop p</literal> 
+	  corresponds to <literal>p = *(esp++);</literal> in C).
+	</para>
+
+	<para>
+	  In the <literal>stdcall</literal> calling convention, arguments are 
+	  pushed onto the stack right-to-left.  For example, the C call
+	  <function>myfunction(40, 20, 70, 30);</function> is expressed in 
+	  Intel assembly as:
+	  <screen>
+    push 30
+    push 70
+    push 20
+    push 40
+    call myfunction
+	  </screen>
+	  The called function is responsible for removing the arguments 
+	  off the stack.  Thus, before the call to myfunction, the
+	  stack would look like:
+	  <screen>
+             [local variable or temporary]
+             [local variable or temporary]
+              30
+              70
+              20
+    esp ->    40
+	  </screen>
+	  After the call returns, it should look like:
+	  <screen>
+             [local variable or temporary]
+    esp ->   [local variable or temporary]
+	  </screen>
+	</para>
+
+	<para>
+	  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.
+	</para>
+
+	<para>
+	  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.  Essentially, each wrapper assumes that the function will 
+	  take a large number of arguments.  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.
+	</para>
+
+	<para>
+	  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 (<filename>ntdll.dll</filename>) by passing 64 arguments, 
+	  all 0, to each function.  Unfortunately, Windows NT quickly goes to a 
+	  blue screen of death, even if the program is run from a 
+	  non-administrator account.
+	</para>
+
+	<para>
+	  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, <literal>ret hhll</literal> (where 
+	  <symbol>hhll</symbol> is the number of bytes to remove, i.e. the 
+	  number of arguments times 4), contains the bytes 
+	  <literal>0xc2 ll hh</literal> in memory.  It is a reasonable
+	  assumption that few, if any, functions take more than 16 arguments; 
+	  therefore, simply searching for 
+	  <literal>hh == 0 && ll &lt; 0x40</literal>  starting from the 
+	  address of a function yields the correct number of arguments most 
+	  of the time.
+	</para>
+
+	<para>
+	  Of course, this is not without errors. <literal>ret 00ll</literal> 
+	  is not the only instruction that can have the byte sequence 
+	  <literal>0xc2 ll 0x0</literal>; for example, 
+	  <literal>push 0x000040c2</literal> has the byte sequence
+	  <literal>0x68 0xc2 0x40 0x0 0x0</literal>, 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 
+	  disassembler -- quite a daunting task.  Besides, the probability 
+	  of having such a byte sequence that is not the actual return 
+	  instruction is fairly low.
+	</para>
+
+	<para>
+	  Much more troublesome is the non-linear flow of a function.  For
+	  example, consider the following two functions:
+	  <screen>
+    somefunction1:
+        jmp  somefunction1_impl
+
+    somefunction2:
+        ret  0004
+
+    somefunction1_impl:
+        ret  0008
+	  </screen>
+	  In this case, we would incorrectly detect both 
+	  <function>somefunction1</function> and
+	  <function>somefunction2</function> as taking only a single 
+	  argument, whereas <function>somefunction1</function> really 
+	  takes two arguments.
+	</para>
+
+	<para>
+	  With these limitations in mind, it is possible to implement more stubs
+	  in Wine and, eventually, the functions themselves.
+	</para>
+    </sect1>
+
     <sect1 id="accel-impl">
       <title>Accelerators</title>
 
diff --git a/documentation/wine-devel.sgml b/documentation/wine-devel.sgml
index e39c873ad79..bfcee26afe5 100644
--- a/documentation/wine-devel.sgml
+++ b/documentation/wine-devel.sgml
@@ -82,6 +82,10 @@
 	<firstname>Eric</firstname>
 	<surname>Pouech</surname>
       </author>
+      <author>
+	<firstname>Douglas</firstname>
+	<surname>Ridgway</surname>
+      </author>
       <author>
 	<firstname>John</firstname>
 	<surname>Sheets</surname>
diff --git a/documentation/wine.texinfo b/documentation/wine.texinfo
deleted file mode 100644
index 8167e108389..00000000000
--- a/documentation/wine.texinfo
+++ /dev/null
@@ -1,2285 +0,0 @@
-\input texinfo   @c -*-texinfo-*-
-@c %**start of header
-@setfilename wine.info
-@settitle Wine Reference Manual
-@iftex
-@afourpaper
-@end iftex
-@c %**end of header
-
-@ifinfo
-@format
-START-INFO-DIR-ENTRY
-* wine: (wine.info).             Windows on Unix.
-END-INFO-DIR-ENTRY
-@end format
-@end ifinfo
-
-@iftex
-@c @finalout
-@end iftex
-
-@ifinfo
-This file documents Wine, a system providing Microsoft Windows compatibility
-to Unix.
-
-@c 
-Copyright @copyright{} 1997,1998 The Wine authors. @*
-@xref{Authors, The Wine Authors, 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.
-
-@ignore
-Permission is granted to process this file through TeX
-and print the results, provided the printed document
-carries a copying permission notice identical to this
-one except for the removal of this paragraph (this
-paragraph not being relevant to the printed manual).
-
-@end ignore
-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''.
-
-@sp 4
-UNIX is a registered trademark of the Open Group.
-POSIX is a registered trademark of the IEEE Inc.
-X Window System is a trademark of X Consortium, Inc. 
-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.
-@end ifinfo
-
-@c begin chapters on right pages
-@setchapternewpage odd
-
-@titlepage
-
-@title{The Wine Reference Manual}
-@subtitle{Edition 0.0.5, February 1998}
-
-@author{The Wine Team}
-@c The following two commands start the copyright page.
-@page
-@vskip 0pt plus 1filll
-
-Copyright @copyright{} 1997, 1998 The Wine authors. @*
-@xref{Authors, The Wine Authors, 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''.
-
-@sp 4
-UNIX is a registered trademark of the Open Group.
-POSIX is a registered trademark of the IEEE Inc.
-X Window System is a trademark of X Consortium, Inc. 
-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.
-@end titlepage
-
-
-
-@c
-@c SETTINGS, DEFINES, MACROS
-@c
-
-@c Edit this macro manually in the above parts of the document
-@macro winemanualversion
-0.0.4
-@end macro
-
-@c Edit this macro manually in the above parts of the document
-@macro winemanualdate
-February 1998
-@end macro
-
-@c Edit this macro manually into the TeX titlepage
-@macro winemanualtitle
-The Wine Reference Manual
-@end macro
-
-@c
-@macro winelib
-Winelib
-@end macro
-@c
-@c MICROSOFT
-@c
-
-@c FIXME: automatic trademark reference
-@macro mswindows
-MS-Windows
-@end macro
-
-@c FIXME: automatic trademark reference
-@c spell it always the same
-@macro WIN32
-WIN32
-@end macro
-@macro WIN16
-WIN16
-@end macro
-
-@c FIXME: automatic trademark reference
-@macro WINNT
-Windows NT
-@end macro
-
-@c FIXME: automatic trademark reference
-@macro WINNT40
-Windows NT 4.0
-@end macro
-
-@c FIXME: automatic trademark reference
-@macro WIN95
-Windows 95
-@end macro
-
-
-@c
-@c THE OTHERS
-@c
-@c FIXME: automatic trademark reference
-@macro unix
-UNIX
-@end macro
-
-@c FIXME: automatic trademark reference
-@macro posix
-POSIX
-@end macro
-
-@macro unicode
-Unicode
-@end macro
-
-@macro ascii
-ASCII
-@end macro
-
-@c
-@c THIS MANUAL
-@c
-
-@c flag out differences to MS-Windows
-@macro windiff
-@emph{Differences to @mswindows{}:} @*
-@end macro
-
-@macro windiffnone
-@windiff{}
-No differences known.
-@end macro
-
-@c tell whether function is present in Windows 95 and/or NT
-@macro winconf
-@emph{Conformance to @mswindows{}:} @*
-@end macro
-
-@macro winconfall
-@winconf{}
-Present in @WIN95{} and @WINNT{}.
-@end macro
-
-@c give information about completion
-@macro completion
-@emph{Completion status:} @*
-@end macro
-
-@macro completionnone
-@completion{}
-Not yet implemented.
-@end macro
-
-@c
-@c MACROS FOR FUNCTIONS, TYPES, CONSTANTS, VARIABLES
-@c
-
-@c Constants in the WIN32 API
-@macro defvr_cw32 {restofline}
-@defvr Constant \restofline\
-@end macro
-@macro defvrx_cw32 {restofline}
-@defvrx Constant \restofline\
-@end macro
-
-@c Functions in the WIN32 API
-@macro deftypefn_w32 {restofline}
-@deftypefn {WIN32 function} \restofline\
-@end macro
-@macro deftypefnx_w32 {restofline}
-@deftypefnx {WIN32 function} \restofline\
-@end macro
-
-@c Types in the WIN32 API
-@macro deftp_w32 {restofline}
-@deftp {Data type} \restofline\
-@end macro
-@macro deftpx_w32 {restofline}
-@deftpx {Data type} \restofline\
-@end macro
-
-@c Macros internal to Wine
-@macro deffn_winemacro {restofline}
-@deffn {Wine internal macro} \restofline\
-@end macro
-@macro deffnx_winemacro {restofline}
-@deffn {Wine internal macro} \restofline\
-@end macro
-
-@c Constants internal to Wine
-@macro defvr_cwine {restofline}
-@defvr {Wine internal constant} \restofline\
-@end macro
-@macro defvrx_cwine {restofline}
-@defvrx {Wine internal constant} \restofline\
-@end macro
-
-
-@c
-@c TOP NODE
-@c
-@ifinfo
-@node Top, Copying, (dir), (dir)
-@top Wine
-
-This is edition @winemanualversion{}, last updated @winemanualdate{},
-of @winemanualtitle{}.
-
-Wine provides both source and binary compatibility with Microsoft Windows.
-The Wine API is designed to be as compatible as possible with various
-implementations of the Windows APIs. The Wine library allows porting
-Windows source to Unix, and a program loader allows unaltered Windows binaries
-to be run on Unix.
-
-Wine is free software. Wine is still under development.
-@end ifinfo
-
-@menu
-* Copying::                     License, Warranty, and Authors of Wine.
-* Introduction::                A short overview.
-* Wine Design::                 The design of Wine.
-* Reference Manual::            The Wine reference manual.
-* Installation::                Installing and configuring Wine.
-* The Wine Project::            How to contribute to Wine.
-* Concept Index::               Index of concepts and names.
-* Type Index::                  Index of types and type qualifiers.
-* Function Index::              Index of functions and function-like
-                                macros.
-* Variable Index::              Index of variables, constants, and
-                                variable-like macros.
-* File Index::                  Index of programs and files.
-@end menu
-
-@node Copying, Introduction, Top, Top
-
-@unnumbered License, Warranty, and Authors of Wine
-@cindex copying conditions for Wine
-@cindex conditions for copying Wine
-@cindex Wine copying conditions
-
-The Wine license, warranty, and list of authors together form the
-copyright for Wine. Read these sections carefully.
-
-@menu
-* License::                     The Wine license.
-* Warranty::                    Wine comes with no warranty.
-* Authors::                     The persons that contributed to Wine.
-@end menu
-
-@node License, Warranty, , Copying
-@cindex Wine license
-@cindex license of Wine
-
-@unnumberedsec The Wine License
-Wine is distributed under the following copyright.
-
-@quotation
-@include LICENSE
-@end quotation
-
-@node Warranty, Authors, License, Copying
-@cindex Wine warranty
-@cindex warranty of Wine
-
-@unnumberedsec The Wine Warranty
-
-@quotation
-Wine comes with no warranty.
-@end quotation
-
-@node Authors, , Warranty, Copying
-@cindex Wine authors
-@cindex authors of Wine
-@cindex copyright holders of Wine
-@cindex Wine copyright holders
-
-@unnumberedsec The Wine Authors
-
-@quotation
-@include AUTHORS
-@end quotation
-
-These persons also hold the copyright on Wine.
-
-The overall coordination is done by @*
-Alexandre Julliard @*
-@email{julliard@@winehq.com}
-
-
-
-@node Introduction, Wine Design, Copying, Top
-@chapter Introduction
-
-@strong{What is Wine?}
-
-Wine is a Windows-compatibility layer for Unix and X11.
-The Wine system consists of several thing:
-@enumerate
-@item
-An API, sometimes referred to as the Wine API,
-designed to be as compatible as possible with the
-@mswindows{} API
-@item
-A library, called @winelib{}, which implements this API
-@item
-A binary compatibility layer
-acts as a program loader for native Windows binaries.
-It works for both 16 and 32 bit Intel binaries, and
-provides all the appropriate translation between 16 and 32 bit code
-(thunking). Real mode interrupts are also supported, and their
-functionality is implemented in @winelib{}.
-
-@end enumerate
-
-@strong{System Requirements}
-
-
-Wine provides binary support for Intel code on Intel hardware only. 
-Neither hardware emulation
-nor non-Intel binaries are supported.
-@winelib{} should be possible to port to just about any Unix system.
-
-Currently, you must have one of:
-@itemize @bullet
-@item
-Linux version 0.99.13 or above
-@item
-NetBSD-current
-@item
-FreeBSD-current or FreeBSD 1.1
-@item
-OpenBSD/i386 2.1 or later
-@item
-Solaris x86 2.5 or later
-@end itemize
-You need X11, and you must have @file{libXpm} installed on your system.
-
-@strong{Availability}
-
-Wine is free software; the license is BSD-style. Basically, you can do
-anything with it, except claim that you wrote it.
-@xref{Copying}, for more information.
-
-@strong{Further information}
-
-You should consult the files @file{README}, @file{ANNOUNCE},
-@file{RELEASE-NOTES}, @file{BUGS}, @file{LICENSE}, and @file{WARRANTY},
-in the root directory of the Wine distribution.
-
-The Wine USENET newsgroup  @url{news:comp.emulators.ms-windows.wine} 
-is useful for both Wine developers and Wine users. The Wine home page
-is @url{http://www.winehq.com/}.
-
-@node Wine Design,  Reference Manual,  Introduction,  Top
-@chapter Wine Design
-
-@subsection The Wine Graphics Driver Model
-
-Wine, like Windows, abstracts drawing code so that applications may access
-a wide variety of devices, from different kinds of graphics cards,
-X displays and printers, using a single unified graphics model.
-This model is referred to as GDI: _G_raphics _D_river _I_nterface.
-This section discusses the Wine implementation of GDI.
-There are 61 functions in the Wine graphics model, including Arc, BitBlt,
-Chord, etc. For a complete list and prototypes, see the definition
-of DC_FUNCTIONS in [include/gdi.h].
-
-Wine, as of 2Q1998, has three native drivers: these provide support
-for rendering to X displays, metafiles, and Win16 native printer drivers.
-As far as Wine is concerned, a driver
-simply consists of a name and a table of function pointers 
-(see [graphics/driver.c]). These functions
-are the driver's implementation of the various Wine graphics
-operations (the GDI).  Wine maintains a linked list of all drivers which
-register themselves with Wine, as well as a ``generic''
-driver. Currently, the X11 driver registers itself as DISPLAY, the
-win16 driver registers itself as the generic driver, and the metafile
-driver doesn't register itself at all.
-
-@subsubsection How a driver function gets invoked
-
-All drawing by Wine applications 
-is done in terms of a Device Context (DC).
-Before an application can draw, it must create a DC, and all drawing calls
-must pass a handle to the DC they wish to draw to.
-[include/gdi.h] defines several structures relating to DCs, including
-DC, WIN_DC_INFO, and DeviceCaps. The DeviceCaps structure is at the lowest
-level: it holds
-information relating to specifics of the graphics display 
-hardware and associated
-driver. 
-WIN_DC_INFO holds information about several device independent
-modes the DC can be in, plus a pointer to DeviceCaps.
-Finally,
-the DC structure is the toplevel structure usually passed around.
-It holds viewport information, a pointer to WIN_DC_INFO, and a
-pointer to the function table to be used while rendering that DC.
-This function table is filled at the time of creating the DC.
-
-@c Modes
-
-@c  Some discussion of the various modalities available to a DC would be nice.
-
-@c Coordinate Systems
-
-@c  Some discussion of the maze of coordinate systems would also be nice.
-
-@c  Device Coordinates
-
-@c  Logical Coordinates
-
-@c  World transforms
-
-
-@subsubsection The X11 driver
-
-As a part of the Wine loading process,
-X11DRV_Init in [graphics/x11drv/init.c] is called. 
-This initializes various aspects of the X11 driver and
-registers it as DISPLAY.  This function first 
-calls initialization procedures for various parts of the X11 driver.
-It then
-creates and 
-fills a static DeviceCaps
-structure to be used for every X11 DC.
-Finally, it fills the table of GDI functions to be used for X11
-rendering and registers itself as ``DISPLAY''.
-
-@subsubsection The Metafile Driver
-
-The metafile driver is unusual, in that it is not a driver for any
-kind of display device, but rather a mechanism which allows using
-the Wine graphics model as a file format for saving graphics.
-The advantage of this is that it allows using identical formats for
-saving pictures as is actually used to display them; it is analogous
-to Display PostScript.
-
-The metafile driver is invoked explicitly by the application. The
-application calls CreateMetaFile() to create a special DC for recording
-graphics drawing operations in a metafile. Any drawing operations
-performed in this DC are not drawn physically anywhere, they are
-instead stored in the metafile.  The DC is explicitly destroyed by a
-call to CloseMetaFile(), which also finishes writing the metafile.
-Metafiles may be written either to a file or to memory. Later, the
-metafile can be rendered (in a physical DC) by PlayMetaFile().
-
-The way that this works is that device contexts contain a pointer
-to the function lookup table for drawing operations appropriate for
-that device.
-
-Not all functions in the Wine graphics model are relevant to metafiles, but
-some relevant but rarely used functions are unimplemented.
-
-@subsubsection The WIN16 Driver
-
-WIN16DRV_Init is called by MAIN_EmulatorInit, and registers the
-WIN16DRV function table WIN16DRV_Funcs [graphics/win16drv/init.c]
-for the generic driver. The WIN16 driver is designed to load 
-specified native Windows printer drivers. I don't understand 
-how the whole scheme works, 
-start studying what happens when a printer DC is
-created via WIN16DRV_CreateDC.
-
-If a DC is created explicitly, via the
-CreateDC() call, the driver name is specified explicitly and Wine
-finds the appropriate driver by leafing through its table of registered
-drivers. Metafile DCs can only be created by the CreateMetaFile function.
-
-Alternatively, most of the time, the DISPLAY driver is invoked
-implicitly. 
-The application creates a window with
-CreateWindow(). If the CS_CLASSDC or CS_OWNDC flag is passed, a new DC
-is created and saved for the window in a structure called DCE, which holds
-a DC, a clipping region, and flags. Whenever the application wants to
-paint in that window, it calls GetDC(hwnd), which returns the DC in the
-DCE saved in the window.
-
-If neither of those flags are used, the window gets a DCE assigned to it
-from a pool of DCEs created during Wine initialization and temporarily
-assigned during the GetDC() call.
-All DCEs, whether part of the Wine DC pool or created by request of a window,
-use the ``DISPLAY'' driver. 
-
-
-@node Reference Manual, Installation, Wine Design, Top
-
-@menu
-* @WIN32{} Reference Manual::   The @WIN32{} function calls and data types.
-* Resources and INI files::     How to determine the appearance and
-                                behaviour of Wine programs.
-* Metafiles--Icons--Bitmaps::   FIXME missing.
-* Debugging::                   Debugging Wine.
-* Programs::                    Programs written to run in/with Wine.
-* Tools::                       Programs to support Wine.
-@end menu
-
-@node @WIN32{} Reference Manual, Resources and INI files, , Reference Manual
-@chapter The @WIN32{} Reference Manual
-
-@menu
-* Kernel Objects::              How the Wine kernel keeps information.
-* Processes and Threads::       Job control and management in Wine.
-* Users and Groups::            Security in Wine.
-* Date and Time::               Functions for getting the date and time
-                                and for conversion between formats.
-* System Information::          Getting information about the hardware
-                                and software the system runs on.
-* Memory Management::           How your programs get memory from
-                                Wine.
-* I/O Facilities::              Input/Output in Wine.
-* Communication::               How processes can communicate.
-* Windows and Graphics::        GUI functions of @WIN32{}.
-* Errors and Exceptions::       How your program can report errors.
-                                (messaging)
-* Resources::                   Functions for dealing with resources.
-* The Registry::                FIXME missing.
-* Dynamic Link Libraries::      Functions for dealing with DLL's.
-@end menu
-
-@node Kernel Objects, Processes and Threads, , @WIN32{} Reference Manual
-@section Kernel Objects
-
-
-@node Processes and Threads, Users and Groups, Kernel Objects, @WIN32{} Reference Manual
-@section Processes and Threads
-
-@node Users and Groups, Date and Time, Processes and Threads, @WIN32{} Reference Manual
-@section Users and Groups
-
-@node Date and Time, System Information, Users and Groups, @WIN32{} Reference Manual
-@section 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.
-
-@menu
-* File Times::                  Creation and manipulation times of files.
-@end menu
-
-@node File Times, , , Date and Time
-@subsection File Times
-
-@menu
-* Type FILETIME::               The data structure used for specifying
-                                file times.
-* Compare File Times::          Compare two file times.
-@end menu
-
-@c
-@c *** struct FILETIME ***
-@c
-@node Type FILETIME, Compare File Times, , File Times
-@subsubsection Type FILETIME
-
-@noindent
-File times in Wine are specified by the data type @code{FILETIME},
-defined in @file{windows.h}.
-@deftp_w32  FILETIME
-@deftpx_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 @code{FILETIME} reads:
-@example
-typedef struct
-@{
-    INT32 dwLowDateTime;
-    INT32 dwHighDateTime;
-@} FILETIME, *LPFILETIME;
-@end example
-
-@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.
-To convert this type to local time, use the function
-@code{FileTimeToLocalFileTime}. 
-
-@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.
-@end deftp
-
-@c
-@c *** CompareFileTime ***
-@c
-@node Compare File Times, , Type FILETIME, File Times
-
-@noindent
-The Wine function @code{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 @file{windows.h}.
-@deftypefn_w32 LONG CompareFileTime (@w{CONST FILETIME* @var{time_1},} @w{CONST FILETIME* @var{time_2})}
-This function returns @code{1}, if @var{time_1} is greater than
-@var{time_2}, @code{-1} if it is less, and @code{0} if both times are
-equal. 
-
-@winconfall{}
-
-@windiffnone{}
-
-@completionnone{}
-@end deftypefn
-
-@node System Information, Memory Management, Date and Time, @WIN32{} Reference Manual
-@section System Information
-
-@node Memory Management, I/O Facilities, System Information, @WIN32{} Reference Manual
-@section Memory Management
-
-@node I/O Facilities, Communication, Memory Management, @WIN32{} Reference Manual
-@section 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.
-
-@menu
-* I/O on Files::                Accessing the contents of files.
-* File System Interface::       Functions for manipulating files as a whole.
-@end menu
-
-@node I/O on Files, File System Interface, , I/O Facilities
-@subsection I/O on Files
-
-@node File System Interface, , I/O on Files, I/O Facilities
-@subsection File System Interface
-
-These functions are concerned with operating on files themselves, rather
-than on their contents.
-
-@menu
-* Type BY_HANDLE_FILE_INFORMATION::     The data structure used to
-                                        specify file information.
-* File attributes::                     The file attributes flags in
-                                        a file information structure.
-* Getting file information::            These functions let you obtain
-                                        information about a file.
-@end menu
-
-@node Type BY_HANDLE_FILE_INFORMATION, File attributes, , File System Interface
-@subsubsection The file information structure
-
-The file information structure of Wine is used to obtain information
-about files. It is declared in the header @file{winedows.h}.
-@deftp_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:
-@table @code
-@item int dwFileAttributes
-   @cindex file attributes in file information
-   @cindex attributes of file in file information
-   @xref{File attributes}, for details.
-@item FILETIME ftCreationTime
-   @cindex creation time in file information
-   @cindex time of file creation in file information
-   The time when the file was created.
-   @xref{Type FILETIME}, for details.
-@item FILETIME ftLastAccessTime
-   @cindex access time in file information
-   @cindex time of file access in file information
-   The time when the file was last accessed.
-   @xref{Type FILETIME}, for details.
-@item FILETIME ftLastWriteTime
-   @cindex write time in file information
-   @cindex time of last file write in file information
-   The time when the file was last written to.
-   @xref{Type FILETIME}, for details.
-@item int dwVolumeSerialNumber
-   @cindex serial number of volume in file information
-   @cindex volume number (serial) in file information
-   The serial number of the volume containing the file. In Wine,
-   currently 0.
-@item int nFileSizeHigh
-   @cindex file size in file information
-   @cindex size of file in file information
-   A 32 bit value which contains the high part of the 64 bit file size.
-@item int nFileSizeLow
-   A 32 bit value which contains the low part of the 64 bit file size.
-@item int nNumberOfLinks
-   @cindex hard links number in file information
-   @cindex links (number of hard) in file information
-   This is the number of hard links to the file. In a file system which
-   does not support hard links, this is 1.
-@item int nFileIndexHigh
-   @cindex inode number in file information
-   @cindex file index in file information
-   @cindex index of file in file information
-   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.
-@item int nFileIndexLow
-   A 32 bit value which contains the low part of the 64 bit file index.
-@end table
-
-The definition of @code{BY_HANDLE_FILE_INFORMATION} reads:
-@example
-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 ;
-@end example
-
-The @code{BY_HANDLE_FILE_INFORMATION} structure can be obtained by the
-@code{GetFileInformationByHandle} function (@pxref{Getting file information}, for
-details).
-
-@windiff{}
-In @mswindows{}, the @code{int} elements of the structure are apparently
-of type @code{DWORD}.
-@end deftp
-
-@node File attributes, Getting file information, Type BY_HANDLE_FILE_INFORMATION, File System Interface
-@subsubsection The file attributes in a file information structure
-
-The file attributes in a file information structure and in other structures
-are a logical @emph{or} of one or more of the following constants:
-
-@defvr_cw32 FILE_ATTRIBUTE_READONLY
-The file is a read-only file. (Wine value: 0x0001).
-@end defvr
-@defvr_cw32 FILE_ATTRIBUTE_HIDDEN
-The file is a hidden file. Wine can set this attribute for files starting
-with a dot (normally considered hidden in a Unix environment). This behaviour
-is controlled by the @code{ShowDotFiles} configuration setting.  
-(Wine value: 0x0002).
-@end defvr
-@defvr_cw32 FILE_ATTRIBUTE_SYSTEM
-The file belongs to the operating system. Files in Wine do not have this
-attribute. (Wine value: 0x0004).
-@end defvr
-@defvr_cw32 FILE_ATTRIBUTE_LABEL
-This is not present in the @mswindows{} API. (Wine value: 0x0008).
-@end defvr
-@defvr_cw32 FILE_ATTRIBUTE_DIRECTORY
-The file is a directory. (Wine value: 0x0010).
-@end defvr
-@defvr_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 @mswindows{} to indicate that a file is to be archived; when the file
-is archived, the flag is cleared. (Wine value: 0x0020).
-@end defvr
-@defvr_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).
-@end defvr
-@defvr_cw32 FILE_ATTRIBUTE_TEMPORARY
-The file is used as a temporary storage. Files in Wine do not have this
-attribute. (Wine value: 0x0100).
-@end defvr
-@defvr_cw32 FILE_ATTRIBUTE_ATOMIC_WRITE
-This is reserved for future use. Files in Wine do not have this
-attribute. (Wine value: 0x0200).
-@end defvr
-@defvr_cw32 FILE_ATTRIBUTE_XACTION_WRITE
-This is reserved for future use. Files in Wine do not have this
-attribute. (Wine value: 0x0400).
-@end defvr
-@defvr_cw32 FILE_ATTRIBUTE_COMPRESSED
-The file is compressed. Files in Wine do not have this attribute. (Wine
-value: 0x0800). 
-@end defvr
-
-@node Getting file information, , File attributes, File System Interface
-@subsubsection Getting file information
-
-The functions in this section describe how to get information about
-files. 
-
-@c
-@c *** GetFileInformationByHandle
-@c
-@noindent
-The Wine function @code{GetFileInformationByHandle} returns a file
-information structure. It is defined in @file{windows.h}.
-
-@deftypefn_w32 BOOL GetFileInformationByHandle (@w{HFILE32 @var{file},} @w{BY_HANDLE_FILE_INFORMATION *@var{info})}
-This function obtains for the specified @var{file} the file information,
-and stores it in @var{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
-@code{TRUE} on success, @code{FALSE} on failure.
-
-@winconfall{}
-
-@windiff{}
-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. @xref{File attributes}, for details. The volume
-serial number is set to 0.
-@end deftypefn
-
-
-@c
-@c *** GetFileTime ***
-@c
-@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 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. @xref{Type FILETIME}, for details. 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{}
-
-@windiff{}
-The file times are produced in a granularity of full seconds, due to the
-underlying @unix{} file system. 
-@end deftypefn
-
-@c
-@c *** GetFileAttributes ***
-@c
-@noindent
-The Wine function @code{GetFileAttributes} returns the file attributes
-for a file. It is defined in @file{windows.h}.
-
-@deftypefn_w32 DWORD GetFileAttributes (@w{LPCTSTR @var{name})}
-This function looks up the file with name @var{name}, and returns the
-attributes of the file. @xref{File attributes}, for details on the file
-attributes. If the function is not successful, it returns a word with
-all bits set (@samp{0xffffffff}).
-
-@winconfall{}
-
-@windiff{}
-Most file attributes are not present in the
-@unix{} file system. @xref{File attributes}, for details.
-@end deftypefn
-
-
-
-
-@node Communication, Windows and Graphics, I/O Facilities, @WIN32{} Reference Manual
-@section Communication
-
-@node Windows and Graphics, Errors and Exceptions, Communication, @WIN32{} Reference Manual
-@section Windows and Graphics
-
-@node Errors and Exceptions, Resources, Windows and Graphics, @WIN32{} Reference Manual
-@section Errors and Exceptions
-
-@node Resources, The Registry, Errors and Exceptions, @WIN32{} Reference Manual
-@section Resources
-
-@node The Registry, Dynamic Link Libraries, Resources, @WIN32{} Reference Manual
-@section The Registry
-
-@node Dynamic Link Libraries, , The Registry, @WIN32{} Reference Manual
-@section 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. @xref{The build program}, for
-information on how DLL's are integrated into Wine.
-
-
-
-
-@node Resources and INI files, Metafiles--Icons--Bitmaps, @WIN32{} Reference Manual, Reference Manual
-@chapter Resources and @file{INI} Files
-
-@node Metafiles--Icons--Bitmaps, Debugging, Resources and INI files, Reference Manual
-@chapter Metafiles --- Icons --- Bitmaps
-
-@node Debugging, Programs, Metafiles--Icons--Bitmaps, Reference Manual
-@chapter Debugging
-
-@node Programs, Tools, Debugging, Reference Manual
-@chapter Programs
-
-@node Tools, , Programs, Reference Manual
-@chapter 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. @xref{Programs}, for such programs.
-
-Tools are internal programs that are used to help compile or configure
-Wine.
-
-@menu
-* The build program::           A program used to build the DLL entry
-                                points from specifications in @file{if1632/}.
-@end menu
-
-
-@node The build program, , , Tools
-@section The @file{build} program
-
-@cindex modules of Wine
-@cindex Wine modules
-@cindex DLL's built-in in Wine
-@cindex Wine DLL's built-in
-@cindex built-in DLL's in Wine
-Wine contains several modules that implement various DLL's which are
-required to run @mswindows{} programs.
-
-The @file{build} program, located in the @file{tools/} directory, is
-used to create the bindings for the DLL entry points of the API functions.
-This program reads a @file{.spec}-file in the @file{if1632} directory
-and creates the assembly code that translates the function arguments
-correctly. 
-
-
-@menu
-* The spec files::              The format of the @file{.spec}-files.
-@end menu
-
-FIXME: where in Wine are the DLL's affixed?
-
-FIXME: write a description
-
-@xref{Implementing an API function}, for notes on using this program.
-
-@node The spec files, , , The build program
-@subsection The @file{.spec}-files
-@cindex DLL spec files
-@cindex spec files of DLL's
-@cindex entry points in DLL's
-
-This subsection describes the format of the @file{.spec}-files.
-
-A @file{.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 @file{.spec}-file, you must
-know about the concept of ordinals.
-@menu
-* The general format::                  General format conventions.
-* Ordinals::                            Ordinals are indexes of entry
-                                        points into DLL's.
-* Spec file header::                    The header information.
-* Variable entry points::               Entries for DLL variables.
-* Function entry points::               Entries for DLL functions.
-* Special entries::                     Entries for stubs, dummy
-                                        functions, Wine symbols, and
-                                        constant values.
-@end menu
-
-@node The general format, Ordinals, , The spec files
-@subsubsection The general format
-@cindex format of spec files
-@cindex spec files format
-
-The @file{.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
-@file{.spec}-file. The default handler function of an ordinal will print
-an error message when called.
-
-Comments are indicated by hash marks (@samp{#}); everything between a
-hash mark and the end of the line is ignored.
-
-Empty lines are allowed.
-@* FIXME: is that so?
-
-@node Ordinals, Spec file header, The general format, The spec files
-@subsubsection Ordinals
-@cindex ordinals in DLL's
-@cindex DLL ordinals
-
-All references to DLL objects like functions or variables are indexed by
-unique nonnegative numbers. These numbers are called
-@dfn{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 @mswindows{} 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 @WINNT{} and @WIN95{}. 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 @mswindows{}
-programs. Also the @file{shell32.dll} functions are reported to be
-imported by ordinal in some other DLL's.
-
-@xref{Getting information on the API}, for sources of further information.
-
-@node Spec file header, Variable entry points, Ordinals, The spec files
-@subsubsection The header of a @file{.spec}-file
-
-The @file{.spec}-file starts with two mandatory definitions. The first
-line gives the name of the DLL which the @file{.spec}-file describes,
-@example
-name @var{NAME}
-@end example
-where @var{NAME} is the name of the DLL. The next line defines the type
-of the DLL, 
-@example
-type @var{TYPE}
-@end example
-with @var{TYPE} being either @samp{win16} or @samp{win32}.
-
-An optional statement of the form
-@example
-base @var{ORDINAL}
-@end example
-can be used to define the offset of the first ordinal. @var{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
-@example
-heap @var{SIZE}
-@end example
-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?
-
-@node Variable entry points, Function entry points, Spec file header, The spec files
-@subsubsection Variable entry points of @file{.spec}-files
-
-You can declare an ordinal that holds data. Data items may be of 8, 16,
-or 32 bit in size.
-
-@example
-@var{ORDINAL} @var{VARTYPE} @var{EXPORTNAME} (@var{DATA} @var{DATA @dots{}})
-@end example
-
-@var{ORDINAL} is the ordinal number corresponding to the
-variable. @var{VARTYPE} must be @samp{byte}, @samp{word}, or
-@samp{long}, for 8, 16, or 32 bits respectively. @var{EXPORTNAME} will
-be the name available for dynamic linking. @var{DATA} can be a decimal
-number or a hex number preceded by @samp{0x}. Each @var{DATA} item defines
-a unit of storage.
-
-The following example defines the variable @samp{VariableA} at ordinal
-2, containing 4 bytes:
-@example
-2 byte VariableA(-1 0xff 0 0)
-@end example
-
-
-@node Function entry points, Special entries, Variable entry points, The spec files
-@subsubsection Function entry points of @file{.spec}-files
-
-@example
-@var{ORDINAL} @var{FUNCTYPE} @var{EXPORTNAME} (@var{ARGTYPE} @dots{} @var{}) @var{HANDLERNAME}
-@end example
-
-@var{ORDINAL} is the ordinal number corresponding to the
-function. @var{FUNCTYPE} must be chosen from this table:
-@table @samp
-@item pascal16
-A @WIN16{} function that returns a 16 bit value.
-@item pascal
-A @WIN16{} function that returns a 32 bit value.
-@item register
-A function using CPU registers to pass arguments.
-@item stdcall
-A normal @WIN32{} function. @xref{Investigating the undocumented API},
-for an explanation of the stdcall calling convention.
-@item cdecl
-A @WIN32{} function using the C calling conventions. (This is presently
-only used for the built-in functions of the C runtime system).
-@end table
-
-@var{EXPORTNAME} specifies the name (prototype) available for dynamic
-linking.
-
-@var{ARGTYPE} must be chosen from this table:
-@table @samp
-@item byte
-  An 8 bit argument. Can be used in @WIN16{} functions only.
-@item word
-  A 16 bit argument. Can be used in @WIN16{} functions only.
-@item long
-  A 32 bit argument. Can be used in @WIN16{} or @WIN32{} functions.
-@item ptr
-  A linear pointer, unsegmented. Can be used in @WIN16{} or @WIN32{}
-  functions.
-@item str
-  A linear pointer, unsegmented, pointing to a null-terminated string.
-  Can be used in @WIN16{} or @WIN32{} functions.
-@item s_byte
-  A signed 8 bit argument. Can be used in @WIN16{} functions only.
-@item s_word
-  A signed 16 bit argument. Can be used in @WIN16{} functions only.
-@item s_long
-  A signed 32 bit argument. Can be used in @WIN16{} or @WIN32{}
-  functions.
-@item segptr
-  A segmented pointer. Can be used in @WIN16{} functions only.
-@item segstr
-  A segmented pointer to a null-terminated string. Can be used in
-  @WIN16{} functions only.
-@end table
-
-@var{HANDLERNAME} is the name of the actual Wine function that will
-process the request in 32-bit mode.
-
-
-@sp 2
-Here are some examples. The first example defines an entry point for the
-@code{CreateWindow()} call (the ordinal 100 is just an example):
-@example
-100 pascal CreateWindow(ptr ptr long s_word s_word s_word s_word
-                        word word word ptr) WIN_CreateWindow
-@end example
-
-The second example defines an entry point for the @code{GetFocus()} call
-(again, the ordinal 100 is an example):
-@example
-100 pascal GetFocus() WIN_GetFocus()
-@end example
-
-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 @code{CURRENT_STACK16->args}.
-@* FIXME: create a reference here
-See the @code{wsprintf}* functions in @file{user.spec} and 
-@file{user32.spec} for an example.
-
-Sometimes it is not known how many arguments an undocumented DLL
-function takes. @xref{Getting information on the API}, for some hints on
-how to proceed in such a case.
-
-@node Special entries, , Function entry points, The spec files
-@subsubsection Special entries of @file{.spec}-files
-
-The @file{.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.
-
-
-@strong{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.
-
-@example
-@var{ORDINAL} stub @var{EXPORTNAME}
-@end example
-
-@var{ORDINAL} is the ordinal number corresponding to the
-function. @var{EXPORTNAME} specifies the name (prototype) available for dynamic
-linking.
-
-@strong{Return ordinals}
-
-This pseudo function type defines a function entry point whose handler
-should do nothing but return a value.
-@example
-@var{ORDINAL} return @var{EXPORTNAME} @var{ARGLENGTH} @var{RETVALUE}
-@end example
-
-@var{ORDINAL} is replaced by the ordinal number corresponding to the
-function. @var{ARGLENGTH} is the number of bytes that need to be removed
-from the stack before returning to the caller. @xref{Investigating the
-undocumented API}, for an explanation of the stdcall calling convention.
-@var{RETVALUE} is the return value which will be passed back to the
-caller.
-
-@strong{Extern ordinals}
-
-@example
-@var{ORDINAL} extern @var{EXPORTNAME} @var{SYMBOLNAME}
-@end example
-This type defines an entry that simply maps to a Wine symbol
-(variable or function); @var{EXPORTNAME} will point to the symbol
-@var{SYMBOLNAME} that must be defined in C code. This type only works with
-@WIN32{}.
-
-
-@strong{Equate ordinals}
-
-@example
-@var{ORDINAL} equate @var{EXPORTNAME} @var{DATA}
-@end example
-
-This type defines an ordinal as an absolute value.
-@var{ORDINAL} is replaced by the ordinal number corresponding to the
-entry. @var{EXPORTNAME} will be the name available for dynamic linking.  
-@var{DATA} can be a decimal number or a hex number preceeded by @samp{0x}.
-
-
-@node Installation, The Wine Project, Reference Manual, Top
-@chapter Wine installation and configuration
-FIXME: write installation guide
-
-@menu
-* Applying patches::            How to update Wine to a newer version.
-@end menu
-
-@node Applying patches, , , Installation
-@section Applying patches
-@xref{Creating patches}, for instructions on creating patches.
-
-@kbd{cd} to the top source directory for Wine, and run 
-@code{patch -p1 < @var{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 @code{make}. In general, the sequence @code{configure},
-@code{make depend}, @code{make} is sufficient, unless the patch alters
-@code{[config.in]}, in which case you must regenerate @code{configure}
-via @code{make configure} (which just runs @code{autoconf}).
-
-
-@node The Wine Project, , Installation, Top
-@chapter The Wine project
-@cindex Wine project contributions
-@cindex project contributions to Wine
-
-If you are new to Wine and want to support this project, here are
-some suggestions. 
-
-@menu
-* Getting information on the API::      Official and unofficial sources
-                                        of information on the @WIN32{} API.
-* Investigating the undocumented API::  You can find out some API
-                                        information on your own.
-* Implementing an API type::            How to implement a data type
-                                        of the API (a checklist).
-* Implementing an API function::        How to implement one function
-                                        of the API (a checklist).
-* API function and type naming::        How to name API functions in Wine.
-* Creating patches::                    How to create patches for Wine.
-* Adding Documentation::                Templates for the documentation.
-* File names::                          How Wine treats @mswindows{} and
-                                        @unix{} file names.
-* Wide character strings::              How Wine treats wide character
-                                        strings.
-@end menu
-
-@xref{Debugging}, for advice on how to debug Wine.
-@xref{Applying patches}, for instructions on applying patches.
-
-
-@node Getting information on the API, Investigating the undocumented API, , The Wine Project
-@section Official and unofficial documentation on the @mswindows{} API
-@cindex documentation of API functions
-@cindex undocumented API functions
-
-
-@strong{Official documentation}
-
-For documentation on @WIN32{} API functions, you might try one of these
-sources:
-
-@itemize @bullet
-
-@item
-There is a free online version of the MSDN library (including
-documentation for the @WIN32{} API) on
-@url{http://www.microsoft.com/msdn/}.
-
-@item 
-The @WINNT{} DDK gives information about some kernel (``executive'')
-routines. Some of the function documentation might also apply to user
-accessible DLL's.
-@end itemize
-
-@strong{Unofficial documentation}
-
-Not all of the @WIN32{} API is well documented. Some functions are
-obscured, and undocumented. @xref{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:
-@c From: vischne@ibm.net-nospam (root)
-@c Subject: Re: Functions
-@c Newsgroups: comp.emulators.ms-windows.wine
-@c Date: 24 Jul 97 16:45:11 GMT
-@c Organization: The Light
-@c NNTP-Posting-Host: 129.37.246.203
-@c Message-ID: <33d78697.0@news3.ibm.net>
-
-@quotation
-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''.
-@end quotation
-
-@xref{Ordinals}, for some notes on undocumented kernel functions.
-
-@itemize @bullet
-
-@item
-@cindex book on undocumented API features by Pietrik
-``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 @*
-
-@item
-@cindex book on undocumented API features by Schulman
-``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  @*
-
-@item
-More books on these topics (including Schulman and Pietrik): @*
-@url{http://www.sonic.net/~undoc/bookstore.html}
-
-@item
-More details about calling undocumented functions can be found at
-@url{http://ftp.uni-mannheim.de/info/OReilly/windows/win95.update/dirty.html}.
-
-@item
-In 1993 Dr. Dobbs Journal published a column called ``Undocumented
-Corner''.
-@item
-You might want to check out BYTE from December 1983 as well.
-@* FIXME: is that to be taken seriously?
-@item
-And you might try to find out something on your own. @xref{Investigating
-the undocumented API}, for details.
-@end itemize
-
-But, all in all, @url{news:comp.emulators.ms-windows.wine} says
-@c From: dacut@henry.ece.cmu.edu (David A. Cuthbert)
-@c Subject: Re: Getting Internet Explorer to work
-@c Newsgroups: comp.emulators.ms-windows.wine
-@c Date: 24 Jul 1997 03:10:30 GMT
-@c Organization: Electrical & Computer Engineering, Carnegie Mellon University
-@c Reply-To: henry.ece.cmu.edu!dacut
-@c Message-ID: <5r6h36$86c@fs7.ece.cmu.edu>
-@c NNTP-Posting-Host: henry.ece.cmu.edu
-
-@quotation
-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.
-@end quotation
-
-
-@node Investigating the undocumented API, Implementing an API type, Getting information on the API, The Wine Project
-@section Investigating the undocumented API
-@cindex undocumented API investigation
-@cindex parameters of undocumented API functions
-@cindex stdcall calling convention
-@cindex C calling convention
-@cindex API function parameters investigation
-@cindex stack handling under stdcall calling
-
-Besides reading the documentation in @ref{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.
-
-@c The following text is closely quoted from:
-@c From: dacut@henry.ece.cmu.edu (David A. Cuthbert)
-@c Subject: Win32 stub functions (Claus Fischer, please read)
-@c Newsgroups: comp.emulators.ms-windows.wine
-@c Date: 7 Aug 1997 22:33:09 GMT
-@c Organization: Electrical & Computer Engineering, Carnegie Mellon University
-@c Reply-To: henry.ece.cmu.edu!dacut
-@c Message-ID: <5sdif5$qt3@fs7.ece.cmu.edu>
-
-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 @dfn{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 @samp{esp}
-register, points to the last valid entry; thus, the operation of
-pushing a value onto the stack involves decrementing @samp{esp} and then
-moving the value into the memory pointed to by esp (i.e., @code{push p}
-in assembly resembles @code{*(--esp) = p;} in C).  Removing (popping)
-values off the stack is the reverse (i.e., @code{pop p} corresponds to
-@code{p = *(esp++);}).
-
-In the @dfn{stdcall} calling convention, arguments are pushed onto the
-stack right-to-left.  For example, the C call
-
-@example
-    myfunction(40, 20, 70, 30);
-@end example
-
-is expressed in Intel assembly as:
-
-@example
-    push 30
-    push 70
-    push 20
-    push 40
-    call myfunction
-@end example
-
-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:
-
-@example
-             [local variable or temporary]
-             [local variable or temporary]
-              30
-              70
-              20
-    esp ->    40
-@end example
-
-After the call returns, it should look like:
-
-@example
-             [local variable or temporary]
-    esp ->   [local variable or temporary]
-@end example
-
-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.  @file{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 @file{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.
-
-@cindex bsod (blue screen of death)
-@cindex blue screen of death
-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 (@file{ntdll.dll}) by passing 64 arguments, all 0, to each
-function.  Unfortunately, @WINNT40{} quickly goes to a blue screen
-of death (@dfn{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, @code{ret hhll} (where @samp{hhll} is the
-number of bytes to remove, i.e. the number of arguments times 4), contains
-the bytes @samp{0xc2 ll hh} in memory.  It is a reasonable assumption
-that few, if any, functions take more than 16 arguments; therefore,
-@samp{hh} is 0x0 and @samp{ll} is less than 0x40.  This utility,
-@file{MakeSpec} (see below), simply queries the address of a function
-and looks for the first occurrence of the bytes @samp{0xc2 ll 0x0},
-where @math{@samp{ll} <= 0x40}.
-
-Of course, this is not without errors. @code{ret 00ll} is not the only
-instruction that can have the byte sequence @samp{0xc2 ll 0x0}; for
-example, @code{push 0x000040c2} has the byte sequence
-@samp{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:
-
-@example
-    somefunction1:
-        jmp  somefunction1_impl
-
-    somefunction2:
-        ret  0004
-
-    somefunction1_impl:
-        ret  0008
-@end example
-
-@file{MakeSpec} would incorrectly list both @code{somefunction1} and
-@code{somefunction2} as taking only a single argument, whereas
-@code{somefunction1} really takes two arguments.
-
-With these limitations in mind, it is possible to implement more stubs
-in Wine and, eventually, the functions themselves.
-
-@c end of quote
-
-The program @file{WinRelay} can be downloaded from
-@url{http://www.ece.cmu.edu/afs/ece/usr/dacut/www/src},
-and @file{MakeSpec} will be available from the same location. You can
-compile them with Borland's C++Builder; you should not optimize when
-compiling (@file{WinRelay} needs the stack frames).
-
-
-@node Implementing an API type, Implementing an API function, Investigating the undocumented API, The Wine Project
-@section 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.
-@xref{Implementing an API function}, for comparison.
-
-@enumerate
-@item
-Find out how the type should be named in Wine and in the DLL's.
-@xref{API function and type naming}, for details.
-
-@item
-Find out where the type should go. Please try to keep the header files
-structure as similar to @mswindows{} as possible. 
-
-@item
-Prepare for the later patch (by saving the original files before you
-work on them). @xref{Creating patches}, for details.
-
-@item
-Put the type declaration into the header file.
-
-@item
-Make sure the declaration is syntactically correct, i.e. it does not
-keep Wine from compiling.
-
-@item
-Make sure the declared type is layout-compatible with
-@mswindows{}-compiled types. Especially keep an eye on the packing of
-the structure.
-@* FIXME: a reference to packed structures here.
-
-@item
-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.
-
-@item
-Write the documentation of the type in the @file{wine.texinfo}
-file. @xref{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.
-
-@item
-Create an entry in the @file{ChangeLog} file.
-
-@item
-Collect some of these changes, and create a patch. @xref{Creating
-patches}, for details.
-
-@item
-Mail the patch to Alexandre Julliard, @email{julliard@@winehq.com}.
-
-@item
-Wait for the patch to appear in the official distribution.
-@end enumerate
-
-
-@node Implementing an API function, API function and type naming, Implementing an API type, The Wine Project
-@section 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.
-
-@enumerate
-@item
-Make sure all data types that appear in function arguments are properly
-declared in Wine. Otherwise, start with the data types.
-
-@item
-Find out how the function should be named in Wine and in the DLL's.
-@xref{API function and type naming}, for details.
-
-@item
-Find out what the function should do. This may be tricky for
-undocumented functions. @xref{Getting information on the API}, for some
-hints.
-
-@item
-Find out where the function should go:
-@enumerate
-@item
-Which header file for the prototype.
-@item
-Which C source file.
-@item
-Which DLL(s), and which ordinal the function will take there. Perhaps
-the function name is already present in one of the @file{.spec}-files in
-the @file{if1632} directory.
-@end enumerate
-
-@item
-Prepare for the later patch (by saving the original files before you
-work on them). @xref{Creating patches}, for details.
-
-@item
-Put the prototype into the header file, and the code into the C file.
-
-@item
-Make sure the code compiles.
-
-@item
-Create or change the information for the DLL entry points in the
-@file{.spec}-file in the @file{if1632} directory.
-@xref{The build program}, for details of the DLL spec files.
-
-@item
-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.
-
-@item
-Write the documentation of the function in the @file{wine.texinfo}
-file. @xref{Adding Documentation}, for details.
-
-@item
-Create an entry in the @file{ChangeLog} file.
-
-@item
-Collect some of these changes, and create a patch. @xref{Creating
-patches}, for details.
-
-@item
-Mail the patch to Alexandre Julliard, @email{julliard@@winehq.com}.
-
-@item
-Wait for the patch to appear in the official distribution.
-@end enumerate
-
-
-@node API function and type naming, Creating patches, Implementing an API function, The Wine Project
-@section API function and data type naming conventions
-@cindex API function names
-@cindex API type names
-@cindex names of API functions and types
-@cindex naming scheme for API functions and types
-@cindex suffixes for API functions and types
-@cindex endings of API function and type names
-
-This section describes Wine's naming scheme for API functions and data
-types.
-
-The purpose of these naming conventions is to ensure that
-@itemize @bullet
-@item
-both the @WIN16{} and @WIN32{} API are supported within the same source
-code,
-@item
-both wide character functions (with @unicode{} strings) and 8 bit
-character functions (with @ascii{} or extended @ascii{} encoding) are
-supported, and
-@item
-the source code can be shared between the emulator and the library
-version of Wine.
-@end itemize
-
-A function or data type whose name in the @mswindows{} API is @var{xxx}
-will in the Wine code have the following name(s):
-@table @code
-@item @var{xxx}16
-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.
-@item @var{xxx}32
-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.
-@item @var{xxx}32A
-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
-@code{char} type). This version always goes together with another
-version, using the next suffix.
-@item @var{xxx}32W
-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.
-@end table
-
-So, where the @mswindows{} 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 @mswindows{} 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.
-
-@menu
-* Access from the emulator::    How to access API functions and types
-                                from applications that are run in the
-                                Wine emulator.
-* Access in the library::       How to access API functions and types
-                                from applications that are linked with
-                                the Wine library.
-* Access from inside Wine::     How to access API functions and types
-                                from inside the Wine code.
-@end menu
-
-@node Access from the emulator, Access in the library, , API function and type naming
-@subsection Accessing API functions and types from the emulator
-@cindex access to DLL API functions and types
-@cindex Wine emulator access to API functions and types
-@cindex emulator access to Wine API functions and types
-
-The emulator part of Wine provides the hooks for dynamically linking the
-API functions to the @mswindows{} executables (@file{.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 @mswindows{} 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
-@file{.spec}-files in the @file{if1632/} directory. @xref{The build
-program}, for details.
-
-The @mswindows{} application simply calls the API function by its
-standard @mswindows{} 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).
-
-
-@node Access in the library, Access from inside Wine, Access from the emulator, API function and type naming
-@subsection Accessing API functions and types in the library
-@cindex Wine library API function and type access
-@cindex access to Wine library API functions and types
-
-If Wine is built as a library, and linked to a user-level main program,
-the user will also use the standard @mswindows{} names for the API
-functions.
-
-Some macros are defined in @file{include/wintypes.h} which perform the
-necessary name mappings. 
-
-These macros are (see the examples below):
-@deffn_winemacro WINELIB_NAME (@var{xxx})
-This macro replaces @var{xxx} by one of @var{xxx}16 or
-@var{xxx}32, depending on the definition of the symbols
-@code{WINELIB16} and @code{WINELIB32}. @var{xxx} should
-be the name of an API function that uses no string arguments.
-Use this macro with a @code{#define} to establish the API name @var{xxx}.
-@end deffn
-@deffn_winemacro WINELIB_NAME_AW (@var{xxx})
-This macro replaces @var{xxx} by one of @var{xxx}16, @var{xxx}32A, or
-@var{xxx}32W, depending on the definition of the symbols
-@code{WINELIB16}, @code{WINELIB32}, and @code{UNICODE}. @var{xxx} should
-be the name of an API function that uses string arguments.
-Use this macro with a @code{#define} to establish the API name @var{xxx}.
-@end deffn
-@deffn_winemacro DECL_WINELIB_TYPE (@var{xxx})
-This macro declares @var{xxx} to be an equivalent to @var{xxx}16 or
-@var{xxx}32, depending on the definition of the symbols
-@code{WINELIB16} and @code{WINELIB32}. @var{xxx} should
-be the name of an API data type that contains no string arguments.
-@end deffn
-@deffn_winemacro DECL_WINELIB_TYPE_AW (@var{xxx})
-This macro declares the type @var{xxx} to be an equivalent to
-@var{xxx}16, @var{xxx}32A, or @var{xxx}32W, depending on the definition
-of the symbols @code{WINELIB16}, @code{WINELIB32}, and
-@code{UNICODE}. @var{xxx} should be the name of an API data type that
-contains string arguments. 
-@end deffn
-
-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 @var{xxx} itself will not be defined.
-
-Note: If the definition of @var{xxx} is exactly the same in @WIN16{} and
-@WIN32{}, you can simply use the same name as @mswindows{}.
-
-Here are some examples:
-@example
-/* 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)
-@end example
-
-The Winelib user can then say (in the application program):
-@example
-    INT i;
-    WNDCLASS wc = @{ @dots{} @};
-    RegisterClass( &wc );
-@end example
-and this will use the correct declaration depending on the definitions
-@code{WINELIB16}, @code{WINELIB32}, and @code{UNICODE}.
-
-Here are the primary defines that are used when Wine is compiled as a
-library:
-@defvr_cwine WINELIB16
-If this @code{#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 @code{@dots{}16}, which
-will perhaps have a behaviour different from its 32 bit counterpart.
-@end defvr
-@defvr_cwine WINELIB32
-If this @code{#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.
-@end defvr
-@defvr_cwine UNICODE
-This @code{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.
-@end defvr
-
-These switches are automatically set when Wine is compiled as a library.
-
-
-@node Access from inside Wine, , Access in the library, API function and type naming
-@subsection Accessing API functions from within Wine
-@cindex explicit names of API functions and types
-
-Within Wine and during the compilation of Wine, you cannot rely on the
-@mswindows{} 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.
-
-
-@node Creating patches, Adding Documentation, API function and type naming, The Wine Project
-@section Creating patches
-@xref{Applying patches}, for instructions on applying patches.
-
-Patches are created with the program @code{diff}. You need a copy
-of clean source tree to diff against. The @samp{-u} option, to create 
-unified diffs, is popular but not obligatory.
-For changes to a single file,
-@code{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 @code{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
-@xref{Applying patches}.
-
-@node Adding Documentation, File names, Creating patches, The Wine Project
-@section Adding Documentation
-
-@ifinfo
-Here are some templates which should help you collaborate on this
-documentation. Read the text below before examining them.
-@end ifinfo
-
-@menu
-* Type Template::               How to document data types in Wine's
-                                include files.
-* Function Template::           How to document an (API) function of
-                                Wine. 
-@end menu
-
-
-These are my tips for adding documentation.
-
-Do not simply copy documentation from @mswindows{} 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 @code{texinfo}.
-
-The rest of this section provides some templates which can serve as a
-start in writing documentation.
-
-@subsection Template introduction
-@iftex
-On the following pages you will find some @code{texinfo} templates, which
-should help you collaborate on this documentation.
-@end iftex
-
-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:
-@example
-@@c
-@@c *** struct FILETIME ***
-@@c
-@@node Type FILETIME, NextNodeName, PreviousNodeName, ParentNodeName
-@end example
-
-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
-@emph{Type} and @emph{type} are distinct. The node name must not contain
-special characters like @samp{@@, @{, @}} or the comma. If you need to
-give a node the same name as a function, data type, etc., use the words
-@samp{Type}, @samp{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:
-@example
-@@c
-@@c *** int  X   ***
-@@c *** long Y() ***
-@@c
-@@node Ints and Longs, NextNodeName, PreviousNodeName, ParentNodeName
-@end example
-
-After the node name, put a sectioning command, such as @samp{@@chapter},
-@samp{@@section}, @samp{@@subsection}, or @samp{@@subsubsection}.
-Without that command, cross references to the node will fail.
-@example
-@@subsubsection Type FILETIME
-@end example
-
-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.
-@example
-@@noindent
-File times in Wine are specified by the data type @@code@{FILETIME@},
-defined in @@file@{windows.h@}.
-@end example
-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.
-@example
-@@deftp_w32  FILETIME
-@@deftpx_w32 LPFILETIME
-@end example
-
-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 @mswindows{} situation but only say what Wine
-does. That is important. (Sometimes they might even do the same.)
-@example
-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.
-@end example
-
-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.
-@example
-The definition of @@code@{FILETIME@} reads:
-@@example
-typedef struct
-@@@{
-    INT32 dwLowDateTime;
-    INT32 dwHighDateTime;
-@@@} FILETIME, *LPFILETIME;
-@@end example
-@end example
-
-You could also use the @code{cindex} command which creates an entry in
-the concept index. The @code{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.
-@example
-@@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.
-@end example
-
-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 @mswindows{} products,
-i.e. whether the item is also present in @WINNT{} and @WIN95{}. The
-other one describes known differences of the Wine item to its
-@mswindows{} counterpart. Both will greatly help in porting software
-from @mswindows{} to Wine and vice versa.
-@example
-@@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.
-@end example
-
-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:
-@example
-@@end deftp
-@end example
-
-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.
-
-
-
-
-
-
-@node Type Template, Function Template, , Adding Documentation
-@subsection Data type template
-
-Category: Data type
-
-@node Function Template, , Type Template, Adding Documentation
-@subsection 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
-
-@example
-@@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
-@end example
-
-
-@node File names, Wide character strings, Adding Documentation, The Wine Project
-@section @mswindows{} and @unix{} file names in Wine
-@cindex file names in Wine
-@cindex Windows file names
-@cindex DOS file names in Wine
-@cindex UNIX file names in Wine
-@cindex POSIX file names in Wine
-
-FIXME:
-
-@node Wide character strings, , File names, The Wine Project
-@section Wide character strings in API functions
-@cindex unicode strings in API functions
-@cindex wide character strings in API functions
-@cindex strings in API functions
-@cindex ascii strings in API functions
-@cindex 16 bit characters in API functions
-@cindex wchar_t 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 @mswindows{}
-applications which have been compiled for wide character strings.
-
-In Wine, wide characters are strictly 16 bit; the @code{wchar_t} type of
-standard C can therefore not be used.
-
-@node Concept Index, , , Top
-@comment  node-name,  next,  previous,  up
-@unnumbered Concept Index
-@printindex cp
-
-@node Type Index, , , Top
-@comment  node-name,  next,  previous,  up
-@unnumbered Type Index
-@printindex tp
-
-@node Function Index, , , Top
-@comment  node-name,  next,  previous,  up
-@unnumbered Function Index
-@printindex fn
-
-@node Variable Index, , , Top
-@comment  node-name,  next,  previous,  up
-@unnumbered Variable, Constants, and Variable-like Macros Index
-@printindex vr
-
-@node File Index, , , Top
-@comment  node-name,  next,  previous,  up
-@unnumbered File and Program Index
-@printindex pg
-
-
-@contents
-@bye
-- 
GitLab