Fixed some quirks (range is 32 bit, page up/dn mismatch on HZ trackbars).
[wine] / documentation / wine.texinfo
CommitLineData
d37eb365
AJ
1\input texinfo @c -*-texinfo-*-
2@c %**start of header
3@setfilename wine.info
4@settitle Wine Reference Manual
5@iftex
6@afourpaper
7@end iftex
8@c %**end of header
9
10@ifinfo
11@format
12START-INFO-DIR-ENTRY
692389d0 13* wine: (wine.info). Windows on Unix.
d37eb365
AJ
14END-INFO-DIR-ENTRY
15@end format
16@end ifinfo
17
18@iftex
19@c @finalout
20@end iftex
21
22@ifinfo
692389d0
DR
23This file documents Wine, a system providing Microsoft Windows compatibility
24to Unix.
d37eb365
AJ
25
26@c
a11d7b1a 27Copyright @copyright{} 1997,1998 The Wine authors. @*
641ee76a
AJ
28@xref{Authors, The Wine Authors, The Wine Authors},
29for a list of the copyright holders.
d37eb365
AJ
30
31Permission is granted to make and distribute verbatim
32copies of this manual provided the copyright notice and
33this permission notice are preserved on all copies.
34
35@ignore
36Permission is granted to process this file through TeX
37and print the results, provided the printed document
38carries a copying permission notice identical to this
39one except for the removal of this paragraph (this
40paragraph not being relevant to the printed manual).
41
42@end ignore
43Permission is granted to copy and distribute modified
44versions of this manual under the conditions stated in
45the section entitled ``License, Warranty, and Authors of Wine''.
46
47@sp 4
a11d7b1a
AJ
48FIXME: X11 and POSIX trademarks. @*
49UNIX is a registered trademark of the Open Group.
670cdc45
AJ
50Microsoft, Windows, MS-Windows, Windows-NT, Windows 95, and MS-DOS are
51registered trademarks of Microsoft Corporation.
52NT is a trademark of Northern Telecom Limited.
53C++Builder is a trademark of Borland International, Inc.
54Postscript is a registered trademark of Adobe Systems Inc.
55Other trademarks are the property of their respective owners, which may
56be registered in certain jurisdictions.
d37eb365
AJ
57@end ifinfo
58
59@c begin chapters on right pages
60@setchapternewpage odd
61
62@titlepage
d37eb365 63
a11d7b1a
AJ
64@title{The Wine Reference Manual}
65@subtitle{Edition 0.0.5, February 1998}
d37eb365 66
a11d7b1a 67@author{The Wine Team}
d37eb365
AJ
68@c The following two commands start the copyright page.
69@page
70@vskip 0pt plus 1filll
71
a11d7b1a 72Copyright @copyright{} 1997, 1998 The Wine authors. @*
641ee76a
AJ
73@xref{Authors, The Wine Authors, The Wine Authors},
74for a list of the copyright holders.
d37eb365
AJ
75
76Permission is granted to make and distribute verbatim
77copies of this manual provided the copyright notice and
78this permission notice are preserved on all copies.
79
80Permission is granted to copy and distribute modified
81versions of this manual under the conditions stated in
82the section entitled ``License, Warranty, and Authors of Wine''.
83
84@sp 4
85FIXME: UNIX and POSIX trademarks. @*
670cdc45
AJ
86X11 @*
87Microsoft, Windows, MS-Windows, Windows-NT, Windows 95, and MS-DOS are
88registered trademarks of Microsoft Corporation.
89NT is a trademark of Northern Telecom Limited.
90C++Builder is a trademark of Borland International, Inc.
91Postscript is a registered trademark of Adobe Systems Inc.
92Other trademarks are the property of their respective owners, which may
93be registered in certain jurisdictions.
d37eb365
AJ
94@end titlepage
95
96
97
98@c
99@c SETTINGS, DEFINES, MACROS
100@c
101
102@c Edit this macro manually in the above parts of the document
103@macro winemanualversion
a11d7b1a 1040.0.4
d37eb365
AJ
105@end macro
106
107@c Edit this macro manually in the above parts of the document
108@macro winemanualdate
a11d7b1a 109February 1998
d37eb365
AJ
110@end macro
111
112@c Edit this macro manually into the TeX titlepage
641ee76a 113@macro winemanualtitle
d37eb365
AJ
114The Wine Reference Manual
115@end macro
116
641ee76a
AJ
117@c
118@macro winelib
119Winelib
120@end macro
d37eb365
AJ
121@c
122@c MICROSOFT
123@c
124
a11d7b1a 125@c FIXME: automatic trademark reference
d37eb365
AJ
126@macro mswindows
127MS-Windows
128@end macro
129
a11d7b1a 130@c FIXME: automatic trademark reference
d37eb365
AJ
131@c spell it always the same
132@macro WIN32
133WIN32
134@end macro
641ee76a
AJ
135@macro WIN16
136WIN16
137@end macro
d37eb365 138
a11d7b1a 139@c FIXME: automatic trademark reference
d37eb365
AJ
140@macro WINNT
141Windows NT
142@end macro
143
a11d7b1a 144@c FIXME: automatic trademark reference
670cdc45
AJ
145@macro WINNT40
146Windows NT 4.0
147@end macro
148
a11d7b1a 149@c FIXME: automatic trademark reference
d37eb365
AJ
150@macro WIN95
151Windows 95
152@end macro
153
154
155@c
156@c THE OTHERS
157@c
a11d7b1a 158@c FIXME: automatic trademark reference
d37eb365
AJ
159@macro unix
160UNIX
161@end macro
162
a11d7b1a 163@c FIXME: automatic trademark reference
d37eb365
AJ
164@macro posix
165POSIX
166@end macro
641ee76a
AJ
167
168@macro unicode
169Unicode
170@end macro
171
172@macro ascii
173ASCII
174@end macro
175
d37eb365
AJ
176@c
177@c THIS MANUAL
178@c
179
180@c flag out differences to MS-Windows
181@macro windiff
182@emph{Differences to @mswindows{}:} @*
183@end macro
184
185@macro windiffnone
186@windiff{}
187No differences known.
188@end macro
189
190@c tell whether function is present in Windows 95 and/or NT
191@macro winconf
192@emph{Conformance to @mswindows{}:} @*
193@end macro
194
195@macro winconfall
196@winconf{}
197Present in @WIN95{} and @WINNT{}.
198@end macro
199
200@c give information about completion
201@macro completion
202@emph{Completion status:} @*
203@end macro
204
205@macro completionnone
206@completion{}
207Not yet implemented.
208@end macro
209
641ee76a
AJ
210@c
211@c MACROS FOR FUNCTIONS, TYPES, CONSTANTS, VARIABLES
212@c
d37eb365 213
641ee76a
AJ
214@c Constants in the WIN32 API
215@macro defvr_cw32 {restofline}
216@defvr Constant \restofline\
217@end macro
218@macro defvrx_cw32 {restofline}
219@defvrx Constant \restofline\
220@end macro
d37eb365 221
641ee76a
AJ
222@c Functions in the WIN32 API
223@macro deftypefn_w32 {restofline}
224@deftypefn {WIN32 function} \restofline\
225@end macro
226@macro deftypefnx_w32 {restofline}
227@deftypefnx {WIN32 function} \restofline\
228@end macro
d37eb365 229
641ee76a
AJ
230@c Types in the WIN32 API
231@macro deftp_w32 {restofline}
232@deftp {Data type} \restofline\
233@end macro
234@macro deftpx_w32 {restofline}
235@deftpx {Data type} \restofline\
236@end macro
d37eb365 237
641ee76a
AJ
238@c Macros internal to Wine
239@macro deffn_winemacro {restofline}
240@deffn {Wine internal macro} \restofline\
241@end macro
242@macro deffnx_winemacro {restofline}
243@deffn {Wine internal macro} \restofline\
244@end macro
245
246@c Constants internal to Wine
247@macro defvr_cwine {restofline}
248@defvr {Wine internal constant} \restofline\
249@end macro
250@macro defvrx_cwine {restofline}
251@defvrx {Wine internal constant} \restofline\
252@end macro
d37eb365
AJ
253
254
255@c
256@c TOP NODE
257@c
258@ifinfo
259@node Top, Copying, (dir), (dir)
260@top Wine
261
262This is edition @winemanualversion{}, last updated @winemanualdate{},
263of @winemanualtitle{}.
264
692389d0
DR
265Wine provides both source and binary compatibility with Microsoft Windows.
266The Wine API is designed to be as compatible as possible with various
267implementations of the Windows APIs. The Wine library allows porting
268Windows source to Unix, and a program loader allows unaltered Windows binaries
269to be run on Unix.
d37eb365 270
692389d0 271Wine is free software. Wine is still under development.
d37eb365
AJ
272@end ifinfo
273
274@menu
275* Copying:: License, Warranty, and Authors of Wine.
276* Introduction:: A short overview.
f90efa9c 277* Wine Design:: The design of Wine.
d37eb365 278* Reference Manual:: The Wine reference manual.
641ee76a 279* Installation:: Installing and configuring Wine.
d37eb365
AJ
280* The Wine Project:: How to contribute to Wine.
281* Concept Index:: Index of concepts and names.
282* Type Index:: Index of types and type qualifiers.
283* Function Index:: Index of functions and function-like
284 macros.
641ee76a
AJ
285* Variable Index:: Index of variables, constants, and
286 variable-like macros.
d37eb365
AJ
287* File Index:: Index of programs and files.
288@end menu
289
290@node Copying, Introduction, Top, Top
291
641ee76a 292@unnumbered License, Warranty, and Authors of Wine
d37eb365
AJ
293@cindex copying conditions for Wine
294@cindex conditions for copying Wine
295@cindex Wine copying conditions
296
297The Wine license, warranty, and list of authors together form the
298copyright for Wine. Read these sections carefully.
299
300@menu
301* License:: The Wine license.
302* Warranty:: Wine comes with no warranty.
303* Authors:: The persons that contributed to Wine.
304@end menu
305
306@node License, Warranty, , Copying
307@cindex Wine license
308@cindex license of Wine
309
310@unnumberedsec The Wine License
311Wine is distributed under the following copyright.
312
313@quotation
314@include LICENSE
315@end quotation
316
317@node Warranty, Authors, License, Copying
318@cindex Wine warranty
319@cindex warranty of Wine
320
321@unnumberedsec The Wine Warranty
322
323@quotation
324@include WARRANTY
325@end quotation
326
327@node Authors, , Warranty, Copying
328@cindex Wine authors
329@cindex authors of Wine
330@cindex copyright holders of Wine
331@cindex Wine copyright holders
332
333@unnumberedsec The Wine Authors
334
335@quotation
336@include AUTHORS
337@end quotation
338
339These persons also hold the copyright on Wine.
340
341The overall coordination is done by @*
342Alexandre Julliard @*
343@email{julliard@@lrc.epfl.ch}
344
345
346
f90efa9c 347@node Introduction, Wine Design, Copying, Top
d37eb365
AJ
348@chapter Introduction
349
641ee76a
AJ
350@strong{What is Wine?}
351
f90efa9c
AJ
352Wine is a Windows-compatibility layer for Unix and X11.
353The Wine system consists of several thing:
641ee76a
AJ
354@enumerate
355@item
f90efa9c
AJ
356An API, sometimes referred to as the Wine API,
357designed to be as compatible as possible with the
358@mswindows{} API
359@item
360A library, called @winelib{}, which implements this API
641ee76a 361@item
692389d0
DR
362A binary compatibility layer
363acts as a program loader for native Windows binaries.
364It works for both 16 and 32 bit Intel binaries, and
f90efa9c
AJ
365provides all the appropriate translation between 16 and 32 bit code
366(thunking). Real mode interrupts are also supported, and their
367functionality is implemented in @winelib{}.
641ee76a 368
641ee76a
AJ
369@end enumerate
370
f90efa9c 371@strong{System Requirements}
641ee76a 372
641ee76a 373
f90efa9c
AJ
374Wine provides binary support for Intel code on Intel hardware only.
375Neither hardware emulation
376nor non-Intel binaries are supported.
377@winelib{} should be possible to port to just about any Unix system.
641ee76a
AJ
378
379Currently, you must have one of:
380@itemize @bullet
381@item
382Linux version 0.99.13 or above
383@item
384NetBSD-current
385@item
386FreeBSD-current or FreeBSD 1.1
f90efa9c
AJ
387@item
388OpenBSD/i386 2.1 or later
389@item
390Solaris x86 2.5 or later
641ee76a
AJ
391@end itemize
392You need X11, and you must have @file{libXpm} installed on your system.
393
394@strong{Availability}
395
f90efa9c
AJ
396Wine is free software; the license is BSD-style. Basically, you can do
397anything with it, except claim that you wrote it.
641ee76a
AJ
398@xref{Copying}, for more information.
399
641ee76a
AJ
400@strong{Further information}
401
402You should consult the files @file{README}, @file{ANNOUNCE},
403@file{RELEASE-NOTES}, @file{BUGS}, @file{LICENSE}, and @file{WARRANTY},
404in the root directory of the Wine distribution.
405
f90efa9c
AJ
406The Wine USENET newsgroup @url{news:comp.emulators.ms-windows.wine}
407is useful for both Wine developers and Wine users. The Wine home page
408is @url{http://www.winehq.com/}.
409
410@node Wine Design, Reference Manual, Introduction, Top
411@chapter Wine Design
412
413@subsection The Wine Graphics Driver Model
414
415Wine, like Windows, abstracts drawing code so that applications may access
416a wide variety of devices, from different kinds of graphics cards,
417X displays and printers, using a single unified graphics model.
418This model is referred to as GDI: _G_raphics _D_river _I_nterface.
419This section discusses the Wine implementation of GDI.
420There are 61 functions in the Wine graphics model, including Arc, BitBlt,
421Chord, etc. For a complete list and prototypes, see the definition
422of DC_FUNCTIONS in [include/gdi.h].
423
424Wine, as of 2Q1998, has three native drivers: these provide support
425for rendering to X displays, metafiles, and Win16 native printer drivers.
426As far as Wine is concerned, a driver
427simply consists of a name and a table of function pointers
428(see [graphics/driver.c]). These functions
429are the driver's implementation of the various Wine graphics
430operations (the GDI). Wine maintains a linked list of all drivers which
431register themselves with Wine, as well as a ``generic''
432driver. Currently, the X11 driver registers itself as DISPLAY, the
433win16 driver registers itself as the generic driver, and the metafile
434driver doesn't register itself at all.
435
436@subsubsection How a driver function gets invoked
437
438All drawing by Wine applications
439is done in terms of a Device Context (DC).
440Before an application can draw, it must create a DC, and all drawing calls
441must pass a handle to the DC they wish to draw to.
442[include/gdi.h] defines several structures relating to DCs, including
443DC, WIN_DC_INFO, and DeviceCaps. The DeviceCaps structure is at the lowest
444level: it holds
445information relating to specifics of the graphics display
446hardware and associated
447driver.
448WIN_DC_INFO holds information about several device independent
449modes the DC can be in, plus a pointer to DeviceCaps.
450Finally,
451the DC structure is the toplevel structure usually passed around.
452It holds viewport information, a pointer to WIN_DC_INFO, and a
453pointer to the function table to be used while rendering that DC.
454This function table is filled at the time of creating the DC.
455
456@c Modes
457
458@c Some discussion of the various modalities available to a DC would be nice.
459
460@c Coordinate Systems
461
462@c Some discussion of the maze of coordinate systems would also be nice.
463
464@c Device Coordinates
465
466@c Logical Coordinates
467
468@c World transforms
469
470
471@subsubsection The X11 driver
472
473As a part of the Wine loading process,
474X11DRV_Init in [graphics/x11drv/init.c] is called.
475This initializes various aspects of the X11 driver and
476registers it as DISPLAY. This function first
477calls initialization procedures for various parts of the X11 driver.
478It then
479creates and
480fills a static DeviceCaps
481structure to be used for every X11 DC.
482Finally, it fills the table of GDI functions to be used for X11
483rendering and registers itself as ``DISPLAY''.
484
485@subsubsection The Metafile Driver
486
487The metafile driver is unusual, in that it is not a driver for any
488kind of display device, but rather a mechanism which allows using
489the Wine graphics model as a file format for saving graphics.
490The advantage of this is that it allows using identical formats for
491saving pictures as is actually used to display them; it is analogous
492to Display PostScript.
493
494The metafile driver is invoked explicitly by the application. The
495application calls CreateMetaFile() to create a special DC for recording
496graphics drawing operations in a metafile. Any drawing operations
497performed in this DC are not drawn physically anywhere, they are
498instead stored in the metafile. The DC is explicitly destroyed by a
499call to CloseMetaFile(), which also finishes writing the metafile.
500Metafiles may be written either to a file or to memory. Later, the
501metafile can be rendered (in a physical DC) by PlayMetaFile().
502
503The way that this works is that device contexts contain a pointer
504to the function lookup table for drawing operations appropriate for
505that device.
506
507Not all functions in the Wine graphics model are relevant to metafiles, but
508some relevant but rarely used functions are unimplemented.
509
510@subsubsection The WIN16 Driver
511
512WIN16DRV_Init is called by MAIN_EmulatorInit, and registers the
513WIN16DRV function table WIN16DRV_Funcs [graphics/win16drv/init.c]
514for the generic driver. The WIN16 driver is designed to load
515specified native Windows printer drivers. I don't understand
516how the whole scheme works,
517start studying what happens when a printer DC is
518created via WIN16DRV_CreateDC.
519
520If a DC is created explicitly, via the
521CreateDC() call, the driver name is specified explicitly and Wine
522finds the appropriate driver by leafing through its table of registered
523drivers. Metafile DCs can only be created by the CreateMetaFile function.
524
525Alternatively, most of the time, the DISPLAY driver is invoked
526implicitly.
527The application creates a window with
528CreateWindow(). If the CS_CLASSDC or CS_OWNDC flag is passed, a new DC
529is created and saved for the window in a structure called DCE, which holds
530a DC, a clipping region, and flags. Whenever the application wants to
531paint in that window, it calls GetDC(hwnd), which returns the DC in the
532DCE saved in the window.
533
534If neither of those flags are used, the window gets a DCE assigned to it
535from a pool of DCEs created during Wine initialization and temporarily
536assigned during the GetDC() call.
537All DCEs, whether part of the Wine DC pool or created by request of a window,
538use the ``DISPLAY'' driver.
539
540
541@node Reference Manual, Installation, Wine Design, Top
d37eb365
AJ
542
543@menu
7692b583 544* @WIN32{} Reference Manual:: The @WIN32{} function calls and data types.
d37eb365
AJ
545* Resources and INI files:: How to determine the appearance and
546 behaviour of Wine programs.
7692b583 547* Metafiles--Icons--Bitmaps:: FIXME missing.
d37eb365
AJ
548* Debugging:: Debugging Wine.
549* Programs:: Programs written to run in/with Wine.
550* Tools:: Programs to support Wine.
551@end menu
552
553@node @WIN32{} Reference Manual, Resources and INI files, , Reference Manual
554@chapter The @WIN32{} Reference Manual
555
556@menu
557* Kernel Objects:: How the Wine kernel keeps information.
558* Processes and Threads:: Job control and management in Wine.
559* Users and Groups:: Security in Wine.
560* Date and Time:: Functions for getting the date and time
561 and for conversion between formats.
562* System Information:: Getting information about the hardware
563 and software the system runs on.
564* Memory Management:: How your programs get memory from
565 Wine.
566* I/O Facilities:: Input/Output in Wine.
d37eb365
AJ
567* Communication:: How processes can communicate.
568* Windows and Graphics:: GUI functions of @WIN32{}.
569* Errors and Exceptions:: How your program can report errors.
641ee76a 570 (messaging)
d37eb365
AJ
571* Resources:: Functions for dealing with resources.
572* The Registry:: FIXME missing.
573* Dynamic Link Libraries:: Functions for dealing with DLL's.
574@end menu
575
576@node Kernel Objects, Processes and Threads, , @WIN32{} Reference Manual
577@section Kernel Objects
578
579
580@node Processes and Threads, Users and Groups, Kernel Objects, @WIN32{} Reference Manual
581@section Processes and Threads
582
583@node Users and Groups, Date and Time, Processes and Threads, @WIN32{} Reference Manual
584@section Users and Groups
585
586@node Date and Time, System Information, Users and Groups, @WIN32{} Reference Manual
587@section Date and Time
588
589This section describes functions for manipulating dates and times. This
590includes the current time, the creation or manipulation times of files
591and other objects, and conversion between different time
592representations.
593
594@menu
595* File Times:: Creation and manipulation times of files.
596@end menu
597
598@node File Times, , , Date and Time
599@subsection File Times
600
601@menu
602* Type FILETIME:: The data structure used for specifying
603 file times.
604* Compare File Times:: Compare two file times.
d37eb365
AJ
605@end menu
606
607@c
608@c *** struct FILETIME ***
609@c
610@node Type FILETIME, Compare File Times, , File Times
641ee76a 611@subsubsection Type FILETIME
d37eb365
AJ
612
613@noindent
614File times in Wine are specified by the data type @code{FILETIME},
615defined in @file{windows.h}.
641ee76a
AJ
616@deftp_w32 FILETIME
617@deftpx_w32 LPFILETIME
d37eb365
AJ
618This is the data type for specifying file times. The file times are
619stored with 64 bit precision. The actual data type is a structure with
641ee76a 620two 32-bit values which are interpreted as the low and high parts of a
d37eb365
AJ
62164-bit value. This value gives a time measured in a granularity of 100
622nanoseconds, so 1.5 seconds are specified by a value of 15,000,000. In
623Wine, this 64-bit value is signed, with the sign taken from the high
624part. The lower part is used as unsigned.
625
626The definition of @code{FILETIME} reads:
627@example
641ee76a 628typedef struct
d37eb365
AJ
629@{
630 INT32 dwLowDateTime;
631 INT32 dwHighDateTime;
641ee76a 632@} FILETIME, *LPFILETIME;
d37eb365
AJ
633@end example
634
635@cindex epoch in file time
636The @code{FILETIME} structure may be used to hold absolute or relative
637times. Absolute times are given as the number of 100 nanoseconds
638intervals elapsed since 1 January 1601, 00:00:00 UTC (Coordinated
639Universal Time, which is GMT, Greenwich Mean Time). This might be
640called the @dfn{epoch} for file times. With a signed 64-bit value, this
641representation covers absolute times of 29247 years around the epoch.
641ee76a
AJ
642To convert this type to local time, use the function
643@code{FileTimeToLocalFileTime}.
d37eb365
AJ
644
645@windiff{}
646In @mswindows{}, the elements of the structure are apparently of type
647@code{DWORD}. Whether the full 64 bit value is interpreted as signed or
648unsigned I do not know.
649@end deftp
650
651@c
652@c *** CompareFileTime ***
653@c
641ee76a 654@node Compare File Times, , Type FILETIME, File Times
d37eb365
AJ
655
656@noindent
657The Wine function @code{CompareFileTime} compares two file times, and
658returns whether the first time is less than, equal to, or greater than
659the second file time. It is defined in @file{windows.h}.
641ee76a 660@deftypefn_w32 LONG CompareFileTime (@w{CONST FILETIME* @var{time_1},} @w{CONST FILETIME* @var{time_2})}
d37eb365
AJ
661This function returns @code{1}, if @var{time_1} is greater than
662@var{time_2}, @code{-1} if it is less, and @code{0} if both times are
663equal.
664
665@winconfall{}
666
667@windiffnone{}
668
669@completionnone{}
670@end deftypefn
671
641ee76a
AJ
672@node System Information, Memory Management, Date and Time, @WIN32{} Reference Manual
673@section System Information
674
675@node Memory Management, I/O Facilities, System Information, @WIN32{} Reference Manual
676@section Memory Management
677
678@node I/O Facilities, Communication, Memory Management, @WIN32{} Reference Manual
679@section I/O Facilities
680
681This section describes all input/output of a process, except for two
682topics: communication with other processes, and communication with the
683windowing system.
684
685@menu
686* I/O on Files:: Accessing the contents of files.
687* File System Interface:: Functions for manipulating files as a whole.
688@end menu
689
690@node I/O on Files, File System Interface, , I/O Facilities
691@subsection I/O on Files
692
693@node File System Interface, , I/O on Files, I/O Facilities
694@subsection File System Interface
695
696These functions are concerned with operating on files themselves, rather
697than on their contents.
698
699@menu
700* Type BY_HANDLE_FILE_INFORMATION:: The data structure used to
701 specify file information.
702* File attributes:: The file attributes flags in
703 a file information structure.
704* Getting file information:: These functions let you obtain
705 information about a file.
706@end menu
707
708@node Type BY_HANDLE_FILE_INFORMATION, File attributes, , File System Interface
709@subsubsection The file information structure
710
711The file information structure of Wine is used to obtain information
712about files. It is declared in the header @file{winedows.h}.
713@deftp_w32 BY_HANDLE_FILE_INFORMATION
714This is the data type for specifying information about files as objects
715of the file system. It contains the following members:
716@table @code
717@item int dwFileAttributes
718 @cindex file attributes in file information
719 @cindex attributes of file in file information
720 @xref{File attributes}, for details.
721@item FILETIME ftCreationTime
722 @cindex creation time in file information
723 @cindex time of file creation in file information
724 The time when the file was created.
725 @xref{Type FILETIME}, for details.
726@item FILETIME ftLastAccessTime
727 @cindex access time in file information
728 @cindex time of file access in file information
729 The time when the file was last accessed.
730 @xref{Type FILETIME}, for details.
731@item FILETIME ftLastWriteTime
732 @cindex write time in file information
733 @cindex time of last file write in file information
734 The time when the file was last written to.
735 @xref{Type FILETIME}, for details.
736@item int dwVolumeSerialNumber
737 @cindex serial number of volume in file information
738 @cindex volume number (serial) in file information
739 The serial number of the volume containing the file. In Wine,
740 currently 0.
741@item int nFileSizeHigh
742 @cindex file size in file information
743 @cindex size of file in file information
744 A 32 bit value which contains the high part of the 64 bit file size.
745@item int nFileSizeLow
746 A 32 bit value which contains the low part of the 64 bit file size.
747@item int nNumberOfLinks
748 @cindex hard links number in file information
749 @cindex links (number of hard) in file information
750 This is the number of hard links to the file. In a file system which
751 does not support hard links, this is 1.
752@item int nFileIndexHigh
753 @cindex inode number in file information
754 @cindex file index in file information
755 @cindex index of file in file information
756 A 32 bit value which contains the high part of the 64 bit file
757 index. The file index is a unique number for a file on a volume.
758 This identifier cannot change while the file is opened by a process.
759 Together with the volume number, the file index is a unique
760 identifier for the file. This can be used by an application to check
761 whether two handles refer to the same file. Wine currently uses the
762 inode number for the file index.
763@item int nFileIndexLow
764 A 32 bit value which contains the low part of the 64 bit file index.
765@end table
766
767The definition of @code{BY_HANDLE_FILE_INFORMATION} reads:
768@example
769typedef struct
770@{
771 int dwFileAttributes;
772 FILETIME ftCreationTime;
773 FILETIME ftLastAccessTime;
774 FILETIME ftLastWriteTime;
775 int dwVolumeSerialNumber;
776 int nFileSizeHigh;
777 int nFileSizeLow;
778 int nNumberOfLinks;
779 int nFileIndexHigh;
780 int nFileIndexLow;
781@} BY_HANDLE_FILE_INFORMATION ;
782@end example
783
784The @code{BY_HANDLE_FILE_INFORMATION} structure can be obtained by the
785@code{GetFileInformationByHandle} function (@pxref{Getting file information}, for
786details).
787
788@windiff{}
789In @mswindows{}, the @code{int} elements of the structure are apparently
790of type @code{DWORD}.
791@end deftp
792
793@node File attributes, Getting file information, Type BY_HANDLE_FILE_INFORMATION, File System Interface
794@subsubsection The file attributes in a file information structure
795
796The file attributes in a file information structure and in other structures
797are a logical @emph{or} of one or more of the following constants:
798
799@defvr_cw32 FILE_ATTRIBUTE_READONLY
800The file is a read-only file. (Wine value: 0x0001).
801@end defvr
802@defvr_cw32 FILE_ATTRIBUTE_HIDDEN
803The file is a hidden file. Files in Wine do not have this attribute. (Wine value:
8040x0002).
805@end defvr
806@defvr_cw32 FILE_ATTRIBUTE_SYSTEM
807The file belongs to the operating system. Files in Wine do not have this
808attribute. (Wine value: 0x0004).
809@end defvr
810@defvr_cw32 FILE_ATTRIBUTE_LABEL
811This is not present in the @mswindows{} API. (Wine value: 0x0008).
812@end defvr
813@defvr_cw32 FILE_ATTRIBUTE_DIRECTORY
814The file is a directory. (Wine value: 0x0010).
815@end defvr
816@defvr_cw32 FILE_ATTRIBUTE_ARCHIVE
670cdc45
AJ
817The file is an archive file. Currently, all non-directory files are
818reported by Wine to have this attribute. This attribute is normally set
819by @mswindows{} to indicate that a file is to be archived; when the file
820is archived, the flag is cleared. (Wine value: 0x0020).
641ee76a
AJ
821@end defvr
822@defvr_cw32 FILE_ATTRIBUTE_NORMAL
823The file does not have any other attributes set. This value must be used
824alone. In Wine, normal files are reported as archive files. (Wine value:
8250x0080).
826@end defvr
827@defvr_cw32 FILE_ATTRIBUTE_TEMPORARY
828The file is used as a temporary storage. Files in Wine do not have this
829attribute. (Wine value: 0x0100).
830@end defvr
831@defvr_cw32 FILE_ATTRIBUTE_ATOMIC_WRITE
832This is reserved for future use. Files in Wine do not have this
833attribute. (Wine value: 0x0200).
834@end defvr
835@defvr_cw32 FILE_ATTRIBUTE_XACTION_WRITE
836This is reserved for future use. Files in Wine do not have this
837attribute. (Wine value: 0x0400).
838@end defvr
839@defvr_cw32 FILE_ATTRIBUTE_COMPRESSED
840The file is compressed. Files in Wine do not have this attribute. (Wine
841value: 0x0800).
842@end defvr
843
844@node Getting file information, , File attributes, File System Interface
845@subsubsection Getting file information
846
847The functions in this section describe how to get information about
848files.
849
850@c
851@c *** GetFileInformationByHandle
852@c
853@noindent
854The Wine function @code{GetFileInformationByHandle} returns a file
855information structure. It is defined in @file{windows.h}.
856
857@deftypefn_w32 BOOL GetFileInformationByHandle (@w{HFILE32 @var{file},} @w{BY_HANDLE_FILE_INFORMATION *@var{info})}
858This function obtains for the specified @var{file} the file information,
859and stores it in @var{info}. The file information contains the file
860attributes, the file times, the volume serial number, the file size, the
861number of links, and a unique file identifier. The function returns
862@code{TRUE} on success, @code{FALSE} on failure.
863
864@winconfall{}
865
866@windiff{}
867The Wine function can of course only give back information that is
868accessible in the @unix{} file system. File times are produced in a
869granularity of full seconds. Most file attributes are not present in the
870@unix{} file system. @xref{File attributes}, for details. The volume
871serial number is set to 0.
872@end deftypefn
873
874
d37eb365 875@c
641ee76a 876@c *** GetFileTime ***
d37eb365 877@c
d37eb365 878@noindent
d37eb365
AJ
879The Wine function @code{GetFileTime} returns the creation time and
880the times of last the read and modification access to a file. It is
881defined in @file{windows.h}.
882
641ee76a 883@deftypefn_w32 BOOL GetFileTime (@w{HANDLE @var{file},} @w{LPFILETIME @var{ctime},} @w{LPFILETIME @var{atime},} @w{LPFILETIME @var{mtime})}
d37eb365
AJ
884This function obtains for the specified @var{file} the creation time
885@var{ctime}, the time of the last access to the file @var{atime}, and
886the time of the last modification (write) to the file, @var{mtime}.
641ee76a
AJ
887The file time arguments of this function are pointers to @code{FILETIME}
888variables, which are filled with a value that indicates an absolute time
889in UTC. @xref{Type FILETIME}, for details. If you do not need some of
890the times, you can pass a @code{NULL} pointer.
891The function returns @code{TRUE} on
892success, @code{FALSE} on failure.
d37eb365
AJ
893
894@winconfall{}
895
641ee76a
AJ
896@windiff{}
897The file times are produced in a granularity of full seconds, due to the
898underlying @unix{} file system.
d37eb365
AJ
899@end deftypefn
900
641ee76a
AJ
901@c
902@c *** GetFileAttributes ***
903@c
904@noindent
905The Wine function @code{GetFileAttributes} returns the file attributes
906for a file. It is defined in @file{windows.h}.
907
908@deftypefn_w32 DWORD GetFileAttributes (@w{LPCTSTR @var{name})}
909This function looks up the file with name @var{name}, and returns the
910attributes of the file. @xref{File attributes}, for details on the file
911attributes. If the function is not successful, it returns a word with
912all bits set (@samp{0xffffffff}).
913
914@winconfall{}
915
916@windiff{}
917Most file attributes are not present in the
918@unix{} file system. @xref{File attributes}, for details.
919@end deftypefn
d37eb365 920
d37eb365 921
d37eb365 922
d37eb365
AJ
923
924@node Communication, Windows and Graphics, I/O Facilities, @WIN32{} Reference Manual
925@section Communication
926
927@node Windows and Graphics, Errors and Exceptions, Communication, @WIN32{} Reference Manual
928@section Windows and Graphics
929
930@node Errors and Exceptions, Resources, Windows and Graphics, @WIN32{} Reference Manual
931@section Errors and Exceptions
932
933@node Resources, The Registry, Errors and Exceptions, @WIN32{} Reference Manual
934@section Resources
935
936@node The Registry, Dynamic Link Libraries, Resources, @WIN32{} Reference Manual
937@section The Registry
938
939@node Dynamic Link Libraries, , The Registry, @WIN32{} Reference Manual
940@section Dynamic Link Libraries (DLL's)
941
641ee76a
AJ
942This section deals with API functions for handling DLL's (dynamic link
943libraries). It does not describe DLL's themselves; nor does it give
944information on how Wine handles DLL's. @xref{The build program}, for
945information on how DLL's are integrated into Wine.
946
d37eb365
AJ
947
948
949
950@node Resources and INI files, Metafiles--Icons--Bitmaps, @WIN32{} Reference Manual, Reference Manual
951@chapter Resources and @file{INI} Files
952
953@node Metafiles--Icons--Bitmaps, Debugging, Resources and INI files, Reference Manual
954@chapter Metafiles --- Icons --- Bitmaps
955
956@node Debugging, Programs, Metafiles--Icons--Bitmaps, Reference Manual
957@chapter Debugging
958
959@node Programs, Tools, Debugging, Reference Manual
960@chapter Programs
961
962@node Tools, , Programs, Reference Manual
963@chapter Tools
964
641ee76a
AJ
965This chapter describes some of the tools that are used by Wine. These
966are not user-level programs which the user of Wine will
5ca7bae8 967run. @xref{Programs}, for such programs.
641ee76a
AJ
968
969Tools are internal programs that are used to help compile or configure
970Wine.
971
972@menu
973* The build program:: A program used to build the DLL entry
974 points from specifications in @file{if1632/}.
975@end menu
976
977
978@node The build program, , , Tools
979@section The @file{build} program
980
981@cindex modules of Wine
982@cindex Wine modules
983@cindex DLL's built-in in Wine
984@cindex Wine DLL's built-in
985@cindex built-in DLL's in Wine
986Wine contains several modules that implement various DLL's which are
987required to run @mswindows{} programs.
988
989The @file{build} program, located in the @file{tools/} directory, is
990used to create the bindings for the DLL entry points of the API functions.
991This program reads a @file{.spec}-file in the @file{if1632} directory
992and creates the assembly code that translates the function arguments
993correctly.
994
995
996@menu
997* The spec files:: The format of the @file{.spec}-files.
998@end menu
999
1000FIXME: where in Wine are the DLL's affixed?
1001
1002FIXME: write a description
1003
1004@xref{Implementing an API function}, for notes on using this program.
1005
1006@node The spec files, , , The build program
1007@subsection The @file{.spec}-files
1008@cindex DLL spec files
1009@cindex spec files of DLL's
1010@cindex entry points in DLL's
1011
1012This subsection describes the format of the @file{.spec}-files.
1013
1014A @file{.spec}-file contains the information about the functions,
1015variables, and constants that are contained in a DLL (dynamic link
1016library).
1017
1018To be able to interpret the contents of a @file{.spec}-file, you must
1019know about the concept of ordinals.
1020@menu
1021* The general format:: General format conventions.
1022* Ordinals:: Ordinals are indexes of entry
1023 points into DLL's.
1024* Spec file header:: The header information.
1025* Variable entry points:: Entries for DLL variables.
1026* Function entry points:: Entries for DLL functions.
1027* Special entries:: Entries for stubs, dummy
1028 functions, Wine symbols, and
1029 constant values.
1030@end menu
1031
1032@node The general format, Ordinals, , The spec files
1033@subsubsection The general format
1034@cindex format of spec files
1035@cindex spec files format
1036
1037The @file{.spec}-file contains a header and a sequence of declarations.
1038Each declaration describes an ordinal.
1039
1040The header gives general information about the DLL and its properties.
1041
1042Ordinal declarations are optional. That means that there is a default
1043behaviour assigned to ordinals which are not mentioned in the
1044@file{.spec}-file. The default handler function of an ordinal will print
1045an error message when called.
1046
1047Comments are indicated by hash marks (@samp{#}); everything between a
1048hash mark and the end of the line is ignored.
1049
1050Empty lines are allowed.
1051@* FIXME: is that so?
1052
1053@node Ordinals, Spec file header, The general format, The spec files
1054@subsubsection Ordinals
1055@cindex ordinals in DLL's
1056@cindex DLL ordinals
1057
1058All references to DLL objects like functions or variables are indexed by
1059unique nonnegative numbers. These numbers are called
1060@dfn{ordinals}. Apparently, a program can refer to a DLL function or
1061variable by specifying its name or its ordinal. Although reference by
1062name is the common usage, some program parts (notably DLL's themselves)
1063sometimes refer to DLL entries by ordinal. Therefore, the ordinals
1064cannot be chosen arbitrarily.
670cdc45
AJ
1065
1066Regular programs that are compiled and linked against @mswindows{} DLL's
1067will import DLL functions by name. This is therefore the default
1068behaviour. Most DLL functions will be imported by name in all cases.
1069Apparently, the @WIN32{} DLL's even show some difference in the mapping
1070of functions and ordinals on @WINNT{} and @WIN95{}. For most DLL
1071functions, the ordinal number will not matter.
1072
1073There are some exceptions to that. Notable the KERNEL32 ordinals below
1074100 are (presently) unnamed and undocumented functions which can only be
1075imported by ordinal. These functions are called by some @mswindows{}
1076programs. Also the @file{shell32.dll} functions are reported to be
1077imported by ordinal in some other DLL's.
1078
1079@xref{Getting information on the API}, for sources of further information.
641ee76a
AJ
1080
1081@node Spec file header, Variable entry points, Ordinals, The spec files
1082@subsubsection The header of a @file{.spec}-file
1083
1084The @file{.spec}-file starts with two mandatory definitions. The first
1085line gives the name of the DLL which the @file{.spec}-file describes,
1086@example
1087name @var{NAME}
1088@end example
1089where @var{NAME} is the name of the DLL. The next line defines the type
1090of the DLL,
1091@example
1092type @var{TYPE}
1093@end example
1094with @var{TYPE} being either @samp{win16} or @samp{win32}.
1095
1096An optional statement of the form
1097@example
1098base @var{ORDINAL}
1099@end example
1100can be used to define the offset of the first ordinal. @var{ORDINAL}
1101must be an integer number. If no base is specified, the offset is zero.
1102@* FIXME: is this the offset of the first or an offset that is added to all
1103ordinals?
1104what is the offset? Is it added to the ordinals, or is it an address, or
1105xxx?
1106
1107An optional statement like
1108@example
1109heap @var{SIZE}
1110@end example
1111can be used to define the size of the module local heap. This is only
1112used for @WIN16{} DLL's. The local heap is the place where the segments
1113of 16 bit programs can locally allocate memory, without interfering with
1114one another. The default size of the local heap, if not specified, is 0.
1115
1116@* FIXME: to my impression, a local heap in DLL's would only be required
1117if DLL functions used it. As all DLL functions in Wine are truly 32 bit
1118functions that are mapped from 16 bit on being called and back to 16 bit
1119on returning, a local heap should never be necessary.
1120If I receive a confirmation of that here, I will state so. Otherwise I
1121am missing some information on local heaps.
1122But why is a heap defined in user.spec and gdi.spec?
1123
1124@node Variable entry points, Function entry points, Spec file header, The spec files
1125@subsubsection Variable entry points of @file{.spec}-files
1126
1127You can declare an ordinal that holds data. Data items may be of 8, 16,
1128or 32 bit in size.
1129
1130@example
1131@var{ORDINAL} @var{VARTYPE} @var{EXPORTNAME} (@var{DATA} @var{[DATA @dots{}]})
1132@end example
1133
1134@var{ORDINAL} is the ordinal number corresponding to the
1135variable. @var{VARTYPE} must be @samp{byte}, @samp{word}, or
1136@samp{long}, for 8, 16, or 32 bits respectively. @var{EXPORTNAME} will
1137be the name available for dynamic linking. @var{DATA} can be a decimal
1138number or a hex number preceded by @samp{0x}. Each @var{DATA} item defines
1139a unit of storage.
1140
1141The following example defines the variable @samp{VariableA} at ordinal
11422, containing 4 bytes:
1143@example
11442 byte VariableA(-1 0xff 0 0)
1145@end example
1146
1147
1148@node Function entry points, Special entries, Variable entry points, The spec files
1149@subsubsection Function entry points of @file{.spec}-files
1150
1151@example
1152@var{ORDINAL} @var{FUNCTYPE} @var{EXPORTNAME} (@var{[ARGTYPE} @dots{} @var{]}) @var{HANDLERNAME}
1153@end example
1154
1155@var{ORDINAL} is the ordinal number corresponding to the
1156function. @var{FUNCTYPE} must be chosen from this table:
1157@table @samp
1158@item pascal16
1159A @WIN16{} function that returns a 16 bit value.
1160@item pascal
1161A @WIN16{} function that returns a 32 bit value.
1162@item register
1163A function using CPU registers to pass arguments.
1164@item stdcall
670cdc45
AJ
1165A normal @WIN32{} function. @xref{Investigating the undocumented API},
1166for an explanation of the stdcall calling convention.
641ee76a
AJ
1167@item cdecl
1168A @WIN32{} function using the C calling conventions. (This is presently
1169only used for the built-in functions of the C runtime system).
1170@end table
1171
1172@var{EXPORTNAME} specifies the name (prototype) available for dynamic
1173linking.
1174
1175@var{ARGTYPE} must be chosen from this table:
1176@table @samp
1177@item byte
1178 An 8 bit argument. Can be used in @WIN16{} functions only.
1179@item word
1180 A 16 bit argument. Can be used in @WIN16{} functions only.
1181@item long
1182 A 32 bit argument. Can be used in @WIN16{} or @WIN32{} functions.
1183@item ptr
1184 A linear pointer, unsegmented. Can be used in @WIN16{} or @WIN32{}
1185 functions.
1186@item str
1187 A linear pointer, unsegmented, pointing to a null-terminated string.
1188 Can be used in @WIN16{} or @WIN32{} functions.
1189@item s_byte
1190 A signed 8 bit argument. Can be used in @WIN16{} functions only.
1191@item s_word
1192 A signed 16 bit argument. Can be used in @WIN16{} functions only.
1193@item s_long
1194 A signed 32 bit argument. Can be used in @WIN16{} or @WIN32{}
1195 functions.
1196@item segptr
1197 A segmented pointer. Can be used in @WIN16{} functions only.
1198@item segstr
1199 A segmented pointer to a null-terminated string. Can be used in
1200 @WIN16{} functions only.
1201@end table
1202
1203@var{HANDLERNAME} is the name of the actual Wine function that will
1204process the request in 32-bit mode.
1205
1206
1207@sp 2
1208Here are some examples. The first example defines an entry point for the
1209@code{CreateWindow()} call (the ordinal 100 is just an example):
1210@example
1211100 pascal CreateWindow(ptr ptr long s_word s_word s_word s_word
1212 word word word ptr) WIN_CreateWindow
1213@end example
1214
1215The second example defines an entry point for the @code{GetFocus()} call
1216(again, the ordinal 100 is an example):
1217@example
1218100 pascal GetFocus() WIN_GetFocus()
1219@end example
1220
1221To declare a function that uses a variable number of arguments, specify
1222the function as taking no arguments. In this special case, in @WIN32{}
1223the called function will be passed a pointer to the first arg; in
1224@WIN16{}, the args are available as @code{CURRENT_STACK16->args}.
1225@* FIXME: create a reference here
1226See the @code{wsprintf}* functions in @file{user.spec} and
1227@file{user32.spec} for an example.
1228
670cdc45
AJ
1229Sometimes it is not known how many arguments an undocumented DLL
1230function takes. @xref{Getting information on the API}, for some hints on
1231how to proceed in such a case.
641ee76a
AJ
1232
1233@node Special entries, , Function entry points, The spec files
1234@subsubsection Special entries of @file{.spec}-files
1235
1236The @file{.spec}-files offer the possibility to use some special
1237entries. These entries are used for stubs (which allow linking for
1238non-existing functions), dummy functions that do not perform any
1239operations, Wine symbols that must be referenced directly, and constant
1240values.
1241
1242
1243@strong{Stub ordinals}
1244
1245This pseudo function type defines a stub function. It makes the name and
1246ordinal available for dynamic linking, but will terminate execution with
1247an error message if the function is ever called.
1248
1249@example
1250@var{ORDINAL} stub @var{EXPORTNAME}
1251@end example
1252
1253@var{ORDINAL} is the ordinal number corresponding to the
1254function. @var{EXPORTNAME} specifies the name (prototype) available for dynamic
1255linking.
1256
1257@strong{Return ordinals}
1258
1259This pseudo function type defines a function entry point whose handler
1260should do nothing but return a value.
1261@example
1262@var{ORDINAL} return @var{EXPORTNAME} @var{ARGLENGTH} @var{RETVALUE}
1263@end example
1264
1265@var{ORDINAL} is replaced by the ordinal number corresponding to the
1266function. @var{ARGLENGTH} is the number of bytes that need to be removed
670cdc45
AJ
1267from the stack before returning to the caller. @xref{Investigating the
1268undocumented API}, for an explanation of the stdcall calling convention.
1269@var{RETVALUE} is the return value which will be passed back to the
1270caller.
641ee76a
AJ
1271
1272@strong{Extern ordinals}
1273
1274@example
1275@var{ORDINAL} extern @var{EXPORTNAME} @var{SYMBOLNAME}
1276@end example
1277This type defines an entry that simply maps to a Wine symbol
1278(variable or function); @var{EXPORTNAME} will point to the symbol
1279@var{SYMBOLNAME} that must be defined in C code. This type only works with
1280@WIN32{}.
1281
1282
1283@strong{Equate ordinals}
1284
1285@example
1286@var{ORDINAL} equate @var{EXPORTNAME} @var{DATA}
1287@end example
1288
1289This type defines an ordinal as an absolute value.
1290@var{ORDINAL} is replaced by the ordinal number corresponding to the
1291entry. @var{EXPORTNAME} will be the name available for dynamic linking.
1292@var{DATA} can be a decimal number or a hex number preceeded by @samp{0x}.
1293
1294
d37eb365 1295@node Installation, The Wine Project, Reference Manual, Top
641ee76a 1296@chapter Wine installation and configuration
d37eb365
AJ
1297FIXME: write installation guide
1298
1299@menu
1300* Applying patches:: How to update Wine to a newer version.
1301@end menu
1302
1303@node Applying patches, , , Installation
1304@section Applying patches
1305@xref{Creating patches}, for instructions on creating patches.
1306
a11d7b1a
AJ
1307@kbd{cd} to the top source directory for Wine, and run
1308@code{patch -p1 < @var{patchfile}}.
1309What needs to be done next depends to some extent on what the
1310patch touches. For small patches which only alter C source, it can be
1311enough to rerun @code{make}. In general, the sequence @code{configure},
1312@code{make depend}, @code{make} is sufficient, unless the patch alters
1313@code{[config.in]}, in which case you must regenerate @code{configure}
1314via @code{make configure} (which just runs @code{autoconf}).
d37eb365
AJ
1315
1316
1317@node The Wine Project, , Installation, Top
1318@chapter The Wine project
1319@cindex Wine project contributions
1320@cindex project contributions to Wine
1321
1322If you are new to Wine and want to support this project, here are
1323some suggestions.
1324
1325@menu
670cdc45
AJ
1326* Getting information on the API:: Official and unofficial sources
1327 of information on the @WIN32{} API.
1328* Investigating the undocumented API:: You can find out some API
1329 information on your own.
641ee76a
AJ
1330* Implementing an API type:: How to implement a data type
1331 of the API (a checklist).
1332* Implementing an API function:: How to implement one function
1333 of the API (a checklist).
1334* API function and type naming:: How to name API functions in Wine.
1335* Creating patches:: How to create patches for Wine.
1336* Adding Documentation:: Templates for the documentation.
1337* File names:: How Wine treats @mswindows{} and
1338 @unix{} file names.
1339* Wide character strings:: How Wine treats wide character
1340 strings.
d37eb365
AJ
1341@end menu
1342
1343@xref{Debugging}, for advice on how to debug Wine.
1344@xref{Applying patches}, for instructions on applying patches.
1345
d37eb365 1346
670cdc45
AJ
1347@node Getting information on the API, Investigating the undocumented API, , The Wine Project
1348@section Official and unofficial documentation on the @mswindows{} API
1349@cindex documentation of API functions
1350@cindex undocumented API functions
1351
1352
1353@strong{Official documentation}
1354
1355For documentation on @WIN32{} API functions, you might try one of these
1356sources:
1357
1358@itemize @bullet
1359
1360@item
1361There is a free online version of the MSDN library (including
1362documentation for the @WIN32{} API) on
1363@url{http://www.microsoft.com/msdn/}.
1364
1365@item
1366The @WINNT{} DDK gives information about some kernel (``executive'')
1367routines. Some of the function documentation might also apply to user
1368accessible DLL's.
1369@end itemize
1370
1371@strong{Unofficial documentation}
1372
1373Not all of the @WIN32{} API is well documented. Some functions are
1374obscured, and undocumented. @xref{Ordinals}, for information about
1375undocumented functions imported by ordinal. Getting to know what these
1376functions do can be tiresome and tedious. Here is a quote from a
1377news posting concerning two books that might help:
1378@c From: vischne@ibm.net-nospam (root)
1379@c Subject: Re: Functions
1380@c Newsgroups: comp.emulators.ms-windows.wine
1381@c Date: 24 Jul 97 16:45:11 GMT
1382@c Organization: The Light
1383@c NNTP-Posting-Host: 129.37.246.203
1384@c Message-ID: <33d78697.0@news3.ibm.net>
1385
1386@quotation
1387Well actually, there are at least _two_ books that address these problems.
1388One is by Matt Pietrek, ``Windows 95 System Programming Secrets'', which
1389gives some auxiliary programs for helping ferret out the information, and
1390the other is by Shulman, ``Undocumented Windows 95''.
1391@end quotation
1392
1393@xref{Ordinals}, for some notes on undocumented kernel functions.
1394
1395@itemize @bullet
1396
1397@item
1398@cindex book on undocumented API features by Pietrik
1399``Windows 95 System Programming Secrets'' @*
1400by Matt Pietrek @*
1401Book & Disk Edition @*
1402Paperback, 778 pages @*
1403Published by IDG Books Worldwide @*
1404Publication date: November 1, 1995 @*
1405Dimensions (in inches): 9.25 x 7.42 x 2.06 @*
1406ISBN: 1568843186 @*
1407
1408@item
1409@cindex book on undocumented API features by Schulman
1410``Undocumented Windows; A Programmers Guide
1411to Reserved Microsoft Windows API Functions'' @*
1412by Andrew Schulman @*
1413Paperback, 715 pages @*
1414Published by Addison-Wesley Pub Co @*
1415Publication date: February 1, 1994 @*
1416Dimensions (in inches): 9.11 x 7.37 x 1.53 @*
1417ISBN: 0201608340 @*
1418
1419@item
1420More books on these topics (including Schulman and Pietrik): @*
1421@url{http://www.sonic.net/~undoc/bookstore.html}
1422
1423@item
1424More details about calling undocumented functions can be found at
1425@url{http://ftp.uni-mannheim.de/info/OReilly/windows/win95.update/dirty.html}.
1426
1427@item
1428In 1993 Dr. Dobbs Journal published a column called ``Undocumented
1429Corner''.
1430@item
1431You might want to check out BYTE from December 1983 as well.
1432@* FIXME: is that to be taken seriously?
1433@item
1434And you might try to find out something on your own. @xref{Investigating
1435the undocumented API}, for details.
1436@end itemize
1437
1438But, all in all, @url{news:comp.emulators.ms-windows.wine} says
1439@c From: dacut@henry.ece.cmu.edu (David A. Cuthbert)
1440@c Subject: Re: Getting Internet Explorer to work
1441@c Newsgroups: comp.emulators.ms-windows.wine
1442@c Date: 24 Jul 1997 03:10:30 GMT
1443@c Organization: Electrical & Computer Engineering, Carnegie Mellon University
1444@c Reply-To: henry.ece.cmu.edu!dacut
1445@c Message-ID: <5r6h36$86c@fs7.ece.cmu.edu>
1446@c NNTP-Posting-Host: henry.ece.cmu.edu
1447
1448@quotation
1449Unfortunately, short of getting something like NuMega's SoftIce, I
1450don't think there's a ``good'' reference on the mystery <100 ordinals in
1451KERNEL32.DLL.
1452@end quotation
1453
1454
1455@node Investigating the undocumented API, Implementing an API type, Getting information on the API, The Wine Project
1456@section Investigating the undocumented API
1457@cindex undocumented API investigation
1458@cindex parameters of undocumented API functions
1459@cindex stdcall calling convention
1460@cindex C calling convention
1461@cindex API function parameters investigation
1462@cindex stack handling under stdcall calling
1463
1464Besides reading the documentation in @ref{Getting information on the API},
1465you can find out some properties of API functions on your own.
1466
1467Sometimes it is not known how many arguments an undocumented DLL
1468function takes. Here is a text from a news posting that gives some
1469hints on how you might proceed in this case.
1470
1471@c The following text is closely quoted from:
1472@c From: dacut@henry.ece.cmu.edu (David A. Cuthbert)
1473@c Subject: Win32 stub functions (Claus Fischer, please read)
1474@c Newsgroups: comp.emulators.ms-windows.wine
1475@c Date: 7 Aug 1997 22:33:09 GMT
1476@c Organization: Electrical & Computer Engineering, Carnegie Mellon University
1477@c Reply-To: henry.ece.cmu.edu!dacut
1478@c Message-ID: <5sdif5$qt3@fs7.ece.cmu.edu>
1479
1480The problem with implementing stubs for @WIN32{} functions is that it is
1481not sufficient to return a default value (usually 0) and leave the
1482stack the way we found it. For most @WIN32{} functions -- those that use
1483the @dfn{stdcall} calling convention -- the arguments sent to the function
1484are removed from the stack.
1485
1486Some background: On the i386 class of machines, stack entries are
1487usually dword (4 bytes) in size, little-endian. The stack grows
1488downward in memory. The stack pointer, maintained in the @samp{esp}
1489register, points to the last valid entry; thus, the operation of
1490pushing a value onto the stack involves decrementing @samp{esp} and then
1491moving the value into the memory pointed to by esp (i.e., @code{push p}
1492in assembly resembles @code{*(--esp) = p;} in C). Removing (popping)
1493values off the stack is the reverse (i.e., @code{pop p} corresponds to
1494@code{p = *(esp++);}).
1495
1496In the @dfn{stdcall} calling convention, arguments are pushed onto the
1497stack right-to-left. For example, the C call
1498
1499@example
1500 myfunction(40, 20, 70, 30);
1501@end example
1502
1503is expressed in Intel assembly as:
1504
1505@example
1506 push 30
1507 push 70
1508 push 20
1509 push 40
1510 call myfunction
1511@end example
1512
1513In addition, the called function is responsible for removing the
1514arguments off the stack. Thus, before the call to myfunction, the
1515stack would look like:
1516
1517@example
1518 [local variable or temporary]
1519 [local variable or temporary]
1520 30
1521 70
1522 20
1523 esp -> 40
1524@end example
1525
1526After the call returns, it should look like:
1527
1528@example
1529 [local variable or temporary]
1530 esp -> [local variable or temporary]
1531@end example
1532
1533To restore the stack to this state, the called function must know how
1534many arguments to remove (which is the number of arguments it takes).
1535This is a problem if the function is undocumented.
1536
1537One way to attempt to document the number of arguments each function
1538takes is to create a wrapper around that function that detects the
1539stack offset. @file{WinRelay} (see below) was written to create such
1540wrappers. Essentially, each wrapper assumes that the function will take
1541a large number of arguments (by default, 64 in @file{WinRelay}). The
1542wrapper copies each of these arguments into its stack, calls the actual
1543function, and then calculates the number of arguments by checking esp
1544before and after the call.
1545
1546@cindex bsod (blue screen of death)
1547@cindex blue screen of death
1548The main problem with this scheme is that the function must actually
1549be called from another program. Many of these functions are seldom
1550used. An attempt was made to aggressively query each function in a
1551given library (@file{ntdll.dll}) by passing 64 arguments, all 0, to each
1552function. Unfortunately, @WINNT40{} quickly goes to a blue screen
1553of death (@dfn{bsod}), even if the program is run from a
1554non-administrator account.
1555
1556Another method that has been much more successful is to attempt to
1557figure out how many arguments each function is removing from the
1558stack. This instruction, @code{ret hhll} (where @samp{hhll} is the
1559number of bytes to remove, i.e. the number of arguments times 4), contains
1560the bytes @samp{0xc2 ll hh} in memory. It is a reasonable assumption
1561that few, if any, functions take more than 16 arguments; therefore,
1562@samp{hh} is 0x0 and @samp{ll} is less than 0x40. This utility,
1563@file{MakeSpec} (see below), simply queries the address of a function
1564and looks for the first occurrence of the bytes @samp{0xc2 ll 0x0},
1565where @math{@samp{ll} <= 0x40}.
1566
1567Of course, this is not without errors. @code{ret 00ll} is not the only
1568instruction that can have the byte sequence @samp{0xc2 ll 0x0}; for
1569example, @code{push 0x000040c2} has the byte sequence
1570@samp{0x68 0xc2 0x40 0x0 0x0}, which matches the above. Properly, the
1571utility should look for this sequence only on an instruction boundary;
1572unfortunately, finding instruction boundaries on an i386 requires
1573implementing a full disassemble -- quite a daunting task. Besides,
1574the probability of having such a byte sequence that is not the actual
1575return instruction is fairly low.
1576
1577Much more troublesome is the non-linear flow of a function. For
1578example, consider the following two functions:
1579
1580@example
1581 somefunction1:
1582 jmp somefunction1_impl
1583
1584 somefunction2:
1585 ret 0004
1586
1587 somefunction1_impl:
1588 ret 0008
1589@end example
1590
1591@file{MakeSpec} would incorrectly list both @code{somefunction1} and
1592@code{somefunction2} as taking only a single argument, whereas
1593@code{somefunction1} really takes two arguments.
1594
1595With these limitations in mind, it is possible to implement more stubs
1596in Wine and, eventually, the functions themselves.
1597
1598@c end of quote
1599
1600The program @file{WinRelay} can be downloaded from
1601@url{http://www.ece.cmu.edu/afs/ece/usr/dacut/www/src},
1602and @file{MakeSpec} will be available from the same location. You can
1603compile them with Borland's C++Builder; you should not optimize when
1604compiling (@file{WinRelay} needs the stack frames).
1605
1606
1607@node Implementing an API type, Implementing an API function, Investigating the undocumented API, The Wine Project
641ee76a
AJ
1608@section Implementing an API type
1609
1610Here is a checklist that should help you writing your first API type. It
1611will of course not tell you which elements to put into the type
1612(assuming it is a structure), but it should help you along the way of
1613integrating this type into Wine.
1614@xref{Implementing an API function}, for comparison.
1615
1616@enumerate
1617@item
1618Find out how the type should be named in Wine and in the DLL's.
1619@xref{API function and type naming}, for details.
1620
1621@item
1622Find out where the type should go. Please try to keep the header files
1623structure as similar to @mswindows{} as possible.
1624
1625@item
1626Prepare for the later patch (by saving the original files before you
1627work on them). @xref{Creating patches}, for details.
1628
1629@item
1630Put the type declaration into the header file.
1631
1632@item
1633Make sure the declaration is syntactically correct, i.e. it does not
1634keep Wine from compiling.
1635
1636@item
1637Make sure the declared type is layout-compatible with
1638@mswindows{}-compiled types. Especially keep an eye on the packing of
1639the structure.
1640@* FIXME: a reference to packed structures here.
1641
1642@item
1643Build Wine and test the type, if possible. If you cannot test the
1644type by implementing a proper API function, write a small test program
1645to test it on its own. Or rather stop here.
1646
1647@item
1648Write the documentation of the type in the @file{wine.texinfo}
1649file. @xref{Adding Documentation}, for details.
1650With types, be especially careful and document all the details. Also
1651document all constants or flags that are used in the type.
1652
1653@item
1654Create an entry in the @file{ChangeLog} file.
1655
1656@item
1657Collect some of these changes, and create a patch. @xref{Creating
1658patches}, for details.
1659
1660@item
1661Mail the patch to Alexandre Julliard, @email{julliard@@lrc.epfl.ch}.
1662
1663@item
1664Wait for the patch to appear in the official distribution.
1665@end enumerate
1666
1667
1668@node Implementing an API function, API function and type naming, Implementing an API type, The Wine Project
1669@section Implementing an API function
1670
1671Here is a checklist that should help you writing your first API
1672function. It will of course not tell you what to do in the function,
1673but it should help you along the way of integrating this function into
1674Wine.
1675
1676@enumerate
1677@item
1678Make sure all data types that appear in function arguments are properly
1679declared in Wine. Otherwise, start with the data types.
1680
1681@item
1682Find out how the function should be named in Wine and in the DLL's.
1683@xref{API function and type naming}, for details.
1684
670cdc45
AJ
1685@item
1686Find out what the function should do. This may be tricky for
1687undocumented functions. @xref{Getting information on the API}, for some
1688hints.
1689
641ee76a
AJ
1690@item
1691Find out where the function should go:
1692@enumerate
1693@item
1694Which header file for the prototype.
1695@item
1696Which C source file.
1697@item
1698Which DLL(s), and which ordinal the function will take there. Perhaps
1699the function name is already present in one of the @file{.spec}-files in
1700the @file{if1632} directory.
1701@end enumerate
1702
1703@item
1704Prepare for the later patch (by saving the original files before you
1705work on them). @xref{Creating patches}, for details.
1706
1707@item
1708Put the prototype into the header file, and the code into the C file.
1709
1710@item
1711Make sure the code compiles.
1712
1713@item
1714Create or change the information for the DLL entry points in the
1715@file{.spec}-file in the @file{if1632} directory.
1716@xref{The build program}, for details of the DLL spec files.
1717
1718@item
1719Build Wine and test the function, if possible. If you cannot test the
1720function in Wine, write a small test program to test it on its own.
1721
1722@item
1723Write the documentation of the function in the @file{wine.texinfo}
1724file. @xref{Adding Documentation}, for details.
1725
1726@item
1727Create an entry in the @file{ChangeLog} file.
1728
1729@item
1730Collect some of these changes, and create a patch. @xref{Creating
1731patches}, for details.
1732
1733@item
1734Mail the patch to Alexandre Julliard, @email{julliard@@lrc.epfl.ch}.
1735
1736@item
1737Wait for the patch to appear in the official distribution.
1738@end enumerate
1739
1740
1741@node API function and type naming, Creating patches, Implementing an API function, The Wine Project
1742@section API function and data type naming conventions
1743@cindex API function names
1744@cindex API type names
1745@cindex names of API functions and types
1746@cindex naming scheme for API functions and types
1747@cindex suffixes for API functions and types
1748@cindex endings of API function and type names
1749
1750This section describes Wine's naming scheme for API functions and data
1751types.
1752
1753The purpose of these naming conventions is to ensure that
1754@itemize @bullet
1755@item
1756both the @WIN16{} and @WIN32{} API are supported within the same source
1757code,
1758@item
1759both wide character functions (with @unicode{} strings) and 8 bit
1760character functions (with @ascii{} or extended @ascii{} encoding) are
1761supported, and
1762@item
1763the source code can be shared between the emulator and the library
1764version of Wine.
1765@end itemize
1766
1767A function or data type whose name in the @mswindows{} API is @var{xxx}
1768will in the Wine code have the following name(s):
1769@table @code
1770@item @var{xxx}16
1771This is the version for the 16 bit API. You might call it the ``16 bit
1772version'' except that the function itself of course runs in true 32 bit
1773mode (being part of Wine). So, the correct meaning of the suffix is that
1774this function is part of the 16 bit API.
1775@item @var{xxx}32
1776This is the version for the 32 bit API. Use this suffix only if the
1777function does not use character strings in its parameters or return
1778values. Otherwise use the next two.
1779@item @var{xxx}32A
1780This is the version for the 32 bit API which uses @ascii{} strings (or
1781rather, strings with 8 bit character encodings, i.e. the standard C
1782@code{char} type). This version always goes together with another
1783version, using the next suffix.
1784@item @var{xxx}32W
1785This is the version for the 32 bit API which uses @unicode{} strings,
1786i.e. strings with wide characters. It goes together with the @ascii{}
1787version.
1788@end table
1789
1790So, where the @mswindows{} API offers one name, Wine actually has two or
1791three different functions implemented (which will hopefully share a
1792large part of the code).
1793
1794Wine allows to use its API functions in two ways. The emulator part of
1795Wine provides DLL's for the @mswindows{} programs it can run. The
1796library part of Wine provides a @unix{} programmer with the facility to
1797use the Wine API's in a standard @unix{} program.
1798
1799@menu
1800* Access from the emulator:: How to access API functions and types
1801 from applications that are run in the
1802 Wine emulator.
1803* Access in the library:: How to access API functions and types
1804 from applications that are linked with
1805 the Wine library.
1806* Access from inside Wine:: How to access API functions and types
1807 from inside the Wine code.
1808@end menu
1809
1810@node Access from the emulator, Access in the library, , API function and type naming
1811@subsection Accessing API functions and types from the emulator
1812@cindex access to DLL API functions and types
1813@cindex Wine emulator access to API functions and types
1814@cindex emulator access to Wine API functions and types
1815
1816The emulator part of Wine provides the hooks for dynamically linking the
1817API functions to the @mswindows{} executables (@file{.EXE}-files). The
1818Wine emulator contains all versions (16 or 32 bit, @ascii{} or
1819@unicode{}) of the API functions in one executable. The emulator
1820performs a mapping from the @mswindows{} name of the function,
1821by which the executable calls it, to one of the Wine internal names that
1822have been used in coding it.
1823
1824This mapping is done by the built-in DLL handling code of Wine. A
1825programmer of Wine has to declare the function in one of the virtual
1826DLL's that are provided by Wine. The declarations are done in the
1827@file{.spec}-files in the @file{if1632/} directory. @xref{The build
1828program}, for details.
1829
1830The @mswindows{} application simply calls the API function by its
1831standard @mswindows{} name. Wine will apply the correct mapping
1832according to Wine's selected appearance (as a 16 bit or 32 bit emulator,
1833which is a parameter on invocation of Wine).
1834
1835
1836@node Access in the library, Access from inside Wine, Access from the emulator, API function and type naming
1837@subsection Accessing API functions and types in the library
1838@cindex Wine library API function and type access
1839@cindex access to Wine library API functions and types
1840
1841If Wine is built as a library, and linked to a user-level main program,
1842the user will also use the standard @mswindows{} names for the API
1843functions.
1844
1845Some macros are defined in @file{include/wintypes.h} which perform the
1846necessary name mappings.
1847
1848These macros are (see the examples below):
1849@deffn_winemacro WINELIB_NAME (@var{xxx})
1850This macro replaces @var{xxx} by one of @var{xxx}16 or
1851@var{xxx}32, depending on the definition of the symbols
1852@code{WINELIB16} and @code{WINELIB32}. @var{xxx} should
1853be the name of an API function that uses no string arguments.
1854Use this macro with a @code{#define} to establish the API name @var{xxx}.
1855@end deffn
1856@deffn_winemacro WINELIB_NAME_AW (@var{xxx})
1857This macro replaces @var{xxx} by one of @var{xxx}16, @var{xxx}32A, or
1858@var{xxx}32W, depending on the definition of the symbols
1859@code{WINELIB16}, @code{WINELIB32}, and @code{UNICODE}. @var{xxx} should
1860be the name of an API function that uses string arguments.
1861Use this macro with a @code{#define} to establish the API name @var{xxx}.
1862@end deffn
1863@deffn_winemacro DECL_WINELIB_TYPE (@var{xxx})
1864This macro declares @var{xxx} to be an equivalent to @var{xxx}16 or
1865@var{xxx}32, depending on the definition of the symbols
1866@code{WINELIB16} and @code{WINELIB32}. @var{xxx} should
1867be the name of an API data type that contains no string arguments.
1868@end deffn
1869@deffn_winemacro DECL_WINELIB_TYPE_AW (@var{xxx})
1870This macro declares the type @var{xxx} to be an equivalent to
1871@var{xxx}16, @var{xxx}32A, or @var{xxx}32W, depending on the definition
1872of the symbols @code{WINELIB16}, @code{WINELIB32}, and
1873@code{UNICODE}. @var{xxx} should be the name of an API data type that
1874contains string arguments.
1875@end deffn
1876
1877If Wine is compiled as an emulator, these macros have no effect, for the
1878mapping is then done by the DLL code. This means that within Wine the
1879name @var{xxx} itself will not be defined.
1880
1881Note: If the definition of @var{xxx} is exactly the same in @WIN16{} and
1882@WIN32{}, you can simply use the same name as @mswindows{}.
1883
1884Here are some examples:
1885@example
1886/* A simple type without strings */
1887typedef short INT16;
1888typedef int INT32;
1889DECL_WINELIB_TYPE(INT);
1890
1891/* A type with strings */
1892typedef struct @{ /* Win32 ASCII data structure */ @} WNDCLASS32A;
1893typedef struct @{ /* Win32 Unicode data structure */ @} WNDCLASS32W;
1894typedef struct @{ /* Win16 data structure */ @} WNDCLASS16;
1895DECL_WINELIB_TYPE_AW(WNDCLASS);
1896
1897/* A function with strings */
1898ATOM RegisterClass16( WNDCLASS16 * );
1899ATOM RegisterClass32A( WNDCLASS32A * );
1900ATOM RegisterClass32W( WNDCLASS32W * );
1901#define RegisterClass WINELIB_NAME_AW(RegisterClass)
1902@end example
1903
1904The Winelib user can then say (in the application program):
1905@example
1906 INT i;
1907 WNDCLASS wc = @{ @dots{} @};
1908 RegisterClass( &wc );
1909@end example
1910and this will use the correct declaration depending on the definitions
1911@code{WINELIB16}, @code{WINELIB32}, and @code{UNICODE}.
1912
1913Here are the primary defines that are used when Wine is compiled as a
1914library:
1915@defvr_cwine WINELIB16
1916If this @code{#define} is set, the Wine library is to be compiled in its
191716 bit form. That means, the 16 bit variants of all functions will be
1918used and the appearance of the application linked with the Wine library
1919will be that of a 16 bit application. Of course, both the application
1920and the Wine library function really run in 32 bit mode. The switch only
1921selects the function with the name ending in @code{@dots{}16}, which
1922will perhaps have a behaviour different from its 32 bit counterpart.
1923@end defvr
1924@defvr_cwine WINELIB32
1925If this @code{#define} is set, the Wine library is to be compiled in its
192632 bit form. That means, the 32 bit variants of all functions will be
1927used and the appearance of the application linked with the Wine library
1928will be that of a 32 bit application.
1929@end defvr
1930@defvr_cwine UNICODE
1931This @code{define} is used to select one of two possible 32 bit
1932variants. Functions and data types of the 32 bit API come in two
1933flavours: one handling @ascii{} strings (or rather strings with
1934characters encoded in 8 bit), the other @unicode{} strings. This define
1935selects the correct variant. As a user of the Wine library, you are
1936responsible to use the correct character type in your part of the
1937application which accesses the Wine API functions and data types.
1938@end defvr
1939
1940These switches are automatically set when Wine is compiled as a library.
1941
1942
1943@node Access from inside Wine, , Access in the library, API function and type naming
1944@subsection Accessing API functions from within Wine
1945@cindex explicit names of API functions and types
1946
1947Within Wine and during the compilation of Wine, you cannot rely on the
1948@mswindows{} names of the API functions and data types. If Wine is
1949compiled as a library, they will be defined; if Wine is compiled as an
1950emulator, they won't.
1951
1952You therefore have to access all functions and data types by their full
a11d7b1a 1953names, with the proper suffix explicitly appended. In Wine, the 16 bit
641ee76a
AJ
1954and 32 bit versions of the functions are distinct entities, which might
1955(theoretically) show a completely different behaviour. They may even
1956call each other (and they will quite frequently).
1957
1958Therefore Wine is a conglomerate that contains all two or
1959three flavours of each function at once, and exports to the
1960application whichever of these is appropriate. Remember that inside
1961Wine, there is no memory segmentation, so all functions are 32 bit.
1962The 16-to-32 bit mapping is done on exporting the DLL functions.
1963
1964
1965@node Creating patches, Adding Documentation, API function and type naming, The Wine Project
d37eb365
AJ
1966@section Creating patches
1967@xref{Applying patches}, for instructions on applying patches.
1968
a11d7b1a
AJ
1969Patches are created with the program @code{diff}. You need a copy
1970of clean source tree to diff against. The @samp{-u} option, to create
1971unified diffs, is popular but not obligatory.
1972For changes to a single file,
1973@code{diff -u wine990101/windows/win.c mywine/windows/win.c > win_patch}
1974is sufficient.
1975To generate a complete diff between your tree and the distribution,
1976use @code{diff -uR wine990101 mywine}.
1977
1978This assumes that the original distribution and your personal tree
1979have the same parent directory, from which you make the diff.
1980This ensures a consistent format for the diffs, which in turn
1981is necessary so that they can be applied consistently as described in
1982@xref{Applying patches}.
d37eb365 1983
641ee76a 1984@node Adding Documentation, File names, Creating patches, The Wine Project
d37eb365
AJ
1985@section Adding Documentation
1986
1987@ifinfo
1988Here are some templates which should help you collaborate on this
1989documentation. Read the text below before examining them.
1990@end ifinfo
1991
d37eb365
AJ
1992@menu
1993* Type Template:: How to document data types in Wine's
1994 include files.
1995* Function Template:: How to document an (API) function of
1996 Wine.
1997@end menu
1998
1999
2000These are my tips for adding documentation.
2001
2002Do not simply copy documentation from @mswindows{} related
2003material. Except from risking copyright violations, which you would not
2004want to do, there is another aspect to that:
2005As Wine is a product to run on @unix{} and @unix{}-like workstations,
2006it seems a good idea to me to organize this documentation primarily for
2007the well-trained @unix{} reader. Please keep that in mind when you add
2008some documentation.
2009
2010Finally, read the info pages for @code{texinfo}.
2011
641ee76a
AJ
2012The rest of this section provides some templates which can serve as a
2013start in writing documentation.
2014
d37eb365
AJ
2015@subsection Template introduction
2016@iftex
2017On the following pages you will find some @code{texinfo} templates, which
2018should help you collaborate on this documentation.
2019@end iftex
2020
2021These templates give hints on how to document data types, functions,
2022variables, constants etc. in Wine.
2023As documentation evolves, you will find common features of data types
2024that should be described in a unified fashion. In such a case, please
2025add a corresponding style guide-line here, in this very place, to help
2026keeping documentation of data types unified.
2027
2028
2029Start out the type or function with a new node. Write a comment before
2030the node, listing all data types (and functions) described in the node,
2031like this:
2032@example
2033@@c
2034@@c *** struct FILETIME ***
2035@@c
2036@@node Type FILETIME, NextNodeName, PreviousNodeName, ParentNodeName
2037@end example
2038
2039The node command describes the node name and the names of the next node,
2040the previous node, and the parent node. The parent node should contain
2041a menu entry for this node. The previous node is the node that appears
2042before this node in the parent node menu. The next node is the node
2043succeeding this one in the parent node menu. If there is no previous or
2044next node, omit the name (putting just a single space between the two
2045commata).
2046
2047The node name must be a unique sequence of words. Case is important, so
2048@emph{Type} and @emph{type} are distinct. The node name must not contain
2049special characters like @samp{@@, @{, @}} or the comma. If you need to
2050give a node the same name as a function, data type, etc., use the words
2051@samp{Type}, @samp{Function}, etc. before the identifier.
2052
2053Always put the names of the node and its links on the same line, even if
2054it gets rather long.
2055
2056If there are two or more data types or functions described in the node,
2057adapt the comment like this:
2058@example
2059@@c
2060@@c *** int X ***
2061@@c *** long Y() ***
2062@@c
2063@@node Ints and Longs, NextNodeName, PreviousNodeName, ParentNodeName
2064@end example
2065
641ee76a
AJ
2066After the node name, put a sectioning command, such as @samp{@@chapter},
2067@samp{@@section}, @samp{@@subsection}, or @samp{@@subsubsection}.
2068Without that command, cross references to the node will fail.
2069@example
2070@@subsubsection Type FILETIME
2071@end example
2072
d37eb365
AJ
2073Start the description of the type(s) or function(s) with a single
2074non-indented paragraph that gives a one-line description of the type(s)
2075or function(s) and states the include files that are required.
2076@example
2077@@noindent
2078File times in Wine are specified by the data type @@code@{FILETIME@},
2079defined in @@file@{windows.h@}.
2080@end example
2081If several types or functions are closely connected, use one paragraph
2082as a common description. If more paragraphs are required for a proper
2083description, indent all but the first of them.
2084
2085Then start the definition of the data type or function. Use the proper
641ee76a
AJ
2086macro, which you will find defined in the beginning of the texinfo file.
2087If appropriate, add your own macros.
d37eb365 2088Again, put everything that belongs to the header into a single line.
641ee76a 2089Use continuation lines for additional headers.
d37eb365 2090@example
641ee76a
AJ
2091@@deftp_w32 FILETIME
2092@@deftpx_w32 LPFILETIME
d37eb365
AJ
2093@end example
2094
2095In the definition, give a verbal explanation of the data type or
2096function. The explanation should be rather complete, exact, and
2097comprehensible, than well-structured. This is the point where you can
2098tell everything you want. Do not be afraid of wasting space.
2099Do not describe the @mswindows{} situation but only say what Wine
2100does. That is important. (Sometimes they might even do the same.)
2101@example
2102This is the data type for specifying file times. The file times are
2103stored with 64 bit precision. The actual data type is a structure with
2104two 32 bit values which are interpreted as the low and high parts of a
210564-bit value. This value gives a time measured in a granularity of 100
2106nanoseconds, so 1.5 seconds are specified by a value of 15,000,000. In
2107Wine, this 64-bit value is signed, with the sign taken from the high
2108part. The lower part is used as unsigned.
2109@end example
2110
2111For data types, it is recommended to quote the definition from the
2112header file. For a function, you might give a short example of its
2113usage. You may also put one example in the end of a node that explains
2114several of the functions in the node. Remember that cut-and-paste from a
2115well prepared example will help the readers write their code.
2116@example
2117The definition of @@code@{FILETIME@} reads:
2118@@example
641ee76a 2119typedef struct
d37eb365
AJ
2120@@@{
2121 INT32 dwLowDateTime;
2122 INT32 dwHighDateTime;
641ee76a 2123@@@} FILETIME, *LPFILETIME;
d37eb365
AJ
2124@@end example
2125@end example
2126
2127You could also use the @code{cindex} command which creates an entry in
2128the concept index. The @code{texinfo} manual recommends to keep concept
2129entries distinct, so that a single concept index entry puts to one
2130well-defined place in the document. Use lower case letters for index
2131entries, unless they are proper names or quotes from actual code.
2132@example
2133@@cindex epoch in file time
2134The @@code@{FILETIME@} structure may be used to hold absolute or relative
2135times. Absolute times are given as the number of 100 nanoseconds
2136intervals elapsed since 1 January 1601, 00:00:00 UTC (Coordinated
2137Universal Time, which is GMT, Greenwich Mean Time). This might be
2138called the @@dfn@{epoch@} for file times. With a signed 64-bit value, this
2139representation covers absolute times of 29247 years around the epoch.
2140@end example
2141
2142After the verbal documentation, you can add some special fields
2143describing bugs, implementation dependencies etc. Two of these are
2144recommended to attach to all descriptions. One describes the
2145conformance of the data type or function to @mswindows{} products,
2146i.e. whether the item is also present in @WINNT{} and @WIN95{}. The
2147other one describes known differences of the Wine item to its
2148@mswindows{} counterpart. Both will greatly help in porting software
2149from @mswindows{} to Wine and vice versa.
2150@example
2151@@winconfall@{@}
2152
2153@@windiff@{@}
2154In @@mswindows@{@}, the elements of the structure are apparently of type
2155@@code@{DWORD@}. Whether the full 64 bit value is interpreted as signed or
2156unsigned I do not know.
2157@end example
2158
2159If you find that more of these property attributes are necessary, feel
2160free to create your own ones. But keep in mind that they should be
2161applicable more or less to all described items. Very special properties
2162will better be put into the verbal text.
2163
2164Finally end the definition of the data type or function:
2165@example
2166@@end deftp
2167@end example
2168
2169Do not forget to enter the node in the menu of its top node, and do
2170properly link the node to its successor and predecessor.
2171
2172
2173
2174
2175
2176
2177@node Type Template, Function Template, , Adding Documentation
2178@subsection Data type template
2179
2180Category: Data type
2181
2182@node Function Template, , Type Template, Adding Documentation
2183@subsection API function template
2184
2185Functions should be given category names, to indicate which API they
2186belong to. Please add items to the list of categories possible.
2187
2188Category: WIN32 function
2189
2190@example
2191@@c
2192@@c ***GetFileTime() ***
2193@@c
2194@@node Get File Times, , Compare File Times, File Times
2195@@noindent
2196The Wine function @@code@{GetFileTime@} returns the creation time and
2197the times of last the read and modification access to a file. It is
2198defined in @@file@{windows.h@}.
2199
641ee76a 2200@@deftypefn_w32 BOOL GetFileTime (@@w@{HANDLE @@var@{file@},@} @@w@{LPFILETIME @@var@{ctime@},@} @@w@{LPFILETIME @@var@{atime@},@} @@w@{LPFILETIME @@var@{mtime@})@}
d37eb365
AJ
2201This function obtains for the specified @@var@{file@} the creation time
2202@@var@{ctime@}, the time of the last access to the file @@var@{atime@}, and
2203the time of the last modification (write) to the file, @@var@{mtime@}.
2204The @@var@{file@} handle must have been obtained by opening the file with
2205@@code@{GENERIC_READ@} access. The file time arguments of this function are
2206pointers to @@code@{FILETIME@} variables, which are filled with a value that
2207indicates an absolute time in UTC. To convert these values to local
2208times, use the function @@code@{FileTimeToLocalFileTime@}. If you do not
2209need some of the times, you can pass a @@code@{NULL@} pointer.
2210The function returns @@code@{TRUE@} on success, @@code@{FALSE@} on failure.
2211
2212@@winconfall@{@}
2213
2214@@windiffnone@{@}
2215@@end deftypefn
2216@end example
2217
2218
641ee76a
AJ
2219@node File names, Wide character strings, Adding Documentation, The Wine Project
2220@section @mswindows{} and @unix{} file names in Wine
2221@cindex file names in Wine
2222@cindex Windows file names
2223@cindex DOS file names in Wine
2224@cindex UNIX file names in Wine
2225@cindex POSIX file names in Wine
2226
2227FIXME:
2228
2229@node Wide character strings, , File names, The Wine Project
2230@section Wide character strings in API functions
2231@cindex unicode strings in API functions
2232@cindex wide character strings in API functions
2233@cindex strings in API functions
2234@cindex ascii strings in API functions
2235@cindex 16 bit characters in API functions
2236@cindex wchar_t in API functions
2237
2238Presently, all wide character strings in API functions of Wine are
2239internally converted to 8 bit representation. Thus, the @WIN32{} API
2240with @unicode{} strings is not fully functional for the application
2241programmer at present.
2242
2243Even so, application programmers might consider developing their
2244applications in wide character format with Wine, as future versions
2245might bring a change. This might come when a @unix{} filesystem can
2246handle @unicode{} file names.
d37eb365 2247
641ee76a
AJ
2248Furthermore, the @unicode{} API is required to let Wine run @mswindows{}
2249applications which have been compiled for wide character strings.
d37eb365 2250
641ee76a
AJ
2251In Wine, wide characters are strictly 16 bit; the @code{wchar_t} type of
2252standard C can therefore not be used.
d37eb365
AJ
2253
2254@node Concept Index, , , Top
2255@comment node-name, next, previous, up
2256@unnumbered Concept Index
2257@printindex cp
2258
2259@node Type Index, , , Top
2260@comment node-name, next, previous, up
2261@unnumbered Type Index
2262@printindex tp
2263
2264@node Function Index, , , Top
2265@comment node-name, next, previous, up
2266@unnumbered Function Index
2267@printindex fn
2268
2269@node Variable Index, , , Top
2270@comment node-name, next, previous, up
641ee76a 2271@unnumbered Variable, Constants, and Variable-like Macros Index
d37eb365
AJ
2272@printindex vr
2273
2274@node File Index, , , Top
2275@comment node-name, next, previous, up
2276@unnumbered File and Program Index
2277@printindex pg
2278
2279
2280@contents
2281@bye