\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 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. @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 FIXME: UNIX and POSIX trademarks. @* X11 @* Microsoft, Windows, MS-Windows, Windows-NT, Windows 95, and MS-DOS are registered trademarks of Microsoft Corporation. NT is a trademark of Northern Telecom Limited. C++Builder is a trademark of Borland International, Inc. Postscript is a registered trademark of Adobe Systems Inc. Other trademarks are the property of their respective owners, which may be registered in certain jurisdictions. @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