\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). The Windows Emulator. END-INFO-DIR-ENTRY @end format @end ifinfo @iftex @c @finalout @end iftex @ifinfo This file documents Wine, the Windows Emulator. @c Copyright @copyright{} 1997 The Wine authors. @* @xref{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: UNIX and POSIX trademarks. @* MS-Windows, Windows-NT, Windows 95 are registered trademarks of Microsoft Corp. Postscript is a registered trademark of Adobe Systems Inc. All other product names mentioned herein are the trademarks of their respective owners. @end ifinfo @c begin chapters on right pages @setchapternewpage odd @titlepage @sp 10 @center @titlefont{The Wine Reference Manual} @center Edition 0.0.1, 6 July 1997 @c The following two commands start the copyright page. @page @vskip 0pt plus 1filll Copyright @copyright{} 1997 The Wine authors. @* @xref{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. @* MS-Windows, Windows-NT, Windows 95 are registered trademarks of Microsoft Corp. Postscript is a registered trademark of Adobe Systems Inc. All other product names mentioned herein are the trademarks of their respective owners. @end titlepage @c @c SETTINGS, DEFINES, MACROS @c @c Edit this macro manually in the above parts of the document @macro winemanualversion 0.0.1 @end macro @c Edit this macro manually in the above parts of the document @macro winemanualdate 6 July 1997 @end macro @c Edit this macro manually into the TeX titlepage @macro winemanualtitle {} The Wine Reference Manual @end macro @c @c MICROSOFT @c @c FIXME: automatical trademark reference @macro mswindows MS-Windows @end macro @c FIXME: automatical trademark reference @c spell it always the same @macro WIN32 WIN32 @end macro @c FIXME: automatical trademark reference @macro WINNT Windows NT @end macro @c FIXME: automatical trademark reference @macro WIN95 Windows 95 @end macro @c @c THE OTHERS @c @c FIXME: automatical trademark reference @macro unix UNIX @end macro @c FIXME: automatical trademark reference @macro posix POSIX @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 TOP NODE @c @ifinfo @node Top, Copying, (dir), (dir) @top Wine This is edition @winemanualversion{}, last updated @winemanualdate{}, of @winemanualtitle{}. Wine (Wine Is Not an Emulator, or the WINdows Emulator) is both an emulator that runs @mswindows{} executables and a library that can be used to compile @mswindows{} source code. Wine is free software. Wine is still in development-only state. @end ifinfo @menu * Copying:: License, Warranty, and Authors of Wine. * Introduction:: A short overview. * Reference Manual:: The Wine reference manual. * Installation:: Installing 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 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 @include 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@@lrc.epfl.ch} @node Introduction, Reference Manual, Copying, Top @chapter Introduction FIXME: Somebody should say some solemn words. @xref{The Wine Project}, if you consider contributing some work. @node Reference Manual, Installation, Introduction, 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. .everything except communication and windows * 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. * Get File Times:: Get the time attributes of a file. @end menu @c @c *** struct FILETIME *** @c @node Type FILETIME, Compare File Times, , File Times @noindent File times in Wine are specified by the data type @code{FILETIME}, defined in @file{windows.h}. @deftp {Data type} FILETIME 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 _FILETIME @{ INT32 dwLowDateTime; INT32 dwHighDateTime; @} FILETIME; @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. @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, Get 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 {WIN32 function} 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 @c @c ***GetFileTime *** @c @node Get File Times, , Compare File Times, File Times @noindent FIXME: move this function to the file IO section. @* 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 {WIN32 function} 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 @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 @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) @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 @node Installation, The Wine Project, Reference Manual, Top @chapter Wine Installation 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. FIXME: write patch instructions @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 * Creating patches:: How to create patches for Wine. * Adding Documentation:: Templates for the documentation. @end menu @xref{Debugging}, for advice on how to debug Wine. @xref{Applying patches}, for instructions on applying patches. FIXME: what is most urgently needed @node Creating patches, Adding Documentation, , The Wine Project @section Creating patches @xref{Applying patches}, for instructions on applying patches. FIXME: how to create patches @node Adding Documentation, , 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 FIXME they are not here in dvi @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}. @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 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 and specify a category and the formal definition on the same line. For proper categories, take a look at the specialized templates. Again, put everything that belongs to the header into a single line. @example @@deftp @{Data type@} FILETIME @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 _FILETIME @@@{ INT32 dwLowDateTime; INT32 dwHighDateTime; @@@} FILETIME; @@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 @{WIN32 function@} 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 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 Index @printindex vr @node File Index, , , Top @comment node-name, next, previous, up @unnumbered File and Program Index @printindex pg @contents @bye