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

This file documents Wine, the Windows Emulator.

Copyright © 1997 The Wine authors.

See Authors, for a list of the copyright holders.

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions stated in the section entitled ``License, Warranty, and Authors of Wine''.

FIXME: UNIX and POSIX trademarks.

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.

Wine
****

This is edition 0.0.1, last updated 6 July 1997, of The Wine Reference Manual.

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

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

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

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

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

Wine is distributed under the following copyright.

          [file LICENSE not included]

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

          [file WARRANTY not included]

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

          [file AUTHORS not included]

These persons also hold the copyright on Wine.

The overall coordination is done by

Alexandre Julliard

julliard@lrc.epfl.ch

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

FIXME: Somebody should say some solemn words.

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

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

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

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

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

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

This section describes functions for manipulating dates and times. This includes the current time, the creation or manipulation times of files and other objects, and conversion between different time representations.

File Times
----------

File times in Wine are specified by the data type FILETIME, defined in windows.h.

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

          typedef struct _FILETIME
          {
              INT32 dwLowDateTime;
              INT32 dwHighDateTime;
          } FILETIME;

     The FILETIME structure may be used to hold absolute or relative times. Absolute times are given as the number of 100 nanoseconds intervals elapsed since 1 January 1601, 00:00:00 UTC (Coordinated Universal Time, which is GMT, Greenwich Mean Time). This might be called the epoch for file times. With a signed 64-bit value, this representation covers absolute times of 29247 years around the epoch.

     Differences to MS-Windows:

     In MS-Windows, the elements of the structure are apparently of type DWORD. Whether the full 64 bit value is interpreted as signed or unsigned I do not know.

The Wine function CompareFileTime compares two file times, and returns whether the first time is less than, equal to, or greater than the second file time. It is defined in windows.h.

 -- WIN32 function: LONG CompareFileTime (CONST FILETIME* TIME_1, CONST FILETIME* TIME_2)
     This function returns 1, if TIME_1 is greater than TIME_2, -1 if it is less, and 0 if both times are equal.

     Conformance to MS-Windows:

     Present in Windows 95 and Windows NT.

     Differences to MS-Windows:

     No differences known.

     Completion status:

     Not yet implemented.

FIXME: move this function to the file IO section.

The Wine function GetFileTime returns the creation time and the times of last the read and modification access to a file. It is defined in windows.h.

 -- WIN32 function: BOOL GetFileTime (HANDLE FILE, LPFILETIME CTIME, LPFILETIME ATIME, LPFILETIME MTIME)
     This function obtains for the specified FILE the creation time CTIME, the time of the last access to the file ATIME, and the time of the last modification (write) to the file, MTIME. The FILE handle must have been obtained by opening the file with GENERIC_READ access. The file time arguments of this function are pointers to FILETIME variables, which are filled with a value that indicates an absolute time in UTC. To convert these values to local times, use the function FileTimeToLocalFileTime. If you do not need some of the times, you can pass a NULL pointer. The function returns TRUE on success, FALSE on failure.

     Conformance to MS-Windows:

     Present in Windows 95 and Windows NT.

     Differences to MS-Windows:

     No differences known.

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

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

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

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

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

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

Resources
=========

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

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

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

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

Debugging
*********

Programs
********

Tools
*****

Wine Installation
*****************

FIXME: write installation guide

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

See Creating patches, for instructions on creating patches.

FIXME: write patch instructions

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

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

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

FIXME: what is most urgently needed

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

See Applying patches, for instructions on applying patches.

FIXME: how to create patches

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

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

FIXME they are not here in dvi

These are my tips for adding documentation.

Do not simply copy documentation from MS-Windows related material. Except from risking copyright violations, which you would not want to do, there is another aspect to that: As Wine is a product to run on UNIX and UNIX-like workstations, it seems a good idea to me to organize this documentation primarily for the well-trained UNIX reader. Please keep that in mind when you add some documentation.

Finally, read the info pages for texinfo.

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

These templates give hints on how to document data types, functions, variables, constants etc. in Wine. As documentation evolves, you will find common features of data types that should be described in a unified fashion. In such a case, please add a corresponding style guide-line here, in this very place, to help keeping documentation of data types unified.

Start out the type or function with a new node. Write a comment before the node, listing all data types (and functions) described in the node, like this:

     @c
     @c *** struct FILETIME ***
     @c
     @node Type FILETIME, NextNodeName, PreviousNodeName, ParentNodeName

The node command describes the node name and the names of the next node, the previous node, and the parent node. The parent node should contain a menu entry for this node. The previous node is the node that appears before this node in the parent node menu. The next node is the node succeeding this one in the parent node menu. If there is no previous or next node, omit the name (putting just a single space between the two commata).

The node name must be a unique sequence of words. Case is important, so Type and type are distinct. The node name must not contain special characters like @, {, } or the comma. If you need to give a node the same name as a function, data type, etc., use the words Type, Function, etc. before the identifier.

Always put the names of the node and its links on the same line, even if it gets rather long.

If there are two or more data types or functions described in the node, adapt the comment like this:

     @c
     @c *** int  X   ***
     @c *** long Y() ***
     @c
     @node Ints and Longs, NextNodeName, PreviousNodeName, ParentNodeName

Start the description of the type(s) or function(s) with a single non-indented paragraph that gives a one-line description of the type(s) or function(s) and states the include files that are required.

     @noindent
     File times in Wine are specified by the data type @code{FILETIME},
     defined in @file{windows.h}.

If several types or functions are closely connected, use one paragraph as a common description. If more paragraphs are required for a proper description, indent all but the first of them.

Then start the definition of the data type or function. Use the proper macro 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.

     @deftp {Data type} FILETIME

In the definition, give a verbal explanation of the data type or function. The explanation should be rather complete, exact, and comprehensible, than well-structured. This is the point where you can tell everything you want. Do not be afraid of wasting space. Do not describe the MS-Windows situation but only say what Wine does. That is important. (Sometimes they might even do the same.)

     This is the data type for specifying file times. The file times are
     stored with 64 bit precision. The actual data type is a structure with
     two 32 bit values which are interpreted as the low and high parts of a
     64-bit value. This value gives a time measured in a granularity of 100
     nanoseconds, so 1.5 seconds are specified by a value of 15,000,000.  In
     Wine, this 64-bit value is signed, with the sign taken from the high
     part. The lower part is used as unsigned.

For data types, it is recommended to quote the definition from the header file. For a function, you might give a short example of its usage. You may also put one example in the end of a node that explains several of the functions in the node. Remember that cut-and-paste from a well prepared example will help the readers write their code.

     The definition of @code{FILETIME} reads:
     @example
     typedef struct _FILETIME
     @{
         INT32 dwLowDateTime;
         INT32 dwHighDateTime;
     @} FILETIME;
     @end example

You could also use the cindex command which creates an entry in the concept index. The texinfo manual recommends to keep concept entries distinct, so that a single concept index entry puts to one well-defined place in the document. Use lower case letters for index entries, unless they are proper names or quotes from actual code.

     @cindex epoch in file time
     The @code{FILETIME} structure may be used to hold absolute or relative
     times. Absolute times are given as the number of 100 nanoseconds
     intervals elapsed since 1 January 1601, 00:00:00 UTC (Coordinated
     Universal Time, which is GMT, Greenwich Mean Time). This might be
     called the @dfn{epoch} for file times. With a signed 64-bit value, this
     representation covers absolute times of 29247 years around the epoch.

After the verbal documentation, you can add some special fields describing bugs, implementation dependencies etc. Two of these are recommended to attach to all descriptions. One describes the conformance of the data type or function to MS-Windows products, i.e. whether the item is also present in Windows NT and Windows 95. The other one describes known differences of the Wine item to its MS-Windows counterpart. Both will greatly help in porting software from MS-Windows to Wine and vice versa.

     @winconfall{}

     @windiff{}
     In @mswindows{}, the elements of the structure are apparently of type
     @code{DWORD}. Whether the full 64 bit value is interpreted as signed or
     unsigned I do not know.

If you find that more of these property attributes are necessary, feel free to create your own ones. But keep in mind that they should be applicable more or less to all described items. Very special properties will better be put into the verbal text.

Finally end the definition of the data type or function:

     @end deftp

Do not forget to enter the node in the menu of its top node, and do properly link the node to its successor and predecessor.

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

Category: Data type

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

Functions should be given category names, to indicate which API they belong to. Please add items to the list of categories possible.

Category: WIN32 function

     @c
     @c ***GetFileTime() ***
     @c
     @node Get File Times, , Compare File Times, File Times
     @noindent
     The Wine function @code{GetFileTime} returns the creation time and
     the times of last the read and modification access to a file. It is
     defined in @file{windows.h}.

     @deftypefn {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