1 \input texinfo @c -*-texinfo-*-
4 @settitle Wine Reference Manual
13 * wine: (wine.info). The Windows Emulator.
23 This file documents Wine, the Windows Emulator.
26 Copyright @copyright{} 1997 The Wine authors. @*
27 @xref{Authors}, for a list of the copyright holders.
29 Permission is granted to make and distribute verbatim
30 copies of this manual provided the copyright notice and
31 this permission notice are preserved on all copies.
34 Permission is granted to process this file through TeX
35 and print the results, provided the printed document
36 carries a copying permission notice identical to this
37 one except for the removal of this paragraph (this
38 paragraph not being relevant to the printed manual).
41 Permission is granted to copy and distribute modified
42 versions of this manual under the conditions stated in
43 the section entitled ``License, Warranty, and Authors of Wine''.
46 FIXME: UNIX and POSIX trademarks. @*
47 MS-Windows, Windows-NT, Windows 95 are registered trademarks of
48 Microsoft Corp. Postscript is a registered trademark of Adobe Systems
49 Inc. All other product names mentioned herein are the trademarks of
50 their respective owners.
53 @c begin chapters on right pages
54 @setchapternewpage odd
59 @center @titlefont{The Wine Reference Manual}
60 @center Edition 0.0.1, 6 July 1997
63 @c The following two commands start the copyright page.
65 @vskip 0pt plus 1filll
67 Copyright @copyright{} 1997 The Wine authors. @*
68 @xref{Authors}, for a list of the copyright holders.
70 Permission is granted to make and distribute verbatim
71 copies of this manual provided the copyright notice and
72 this permission notice are preserved on all copies.
74 Permission is granted to copy and distribute modified
75 versions of this manual under the conditions stated in
76 the section entitled ``License, Warranty, and Authors of Wine''.
79 FIXME: UNIX and POSIX trademarks. @*
80 MS-Windows, Windows-NT, Windows 95 are registered trademarks of
81 Microsoft Corp. Postscript is a registered trademark of Adobe Systems
82 Inc. All other product names mentioned herein are the trademarks of
83 their respective owners.
89 @c SETTINGS, DEFINES, MACROS
92 @c Edit this macro manually in the above parts of the document
93 @macro winemanualversion
97 @c Edit this macro manually in the above parts of the document
102 @c Edit this macro manually into the TeX titlepage
103 @macro winemanualtitle {}
104 The Wine Reference Manual
111 @c FIXME: automatical trademark reference
116 @c FIXME: automatical trademark reference
117 @c spell it always the same
122 @c FIXME: automatical trademark reference
127 @c FIXME: automatical trademark reference
136 @c FIXME: automatical trademark reference
141 @c FIXME: automatical trademark reference
149 @c flag out differences to MS-Windows
151 @emph{Differences to @mswindows{}:} @*
156 No differences known.
159 @c tell whether function is present in Windows 95 and/or NT
161 @emph{Conformance to @mswindows{}:} @*
166 Present in @WIN95{} and @WINNT{}.
169 @c give information about completion
171 @emph{Completion status:} @*
174 @macro completionnone
189 @node Top, Copying, (dir), (dir)
192 This is edition @winemanualversion{}, last updated @winemanualdate{},
193 of @winemanualtitle{}.
195 Wine (Wine Is Not an Emulator, or the WINdows Emulator)
196 is both an emulator that runs @mswindows{} executables and a library
197 that can be used to compile @mswindows{} source code.
199 Wine is free software. Wine is still in development-only state.
203 * Copying:: License, Warranty, and Authors of Wine.
204 * Introduction:: A short overview.
205 * Reference Manual:: The Wine reference manual.
206 * Installation:: Installing Wine.
207 * The Wine Project:: How to contribute to Wine.
208 * Concept Index:: Index of concepts and names.
209 * Type Index:: Index of types and type qualifiers.
210 * Function Index:: Index of functions and function-like
212 * Variable Index:: Index of variables and variable-like
214 * File Index:: Index of programs and files.
217 @node Copying, Introduction, Top, Top
219 @unnumbered License, Warranty, and Authors of Wine.
220 @cindex copying conditions for Wine
221 @cindex conditions for copying Wine
222 @cindex Wine copying conditions
224 The Wine license, warranty, and list of authors together form the
225 copyright for Wine. Read these sections carefully.
228 * License:: The Wine license.
229 * Warranty:: Wine comes with no warranty.
230 * Authors:: The persons that contributed to Wine.
233 @node License, Warranty, , Copying
235 @cindex license of Wine
237 @unnumberedsec The Wine License
238 Wine is distributed under the following copyright.
244 @node Warranty, Authors, License, Copying
245 @cindex Wine warranty
246 @cindex warranty of Wine
248 @unnumberedsec The Wine Warranty
254 @node Authors, , Warranty, Copying
256 @cindex authors of Wine
257 @cindex copyright holders of Wine
258 @cindex Wine copyright holders
260 @unnumberedsec The Wine Authors
266 These persons also hold the copyright on Wine.
268 The overall coordination is done by @*
269 Alexandre Julliard @*
270 @email{julliard@@lrc.epfl.ch}
274 @node Introduction, Reference Manual, Copying, Top
275 @chapter Introduction
277 FIXME: Somebody should say some solemn words.
279 @xref{The Wine Project}, if you consider contributing some work.
282 @node Reference Manual, Installation, Introduction, Top
285 * @WIN32{} Reference Manual:: The @WIN32{} function calls and data types.
286 * Resources and INI files:: How to determine the appearance and
287 behaviour of Wine programs.
288 * Metafiles--Icons--Bitmaps:: FIXME missing.
289 * Debugging:: Debugging Wine.
290 * Programs:: Programs written to run in/with Wine.
291 * Tools:: Programs to support Wine.
294 @node @WIN32{} Reference Manual, Resources and INI files, , Reference Manual
295 @chapter The @WIN32{} Reference Manual
298 * Kernel Objects:: How the Wine kernel keeps information.
299 * Processes and Threads:: Job control and management in Wine.
300 * Users and Groups:: Security in Wine.
301 * Date and Time:: Functions for getting the date and time
302 and for conversion between formats.
303 * System Information:: Getting information about the hardware
304 and software the system runs on.
305 * Memory Management:: How your programs get memory from
307 * I/O Facilities:: Input/Output in Wine.
308 .everything except communication and windows
309 * Communication:: How processes can communicate.
310 * Windows and Graphics:: GUI functions of @WIN32{}.
311 * Errors and Exceptions:: How your program can report errors.
313 * Resources:: Functions for dealing with resources.
314 * The Registry:: FIXME missing.
315 * Dynamic Link Libraries:: Functions for dealing with DLL's.
318 @node Kernel Objects, Processes and Threads, , @WIN32{} Reference Manual
319 @section Kernel Objects
322 @node Processes and Threads, Users and Groups, Kernel Objects, @WIN32{} Reference Manual
323 @section Processes and Threads
325 @node Users and Groups, Date and Time, Processes and Threads, @WIN32{} Reference Manual
326 @section Users and Groups
328 @node Date and Time, System Information, Users and Groups, @WIN32{} Reference Manual
329 @section Date and Time
331 This section describes functions for manipulating dates and times. This
332 includes the current time, the creation or manipulation times of files
333 and other objects, and conversion between different time
337 * File Times:: Creation and manipulation times of files.
340 @node File Times, , , Date and Time
341 @subsection File Times
344 * Type FILETIME:: The data structure used for specifying
346 * Compare File Times:: Compare two file times.
347 * Get File Times:: Get the time attributes of a file.
351 @c *** struct FILETIME ***
353 @node Type FILETIME, Compare File Times, , File Times
356 File times in Wine are specified by the data type @code{FILETIME},
357 defined in @file{windows.h}.
359 @deftp {Data type} FILETIME
360 This is the data type for specifying file times. The file times are
361 stored with 64 bit precision. The actual data type is a structure with
362 two 32 bit values which are interpreted as the low and high parts of a
363 64-bit value. This value gives a time measured in a granularity of 100
364 nanoseconds, so 1.5 seconds are specified by a value of 15,000,000. In
365 Wine, this 64-bit value is signed, with the sign taken from the high
366 part. The lower part is used as unsigned.
368 The definition of @code{FILETIME} reads:
370 typedef struct _FILETIME
373 INT32 dwHighDateTime;
377 @cindex epoch in file time
378 The @code{FILETIME} structure may be used to hold absolute or relative
379 times. Absolute times are given as the number of 100 nanoseconds
380 intervals elapsed since 1 January 1601, 00:00:00 UTC (Coordinated
381 Universal Time, which is GMT, Greenwich Mean Time). This might be
382 called the @dfn{epoch} for file times. With a signed 64-bit value, this
383 representation covers absolute times of 29247 years around the epoch.
386 In @mswindows{}, the elements of the structure are apparently of type
387 @code{DWORD}. Whether the full 64 bit value is interpreted as signed or
388 unsigned I do not know.
392 @c *** CompareFileTime ***
394 @node Compare File Times, Get File Times, Type FILETIME, File Times
397 The Wine function @code{CompareFileTime} compares two file times, and
398 returns whether the first time is less than, equal to, or greater than
399 the second file time. It is defined in @file{windows.h}.
401 @deftypefn {WIN32 function} LONG CompareFileTime (@w{CONST FILETIME* @var{time_1},} @w{CONST FILETIME* @var{time_2})}
402 This function returns @code{1}, if @var{time_1} is greater than
403 @var{time_2}, @code{-1} if it is less, and @code{0} if both times are
414 @c ***GetFileTime ***
416 @node Get File Times, , Compare File Times, File Times
418 FIXME: move this function to the file IO section. @*
419 The Wine function @code{GetFileTime} returns the creation time and
420 the times of last the read and modification access to a file. It is
421 defined in @file{windows.h}.
423 @deftypefn {WIN32 function} BOOL GetFileTime (@w{HANDLE @var{file},} @w{LPFILETIME @var{ctime},} @w{LPFILETIME @var{atime},} @w{LPFILETIME @var{mtime})}
424 This function obtains for the specified @var{file} the creation time
425 @var{ctime}, the time of the last access to the file @var{atime}, and
426 the time of the last modification (write) to the file, @var{mtime}.
427 The @var{file} handle must have been obtained by opening the file with
428 @code{GENERIC_READ} access. The file time arguments of this function are
429 pointers to @code{FILETIME} variables, which are filled with a value that
430 indicates an absolute time in UTC. To convert these values to local
431 times, use the function @code{FileTimeToLocalFileTime}. If you do not
432 need some of the times, you can pass a @code{NULL} pointer.
433 The function returns @code{TRUE} on success, @code{FALSE} on failure.
441 @node System Information, Memory Management, Date and Time, @WIN32{} Reference Manual
442 @section System Information
444 @node Memory Management, I/O Facilities, System Information, @WIN32{} Reference Manual
445 @section Memory Management
447 @node I/O Facilities, Communication, Memory Management, @WIN32{} Reference Manual
448 @section I/O Facilities
450 @node Communication, Windows and Graphics, I/O Facilities, @WIN32{} Reference Manual
451 @section Communication
453 @node Windows and Graphics, Errors and Exceptions, Communication, @WIN32{} Reference Manual
454 @section Windows and Graphics
456 @node Errors and Exceptions, Resources, Windows and Graphics, @WIN32{} Reference Manual
457 @section Errors and Exceptions
459 @node Resources, The Registry, Errors and Exceptions, @WIN32{} Reference Manual
462 @node The Registry, Dynamic Link Libraries, Resources, @WIN32{} Reference Manual
463 @section The Registry
465 @node Dynamic Link Libraries, , The Registry, @WIN32{} Reference Manual
466 @section Dynamic Link Libraries (DLL's)
471 @node Resources and INI files, Metafiles--Icons--Bitmaps, @WIN32{} Reference Manual, Reference Manual
472 @chapter Resources and @file{INI} Files
474 @node Metafiles--Icons--Bitmaps, Debugging, Resources and INI files, Reference Manual
475 @chapter Metafiles --- Icons --- Bitmaps
477 @node Debugging, Programs, Metafiles--Icons--Bitmaps, Reference Manual
480 @node Programs, Tools, Debugging, Reference Manual
483 @node Tools, , Programs, Reference Manual
486 @node Installation, The Wine Project, Reference Manual, Top
487 @chapter Wine Installation
488 FIXME: write installation guide
491 * Applying patches:: How to update Wine to a newer version.
494 @node Applying patches, , , Installation
495 @section Applying patches
496 @xref{Creating patches}, for instructions on creating patches.
498 FIXME: write patch instructions
501 @node The Wine Project, , Installation, Top
502 @chapter The Wine project
503 @cindex Wine project contributions
504 @cindex project contributions to Wine
506 If you are new to Wine and want to support this project, here are
510 * Creating patches:: How to create patches for Wine.
511 * Adding Documentation:: Templates for the documentation.
514 @xref{Debugging}, for advice on how to debug Wine.
515 @xref{Applying patches}, for instructions on applying patches.
517 FIXME: what is most urgently needed
519 @node Creating patches, Adding Documentation, , The Wine Project
520 @section Creating patches
521 @xref{Applying patches}, for instructions on applying patches.
523 FIXME: how to create patches
525 @node Adding Documentation, , Creating patches, The Wine Project
526 @section Adding Documentation
529 Here are some templates which should help you collaborate on this
530 documentation. Read the text below before examining them.
533 FIXME they are not here in dvi
536 * Type Template:: How to document data types in Wine's
538 * Function Template:: How to document an (API) function of
543 These are my tips for adding documentation.
545 Do not simply copy documentation from @mswindows{} related
546 material. Except from risking copyright violations, which you would not
547 want to do, there is another aspect to that:
548 As Wine is a product to run on @unix{} and @unix{}-like workstations,
549 it seems a good idea to me to organize this documentation primarily for
550 the well-trained @unix{} reader. Please keep that in mind when you add
553 Finally, read the info pages for @code{texinfo}.
555 @subsection Template introduction
557 On the following pages you will find some @code{texinfo} templates, which
558 should help you collaborate on this documentation.
561 These templates give hints on how to document data types, functions,
562 variables, constants etc. in Wine.
563 As documentation evolves, you will find common features of data types
564 that should be described in a unified fashion. In such a case, please
565 add a corresponding style guide-line here, in this very place, to help
566 keeping documentation of data types unified.
569 Start out the type or function with a new node. Write a comment before
570 the node, listing all data types (and functions) described in the node,
574 @@c *** struct FILETIME ***
576 @@node Type FILETIME, NextNodeName, PreviousNodeName, ParentNodeName
579 The node command describes the node name and the names of the next node,
580 the previous node, and the parent node. The parent node should contain
581 a menu entry for this node. The previous node is the node that appears
582 before this node in the parent node menu. The next node is the node
583 succeeding this one in the parent node menu. If there is no previous or
584 next node, omit the name (putting just a single space between the two
587 The node name must be a unique sequence of words. Case is important, so
588 @emph{Type} and @emph{type} are distinct. The node name must not contain
589 special characters like @samp{@@, @{, @}} or the comma. If you need to
590 give a node the same name as a function, data type, etc., use the words
591 @samp{Type}, @samp{Function}, etc. before the identifier.
593 Always put the names of the node and its links on the same line, even if
596 If there are two or more data types or functions described in the node,
597 adapt the comment like this:
603 @@node Ints and Longs, NextNodeName, PreviousNodeName, ParentNodeName
606 Start the description of the type(s) or function(s) with a single
607 non-indented paragraph that gives a one-line description of the type(s)
608 or function(s) and states the include files that are required.
611 File times in Wine are specified by the data type @@code@{FILETIME@},
612 defined in @@file@{windows.h@}.
614 If several types or functions are closely connected, use one paragraph
615 as a common description. If more paragraphs are required for a proper
616 description, indent all but the first of them.
618 Then start the definition of the data type or function. Use the proper
619 macro and specify a category and the formal definition on the same
620 line. For proper categories, take a look at the specialized templates.
621 Again, put everything that belongs to the header into a single line.
623 @@deftp @{Data type@} FILETIME
626 In the definition, give a verbal explanation of the data type or
627 function. The explanation should be rather complete, exact, and
628 comprehensible, than well-structured. This is the point where you can
629 tell everything you want. Do not be afraid of wasting space.
630 Do not describe the @mswindows{} situation but only say what Wine
631 does. That is important. (Sometimes they might even do the same.)
633 This is the data type for specifying file times. The file times are
634 stored with 64 bit precision. The actual data type is a structure with
635 two 32 bit values which are interpreted as the low and high parts of a
636 64-bit value. This value gives a time measured in a granularity of 100
637 nanoseconds, so 1.5 seconds are specified by a value of 15,000,000. In
638 Wine, this 64-bit value is signed, with the sign taken from the high
639 part. The lower part is used as unsigned.
642 For data types, it is recommended to quote the definition from the
643 header file. For a function, you might give a short example of its
644 usage. You may also put one example in the end of a node that explains
645 several of the functions in the node. Remember that cut-and-paste from a
646 well prepared example will help the readers write their code.
648 The definition of @@code@{FILETIME@} reads:
650 typedef struct _FILETIME
653 INT32 dwHighDateTime;
658 You could also use the @code{cindex} command which creates an entry in
659 the concept index. The @code{texinfo} manual recommends to keep concept
660 entries distinct, so that a single concept index entry puts to one
661 well-defined place in the document. Use lower case letters for index
662 entries, unless they are proper names or quotes from actual code.
664 @@cindex epoch in file time
665 The @@code@{FILETIME@} structure may be used to hold absolute or relative
666 times. Absolute times are given as the number of 100 nanoseconds
667 intervals elapsed since 1 January 1601, 00:00:00 UTC (Coordinated
668 Universal Time, which is GMT, Greenwich Mean Time). This might be
669 called the @@dfn@{epoch@} for file times. With a signed 64-bit value, this
670 representation covers absolute times of 29247 years around the epoch.
673 After the verbal documentation, you can add some special fields
674 describing bugs, implementation dependencies etc. Two of these are
675 recommended to attach to all descriptions. One describes the
676 conformance of the data type or function to @mswindows{} products,
677 i.e. whether the item is also present in @WINNT{} and @WIN95{}. The
678 other one describes known differences of the Wine item to its
679 @mswindows{} counterpart. Both will greatly help in porting software
680 from @mswindows{} to Wine and vice versa.
685 In @@mswindows@{@}, the elements of the structure are apparently of type
686 @@code@{DWORD@}. Whether the full 64 bit value is interpreted as signed or
687 unsigned I do not know.
690 If you find that more of these property attributes are necessary, feel
691 free to create your own ones. But keep in mind that they should be
692 applicable more or less to all described items. Very special properties
693 will better be put into the verbal text.
695 Finally end the definition of the data type or function:
700 Do not forget to enter the node in the menu of its top node, and do
701 properly link the node to its successor and predecessor.
708 @node Type Template, Function Template, , Adding Documentation
709 @subsection Data type template
713 @node Function Template, , Type Template, Adding Documentation
714 @subsection API function template
716 Functions should be given category names, to indicate which API they
717 belong to. Please add items to the list of categories possible.
719 Category: WIN32 function
723 @@c ***GetFileTime() ***
725 @@node Get File Times, , Compare File Times, File Times
727 The Wine function @@code@{GetFileTime@} returns the creation time and
728 the times of last the read and modification access to a file. It is
729 defined in @@file@{windows.h@}.
731 @@deftypefn @{WIN32 function@} BOOL GetFileTime (@@w@{HANDLE @@var@{file@},@} @@w@{LPFILETIME @@var@{ctime@},@} @@w@{LPFILETIME @@var@{atime@},@} @@w@{LPFILETIME @@var@{mtime@})@}
732 This function obtains for the specified @@var@{file@} the creation time
733 @@var@{ctime@}, the time of the last access to the file @@var@{atime@}, and
734 the time of the last modification (write) to the file, @@var@{mtime@}.
735 The @@var@{file@} handle must have been obtained by opening the file with
736 @@code@{GENERIC_READ@} access. The file time arguments of this function are
737 pointers to @@code@{FILETIME@} variables, which are filled with a value that
738 indicates an absolute time in UTC. To convert these values to local
739 times, use the function @@code@{FileTimeToLocalFileTime@}. If you do not
740 need some of the times, you can pass a @@code@{NULL@} pointer.
741 The function returns @@code@{TRUE@} on success, @@code@{FALSE@} on failure.
753 @node Concept Index, , , Top
754 @comment node-name, next, previous, up
755 @unnumbered Concept Index
758 @node Type Index, , , Top
759 @comment node-name, next, previous, up
760 @unnumbered Type Index
763 @node Function Index, , , Top
764 @comment node-name, next, previous, up
765 @unnumbered Function Index
768 @node Variable Index, , , Top
769 @comment node-name, next, previous, up
770 @unnumbered Variable Index
773 @node File Index, , , Top
774 @comment node-name, next, previous, up
775 @unnumbered File and Program Index