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, The Wine Authors, The Wine Authors},
28 for a list of the copyright holders.
30 Permission is granted to make and distribute verbatim
31 copies of this manual provided the copyright notice and
32 this permission notice are preserved on all copies.
35 Permission is granted to process this file through TeX
36 and print the results, provided the printed document
37 carries a copying permission notice identical to this
38 one except for the removal of this paragraph (this
39 paragraph not being relevant to the printed manual).
42 Permission is granted to copy and distribute modified
43 versions of this manual under the conditions stated in
44 the section entitled ``License, Warranty, and Authors of Wine''.
47 FIXME: UNIX and POSIX trademarks. @*
49 Microsoft, Windows, MS-Windows, Windows-NT, Windows 95, and MS-DOS are
50 registered trademarks of Microsoft Corporation.
51 NT is a trademark of Northern Telecom Limited.
52 C++Builder is a trademark of Borland International, Inc.
53 Postscript is a registered trademark of Adobe Systems Inc.
54 Other trademarks are the property of their respective owners, which may
55 be registered in certain jurisdictions.
58 @c begin chapters on right pages
59 @setchapternewpage odd
64 @center @titlefont{The Wine Reference Manual}
65 @center Edition 0.0.3, 14 August 1997
68 @c The following two commands start the copyright page.
70 @vskip 0pt plus 1filll
72 Copyright @copyright{} 1997 The Wine authors. @*
73 @xref{Authors, The Wine Authors, The Wine Authors},
74 for a list of the copyright holders.
76 Permission is granted to make and distribute verbatim
77 copies of this manual provided the copyright notice and
78 this permission notice are preserved on all copies.
80 Permission is granted to copy and distribute modified
81 versions of this manual under the conditions stated in
82 the section entitled ``License, Warranty, and Authors of Wine''.
85 FIXME: UNIX and POSIX trademarks. @*
87 Microsoft, Windows, MS-Windows, Windows-NT, Windows 95, and MS-DOS are
88 registered trademarks of Microsoft Corporation.
89 NT is a trademark of Northern Telecom Limited.
90 C++Builder is a trademark of Borland International, Inc.
91 Postscript is a registered trademark of Adobe Systems Inc.
92 Other trademarks are the property of their respective owners, which may
93 be registered in certain jurisdictions.
99 @c SETTINGS, DEFINES, MACROS
102 @c Edit this macro manually in the above parts of the document
103 @macro winemanualversion
107 @c Edit this macro manually in the above parts of the document
108 @macro winemanualdate
112 @c Edit this macro manually into the TeX titlepage
113 @macro winemanualtitle
114 The Wine Reference Manual
125 @c FIXME: automatical trademark reference
130 @c FIXME: automatical trademark reference
131 @c spell it always the same
139 @c FIXME: automatical trademark reference
144 @c FIXME: automatical trademark reference
149 @c FIXME: automatical trademark reference
158 @c FIXME: automatical trademark reference
163 @c FIXME: automatical trademark reference
180 @c flag out differences to MS-Windows
182 @emph{Differences to @mswindows{}:} @*
187 No differences known.
190 @c tell whether function is present in Windows 95 and/or NT
192 @emph{Conformance to @mswindows{}:} @*
197 Present in @WIN95{} and @WINNT{}.
200 @c give information about completion
202 @emph{Completion status:} @*
205 @macro completionnone
211 @c MACROS FOR FUNCTIONS, TYPES, CONSTANTS, VARIABLES
214 @c Constants in the WIN32 API
215 @macro defvr_cw32 {restofline}
216 @defvr Constant \restofline\
218 @macro defvrx_cw32 {restofline}
219 @defvrx Constant \restofline\
222 @c Functions in the WIN32 API
223 @macro deftypefn_w32 {restofline}
224 @deftypefn {WIN32 function} \restofline\
226 @macro deftypefnx_w32 {restofline}
227 @deftypefnx {WIN32 function} \restofline\
230 @c Types in the WIN32 API
231 @macro deftp_w32 {restofline}
232 @deftp {Data type} \restofline\
234 @macro deftpx_w32 {restofline}
235 @deftpx {Data type} \restofline\
238 @c Macros internal to Wine
239 @macro deffn_winemacro {restofline}
240 @deffn {Wine internal macro} \restofline\
242 @macro deffnx_winemacro {restofline}
243 @deffn {Wine internal macro} \restofline\
246 @c Constants internal to Wine
247 @macro defvr_cwine {restofline}
248 @defvr {Wine internal constant} \restofline\
250 @macro defvrx_cwine {restofline}
251 @defvrx {Wine internal constant} \restofline\
259 @node Top, Copying, (dir), (dir)
262 This is edition @winemanualversion{}, last updated @winemanualdate{},
263 of @winemanualtitle{}.
265 Wine (Wine Is Not an Emulator, or the WINdows Emulator)
266 is both an emulator that runs @mswindows{} executables and a library
267 that can be used to compile @mswindows{} source code.
269 Wine is free software. Wine is still in development-only state.
273 * Copying:: License, Warranty, and Authors of Wine.
274 * Introduction:: A short overview.
275 * Reference Manual:: The Wine reference manual.
276 * Installation:: Installing and configuring Wine.
277 * The Wine Project:: How to contribute to Wine.
278 * Concept Index:: Index of concepts and names.
279 * Type Index:: Index of types and type qualifiers.
280 * Function Index:: Index of functions and function-like
282 * Variable Index:: Index of variables, constants, and
283 variable-like macros.
284 * File Index:: Index of programs and files.
287 @node Copying, Introduction, Top, Top
289 @unnumbered License, Warranty, and Authors of Wine
290 @cindex copying conditions for Wine
291 @cindex conditions for copying Wine
292 @cindex Wine copying conditions
294 The Wine license, warranty, and list of authors together form the
295 copyright for Wine. Read these sections carefully.
298 * License:: The Wine license.
299 * Warranty:: Wine comes with no warranty.
300 * Authors:: The persons that contributed to Wine.
303 @node License, Warranty, , Copying
305 @cindex license of Wine
307 @unnumberedsec The Wine License
308 Wine is distributed under the following copyright.
314 @node Warranty, Authors, License, Copying
315 @cindex Wine warranty
316 @cindex warranty of Wine
318 @unnumberedsec The Wine Warranty
324 @node Authors, , Warranty, Copying
326 @cindex authors of Wine
327 @cindex copyright holders of Wine
328 @cindex Wine copyright holders
330 @unnumberedsec The Wine Authors
336 These persons also hold the copyright on Wine.
338 The overall coordination is done by @*
339 Alexandre Julliard @*
340 @email{julliard@@lrc.epfl.ch}
344 @node Introduction, Reference Manual, Copying, Top
345 @chapter Introduction
348 @center the WINdows Emulator,
349 @center or Wine Is Not an Emulator
351 FIXME: make an easy-readable fluent text out of this.
353 Welcome to @winemanualtitle{}. This is edition @winemanualversion{},
354 last updated @winemanualdate{}.
356 @strong{What is Wine?}
358 Wine is a program that allows running MS-Windows programs under X11.
361 Wine incorporates two features, the program loader and @winelib{}:
364 You can run @mswindows{} binaries (programs) in Wine. Wine contains a
365 program loader which loads and executes an @mswindows{} binary. It uses
366 the @winelib{} features of Wine to translate @WIN32{} and @WIN16{} calls
367 to their @unix{}/X11 equivalent.
369 Both 16 bit and 32 bit binaries can be loaded.
371 @winelib{}: Wine can also be used as a library which implements the
372 @mswindows{} API on top of a @unix{} or @unix{}-like operating system
373 with X11. @winelib{} (i.e. the Wine library) translates @WIN16{} or
374 @WIN32{} API calls to their @unix{}/X11 equivalent.
376 You can write a user-level application program that calls the @WIN16{}
377 or @WIN32{} API functions and compile it on a @unix{} box.
382 Wine is still at development stage. The file @file{ANNOUNCE} says,
383 ``This is still a developer's only release. There are many bugs and
384 many unimplemented API features. Most applications still do not work
386 @xref{Warranty}, for additional information.
388 @strong{Requirements}
390 Wine needs an 80x86 CPU to run on. Emulating the CPU is currently not
393 Currently, you must have one of:
396 Linux version 0.99.13 or above
400 FreeBSD-current or FreeBSD 1.1
402 You need X11, and you must have @file{libXpm} installed on your system.
404 @strong{Availability}
406 Wine is free software. The file @file{README} says, ``Basically, you can do
407 anything with it, except claim that you wrote it.''
408 @xref{Copying}, for more information.
412 Wine is expected to run @mswindows{} binaries about the same speed as
413 @mswindows{} would. However, be aware that the 16 bit versions of
414 @mswindows{} programs are generally slower than their 32 bit
417 @strong{Further information}
419 You should consult the files @file{README}, @file{ANNOUNCE},
420 @file{RELEASE-NOTES}, @file{BUGS}, @file{LICENSE}, and @file{WARRANTY},
421 in the root directory of the Wine distribution.
423 The Wine FAQ, available from @*
424 @url{ftp://ftp.asgardpro.com/wine/dave/Wine.FAQ}, @*
425 @url{ftp://tsx-11.mit.edu/pub/linux/ALPHA/Wine/Wine.FAQ}, @*
426 @url{ftp://rtfm.mit.edu/pub/usenet-by-group/comp.emulators.ms-windows.wine/WINE_(WINdows_Emulator)_Frequently_Asked_Questions}, @*
427 @url{ftp://sunsite.unc.edu/pub/Linux/ALPHA/wine/Wine.FAQ}, @*
428 @url{http://www.asgardpro.com/wine/index.html}, @*
429 gives answer to a lot of questions.
431 The Wine USENET newsgroup is interesting for developers. It discusses technical
432 matters about Wine. The address is: @url{news:comp.emulators.ms-windows.wine}.
436 @xref{The Wine Project}, if you consider contributing some work.
440 @node Reference Manual, Installation, Introduction, Top
443 * @WIN32{} Reference Manual:: The @WIN32{} function calls and data types.
444 * Resources and INI files:: How to determine the appearance and
445 behaviour of Wine programs.
446 * Metafiles--Icons--Bitmaps:: FIXME missing.
447 * Debugging:: Debugging Wine.
448 * Programs:: Programs written to run in/with Wine.
449 * Tools:: Programs to support Wine.
452 @node @WIN32{} Reference Manual, Resources and INI files, , Reference Manual
453 @chapter The @WIN32{} Reference Manual
456 * Kernel Objects:: How the Wine kernel keeps information.
457 * Processes and Threads:: Job control and management in Wine.
458 * Users and Groups:: Security in Wine.
459 * Date and Time:: Functions for getting the date and time
460 and for conversion between formats.
461 * System Information:: Getting information about the hardware
462 and software the system runs on.
463 * Memory Management:: How your programs get memory from
465 * I/O Facilities:: Input/Output in Wine.
466 * Communication:: How processes can communicate.
467 * Windows and Graphics:: GUI functions of @WIN32{}.
468 * Errors and Exceptions:: How your program can report errors.
470 * Resources:: Functions for dealing with resources.
471 * The Registry:: FIXME missing.
472 * Dynamic Link Libraries:: Functions for dealing with DLL's.
475 @node Kernel Objects, Processes and Threads, , @WIN32{} Reference Manual
476 @section Kernel Objects
479 @node Processes and Threads, Users and Groups, Kernel Objects, @WIN32{} Reference Manual
480 @section Processes and Threads
482 @node Users and Groups, Date and Time, Processes and Threads, @WIN32{} Reference Manual
483 @section Users and Groups
485 @node Date and Time, System Information, Users and Groups, @WIN32{} Reference Manual
486 @section Date and Time
488 This section describes functions for manipulating dates and times. This
489 includes the current time, the creation or manipulation times of files
490 and other objects, and conversion between different time
494 * File Times:: Creation and manipulation times of files.
497 @node File Times, , , Date and Time
498 @subsection File Times
501 * Type FILETIME:: The data structure used for specifying
503 * Compare File Times:: Compare two file times.
507 @c *** struct FILETIME ***
509 @node Type FILETIME, Compare File Times, , File Times
510 @subsubsection Type FILETIME
513 File times in Wine are specified by the data type @code{FILETIME},
514 defined in @file{windows.h}.
516 @deftpx_w32 LPFILETIME
517 This is the data type for specifying file times. The file times are
518 stored with 64 bit precision. The actual data type is a structure with
519 two 32-bit values which are interpreted as the low and high parts of a
520 64-bit value. This value gives a time measured in a granularity of 100
521 nanoseconds, so 1.5 seconds are specified by a value of 15,000,000. In
522 Wine, this 64-bit value is signed, with the sign taken from the high
523 part. The lower part is used as unsigned.
525 The definition of @code{FILETIME} reads:
530 INT32 dwHighDateTime;
531 @} FILETIME, *LPFILETIME;
534 @cindex epoch in file time
535 The @code{FILETIME} structure may be used to hold absolute or relative
536 times. Absolute times are given as the number of 100 nanoseconds
537 intervals elapsed since 1 January 1601, 00:00:00 UTC (Coordinated
538 Universal Time, which is GMT, Greenwich Mean Time). This might be
539 called the @dfn{epoch} for file times. With a signed 64-bit value, this
540 representation covers absolute times of 29247 years around the epoch.
541 To convert this type to local time, use the function
542 @code{FileTimeToLocalFileTime}.
545 In @mswindows{}, the elements of the structure are apparently of type
546 @code{DWORD}. Whether the full 64 bit value is interpreted as signed or
547 unsigned I do not know.
551 @c *** CompareFileTime ***
553 @node Compare File Times, , Type FILETIME, File Times
556 The Wine function @code{CompareFileTime} compares two file times, and
557 returns whether the first time is less than, equal to, or greater than
558 the second file time. It is defined in @file{windows.h}.
559 @deftypefn_w32 LONG CompareFileTime (@w{CONST FILETIME* @var{time_1},} @w{CONST FILETIME* @var{time_2})}
560 This function returns @code{1}, if @var{time_1} is greater than
561 @var{time_2}, @code{-1} if it is less, and @code{0} if both times are
571 @node System Information, Memory Management, Date and Time, @WIN32{} Reference Manual
572 @section System Information
574 @node Memory Management, I/O Facilities, System Information, @WIN32{} Reference Manual
575 @section Memory Management
577 @node I/O Facilities, Communication, Memory Management, @WIN32{} Reference Manual
578 @section I/O Facilities
580 This section describes all input/output of a process, except for two
581 topics: communication with other processes, and communication with the
585 * I/O on Files:: Accessing the contents of files.
586 * File System Interface:: Functions for manipulating files as a whole.
589 @node I/O on Files, File System Interface, , I/O Facilities
590 @subsection I/O on Files
592 @node File System Interface, , I/O on Files, I/O Facilities
593 @subsection File System Interface
595 These functions are concerned with operating on files themselves, rather
596 than on their contents.
599 * Type BY_HANDLE_FILE_INFORMATION:: The data structure used to
600 specify file information.
601 * File attributes:: The file attributes flags in
602 a file information structure.
603 * Getting file information:: These functions let you obtain
604 information about a file.
607 @node Type BY_HANDLE_FILE_INFORMATION, File attributes, , File System Interface
608 @subsubsection The file information structure
610 The file information structure of Wine is used to obtain information
611 about files. It is declared in the header @file{winedows.h}.
612 @deftp_w32 BY_HANDLE_FILE_INFORMATION
613 This is the data type for specifying information about files as objects
614 of the file system. It contains the following members:
616 @item int dwFileAttributes
617 @cindex file attributes in file information
618 @cindex attributes of file in file information
619 @xref{File attributes}, for details.
620 @item FILETIME ftCreationTime
621 @cindex creation time in file information
622 @cindex time of file creation in file information
623 The time when the file was created.
624 @xref{Type FILETIME}, for details.
625 @item FILETIME ftLastAccessTime
626 @cindex access time in file information
627 @cindex time of file access in file information
628 The time when the file was last accessed.
629 @xref{Type FILETIME}, for details.
630 @item FILETIME ftLastWriteTime
631 @cindex write time in file information
632 @cindex time of last file write in file information
633 The time when the file was last written to.
634 @xref{Type FILETIME}, for details.
635 @item int dwVolumeSerialNumber
636 @cindex serial number of volume in file information
637 @cindex volume number (serial) in file information
638 The serial number of the volume containing the file. In Wine,
640 @item int nFileSizeHigh
641 @cindex file size in file information
642 @cindex size of file in file information
643 A 32 bit value which contains the high part of the 64 bit file size.
644 @item int nFileSizeLow
645 A 32 bit value which contains the low part of the 64 bit file size.
646 @item int nNumberOfLinks
647 @cindex hard links number in file information
648 @cindex links (number of hard) in file information
649 This is the number of hard links to the file. In a file system which
650 does not support hard links, this is 1.
651 @item int nFileIndexHigh
652 @cindex inode number in file information
653 @cindex file index in file information
654 @cindex index of file in file information
655 A 32 bit value which contains the high part of the 64 bit file
656 index. The file index is a unique number for a file on a volume.
657 This identifier cannot change while the file is opened by a process.
658 Together with the volume number, the file index is a unique
659 identifier for the file. This can be used by an application to check
660 whether two handles refer to the same file. Wine currently uses the
661 inode number for the file index.
662 @item int nFileIndexLow
663 A 32 bit value which contains the low part of the 64 bit file index.
666 The definition of @code{BY_HANDLE_FILE_INFORMATION} reads:
670 int dwFileAttributes;
671 FILETIME ftCreationTime;
672 FILETIME ftLastAccessTime;
673 FILETIME ftLastWriteTime;
674 int dwVolumeSerialNumber;
680 @} BY_HANDLE_FILE_INFORMATION ;
683 The @code{BY_HANDLE_FILE_INFORMATION} structure can be obtained by the
684 @code{GetFileInformationByHandle} function (@pxref{Getting file information}, for
688 In @mswindows{}, the @code{int} elements of the structure are apparently
689 of type @code{DWORD}.
692 @node File attributes, Getting file information, Type BY_HANDLE_FILE_INFORMATION, File System Interface
693 @subsubsection The file attributes in a file information structure
695 The file attributes in a file information structure and in other structures
696 are a logical @emph{or} of one or more of the following constants:
698 @defvr_cw32 FILE_ATTRIBUTE_READONLY
699 The file is a read-only file. (Wine value: 0x0001).
701 @defvr_cw32 FILE_ATTRIBUTE_HIDDEN
702 The file is a hidden file. Files in Wine do not have this attribute. (Wine value:
705 @defvr_cw32 FILE_ATTRIBUTE_SYSTEM
706 The file belongs to the operating system. Files in Wine do not have this
707 attribute. (Wine value: 0x0004).
709 @defvr_cw32 FILE_ATTRIBUTE_LABEL
710 This is not present in the @mswindows{} API. (Wine value: 0x0008).
712 @defvr_cw32 FILE_ATTRIBUTE_DIRECTORY
713 The file is a directory. (Wine value: 0x0010).
715 @defvr_cw32 FILE_ATTRIBUTE_ARCHIVE
716 The file is an archive file. Currently, all non-directory files are
717 reported by Wine to have this attribute. This attribute is normally set
718 by @mswindows{} to indicate that a file is to be archived; when the file
719 is archived, the flag is cleared. (Wine value: 0x0020).
721 @defvr_cw32 FILE_ATTRIBUTE_NORMAL
722 The file does not have any other attributes set. This value must be used
723 alone. In Wine, normal files are reported as archive files. (Wine value:
726 @defvr_cw32 FILE_ATTRIBUTE_TEMPORARY
727 The file is used as a temporary storage. Files in Wine do not have this
728 attribute. (Wine value: 0x0100).
730 @defvr_cw32 FILE_ATTRIBUTE_ATOMIC_WRITE
731 This is reserved for future use. Files in Wine do not have this
732 attribute. (Wine value: 0x0200).
734 @defvr_cw32 FILE_ATTRIBUTE_XACTION_WRITE
735 This is reserved for future use. Files in Wine do not have this
736 attribute. (Wine value: 0x0400).
738 @defvr_cw32 FILE_ATTRIBUTE_COMPRESSED
739 The file is compressed. Files in Wine do not have this attribute. (Wine
743 @node Getting file information, , File attributes, File System Interface
744 @subsubsection Getting file information
746 The functions in this section describe how to get information about
750 @c *** GetFileInformationByHandle
753 The Wine function @code{GetFileInformationByHandle} returns a file
754 information structure. It is defined in @file{windows.h}.
756 @deftypefn_w32 BOOL GetFileInformationByHandle (@w{HFILE32 @var{file},} @w{BY_HANDLE_FILE_INFORMATION *@var{info})}
757 This function obtains for the specified @var{file} the file information,
758 and stores it in @var{info}. The file information contains the file
759 attributes, the file times, the volume serial number, the file size, the
760 number of links, and a unique file identifier. The function returns
761 @code{TRUE} on success, @code{FALSE} on failure.
766 The Wine function can of course only give back information that is
767 accessible in the @unix{} file system. File times are produced in a
768 granularity of full seconds. Most file attributes are not present in the
769 @unix{} file system. @xref{File attributes}, for details. The volume
770 serial number is set to 0.
775 @c *** GetFileTime ***
778 The Wine function @code{GetFileTime} returns the creation time and
779 the times of last the read and modification access to a file. It is
780 defined in @file{windows.h}.
782 @deftypefn_w32 BOOL GetFileTime (@w{HANDLE @var{file},} @w{LPFILETIME @var{ctime},} @w{LPFILETIME @var{atime},} @w{LPFILETIME @var{mtime})}
783 This function obtains for the specified @var{file} the creation time
784 @var{ctime}, the time of the last access to the file @var{atime}, and
785 the time of the last modification (write) to the file, @var{mtime}.
786 The file time arguments of this function are pointers to @code{FILETIME}
787 variables, which are filled with a value that indicates an absolute time
788 in UTC. @xref{Type FILETIME}, for details. If you do not need some of
789 the times, you can pass a @code{NULL} pointer.
790 The function returns @code{TRUE} on
791 success, @code{FALSE} on failure.
796 The file times are produced in a granularity of full seconds, due to the
797 underlying @unix{} file system.
801 @c *** GetFileAttributes ***
804 The Wine function @code{GetFileAttributes} returns the file attributes
805 for a file. It is defined in @file{windows.h}.
807 @deftypefn_w32 DWORD GetFileAttributes (@w{LPCTSTR @var{name})}
808 This function looks up the file with name @var{name}, and returns the
809 attributes of the file. @xref{File attributes}, for details on the file
810 attributes. If the function is not successful, it returns a word with
811 all bits set (@samp{0xffffffff}).
816 Most file attributes are not present in the
817 @unix{} file system. @xref{File attributes}, for details.
823 @node Communication, Windows and Graphics, I/O Facilities, @WIN32{} Reference Manual
824 @section Communication
826 @node Windows and Graphics, Errors and Exceptions, Communication, @WIN32{} Reference Manual
827 @section Windows and Graphics
829 @node Errors and Exceptions, Resources, Windows and Graphics, @WIN32{} Reference Manual
830 @section Errors and Exceptions
832 @node Resources, The Registry, Errors and Exceptions, @WIN32{} Reference Manual
835 @node The Registry, Dynamic Link Libraries, Resources, @WIN32{} Reference Manual
836 @section The Registry
838 @node Dynamic Link Libraries, , The Registry, @WIN32{} Reference Manual
839 @section Dynamic Link Libraries (DLL's)
841 This section deals with API functions for handling DLL's (dynamic link
842 libraries). It does not describe DLL's themselves; nor does it give
843 information on how Wine handles DLL's. @xref{The build program}, for
844 information on how DLL's are integrated into Wine.
849 @node Resources and INI files, Metafiles--Icons--Bitmaps, @WIN32{} Reference Manual, Reference Manual
850 @chapter Resources and @file{INI} Files
852 @node Metafiles--Icons--Bitmaps, Debugging, Resources and INI files, Reference Manual
853 @chapter Metafiles --- Icons --- Bitmaps
855 @node Debugging, Programs, Metafiles--Icons--Bitmaps, Reference Manual
858 @node Programs, Tools, Debugging, Reference Manual
861 @node Tools, , Programs, Reference Manual
864 This chapter describes some of the tools that are used by Wine. These
865 are not user-level programs which the user of Wine will
866 run. @xref{Programs} for such programs.
868 Tools are internal programs that are used to help compile or configure
872 * The build program:: A program used to build the DLL entry
873 points from specifications in @file{if1632/}.
877 @node The build program, , , Tools
878 @section The @file{build} program
880 @cindex modules of Wine
882 @cindex DLL's built-in in Wine
883 @cindex Wine DLL's built-in
884 @cindex built-in DLL's in Wine
885 Wine contains several modules that implement various DLL's which are
886 required to run @mswindows{} programs.
888 The @file{build} program, located in the @file{tools/} directory, is
889 used to create the bindings for the DLL entry points of the API functions.
890 This program reads a @file{.spec}-file in the @file{if1632} directory
891 and creates the assembly code that translates the function arguments
896 * The spec files:: The format of the @file{.spec}-files.
899 FIXME: where in Wine are the DLL's affixed?
901 FIXME: write a description
903 @xref{Implementing an API function}, for notes on using this program.
905 @node The spec files, , , The build program
906 @subsection The @file{.spec}-files
907 @cindex DLL spec files
908 @cindex spec files of DLL's
909 @cindex entry points in DLL's
911 This subsection describes the format of the @file{.spec}-files.
913 A @file{.spec}-file contains the information about the functions,
914 variables, and constants that are contained in a DLL (dynamic link
917 To be able to interpret the contents of a @file{.spec}-file, you must
918 know about the concept of ordinals.
920 * The general format:: General format conventions.
921 * Ordinals:: Ordinals are indexes of entry
923 * Spec file header:: The header information.
924 * Variable entry points:: Entries for DLL variables.
925 * Function entry points:: Entries for DLL functions.
926 * Special entries:: Entries for stubs, dummy
927 functions, Wine symbols, and
931 @node The general format, Ordinals, , The spec files
932 @subsubsection The general format
933 @cindex format of spec files
934 @cindex spec files format
936 The @file{.spec}-file contains a header and a sequence of declarations.
937 Each declaration describes an ordinal.
939 The header gives general information about the DLL and its properties.
941 Ordinal declarations are optional. That means that there is a default
942 behaviour assigned to ordinals which are not mentioned in the
943 @file{.spec}-file. The default handler function of an ordinal will print
944 an error message when called.
946 Comments are indicated by hash marks (@samp{#}); everything between a
947 hash mark and the end of the line is ignored.
949 Empty lines are allowed.
950 @* FIXME: is that so?
952 @node Ordinals, Spec file header, The general format, The spec files
953 @subsubsection Ordinals
954 @cindex ordinals in DLL's
957 All references to DLL objects like functions or variables are indexed by
958 unique nonnegative numbers. These numbers are called
959 @dfn{ordinals}. Apparently, a program can refer to a DLL function or
960 variable by specifying its name or its ordinal. Although reference by
961 name is the common usage, some program parts (notably DLL's themselves)
962 sometimes refer to DLL entries by ordinal. Therefore, the ordinals
963 cannot be chosen arbitrarily.
965 Regular programs that are compiled and linked against @mswindows{} DLL's
966 will import DLL functions by name. This is therefore the default
967 behaviour. Most DLL functions will be imported by name in all cases.
968 Apparently, the @WIN32{} DLL's even show some difference in the mapping
969 of functions and ordinals on @WINNT{} and @WIN95{}. For most DLL
970 functions, the ordinal number will not matter.
972 There are some exceptions to that. Notable the KERNEL32 ordinals below
973 100 are (presently) unnamed and undocumented functions which can only be
974 imported by ordinal. These functions are called by some @mswindows{}
975 programs. Also the @file{shell32.dll} functions are reported to be
976 imported by ordinal in some other DLL's.
978 @xref{Getting information on the API}, for sources of further information.
980 @node Spec file header, Variable entry points, Ordinals, The spec files
981 @subsubsection The header of a @file{.spec}-file
983 The @file{.spec}-file starts with two mandatory definitions. The first
984 line gives the name of the DLL which the @file{.spec}-file describes,
988 where @var{NAME} is the name of the DLL. The next line defines the type
993 with @var{TYPE} being either @samp{win16} or @samp{win32}.
995 An optional statement of the form
999 can be used to define the offset of the first ordinal. @var{ORDINAL}
1000 must be an integer number. If no base is specified, the offset is zero.
1001 @* FIXME: is this the offset of the first or an offset that is added to all
1003 what is the offset? Is it added to the ordinals, or is it an address, or
1006 An optional statement like
1010 can be used to define the size of the module local heap. This is only
1011 used for @WIN16{} DLL's. The local heap is the place where the segments
1012 of 16 bit programs can locally allocate memory, without interfering with
1013 one another. The default size of the local heap, if not specified, is 0.
1015 @* FIXME: to my impression, a local heap in DLL's would only be required
1016 if DLL functions used it. As all DLL functions in Wine are truly 32 bit
1017 functions that are mapped from 16 bit on being called and back to 16 bit
1018 on returning, a local heap should never be necessary.
1019 If I receive a confirmation of that here, I will state so. Otherwise I
1020 am missing some information on local heaps.
1021 But why is a heap defined in user.spec and gdi.spec?
1023 @node Variable entry points, Function entry points, Spec file header, The spec files
1024 @subsubsection Variable entry points of @file{.spec}-files
1026 You can declare an ordinal that holds data. Data items may be of 8, 16,
1030 @var{ORDINAL} @var{VARTYPE} @var{EXPORTNAME} (@var{DATA} @var{[DATA @dots{}]})
1033 @var{ORDINAL} is the ordinal number corresponding to the
1034 variable. @var{VARTYPE} must be @samp{byte}, @samp{word}, or
1035 @samp{long}, for 8, 16, or 32 bits respectively. @var{EXPORTNAME} will
1036 be the name available for dynamic linking. @var{DATA} can be a decimal
1037 number or a hex number preceded by @samp{0x}. Each @var{DATA} item defines
1040 The following example defines the variable @samp{VariableA} at ordinal
1041 2, containing 4 bytes:
1043 2 byte VariableA(-1 0xff 0 0)
1047 @node Function entry points, Special entries, Variable entry points, The spec files
1048 @subsubsection Function entry points of @file{.spec}-files
1051 @var{ORDINAL} @var{FUNCTYPE} @var{EXPORTNAME} (@var{[ARGTYPE} @dots{} @var{]}) @var{HANDLERNAME}
1054 @var{ORDINAL} is the ordinal number corresponding to the
1055 function. @var{FUNCTYPE} must be chosen from this table:
1058 A @WIN16{} function that returns a 16 bit value.
1060 A @WIN16{} function that returns a 32 bit value.
1062 A function using CPU registers to pass arguments.
1064 A normal @WIN32{} function. @xref{Investigating the undocumented API},
1065 for an explanation of the stdcall calling convention.
1067 A @WIN32{} function using the C calling conventions. (This is presently
1068 only used for the built-in functions of the C runtime system).
1071 @var{EXPORTNAME} specifies the name (prototype) available for dynamic
1074 @var{ARGTYPE} must be chosen from this table:
1077 An 8 bit argument. Can be used in @WIN16{} functions only.
1079 A 16 bit argument. Can be used in @WIN16{} functions only.
1081 A 32 bit argument. Can be used in @WIN16{} or @WIN32{} functions.
1083 A linear pointer, unsegmented. Can be used in @WIN16{} or @WIN32{}
1086 A linear pointer, unsegmented, pointing to a null-terminated string.
1087 Can be used in @WIN16{} or @WIN32{} functions.
1089 A signed 8 bit argument. Can be used in @WIN16{} functions only.
1091 A signed 16 bit argument. Can be used in @WIN16{} functions only.
1093 A signed 32 bit argument. Can be used in @WIN16{} or @WIN32{}
1096 A segmented pointer. Can be used in @WIN16{} functions only.
1098 A segmented pointer to a null-terminated string. Can be used in
1099 @WIN16{} functions only.
1102 @var{HANDLERNAME} is the name of the actual Wine function that will
1103 process the request in 32-bit mode.
1107 Here are some examples. The first example defines an entry point for the
1108 @code{CreateWindow()} call (the ordinal 100 is just an example):
1110 100 pascal CreateWindow(ptr ptr long s_word s_word s_word s_word
1111 word word word ptr) WIN_CreateWindow
1114 The second example defines an entry point for the @code{GetFocus()} call
1115 (again, the ordinal 100 is an example):
1117 100 pascal GetFocus() WIN_GetFocus()
1120 To declare a function that uses a variable number of arguments, specify
1121 the function as taking no arguments. In this special case, in @WIN32{}
1122 the called function will be passed a pointer to the first arg; in
1123 @WIN16{}, the args are available as @code{CURRENT_STACK16->args}.
1124 @* FIXME: create a reference here
1125 See the @code{wsprintf}* functions in @file{user.spec} and
1126 @file{user32.spec} for an example.
1128 Sometimes it is not known how many arguments an undocumented DLL
1129 function takes. @xref{Getting information on the API}, for some hints on
1130 how to proceed in such a case.
1132 @node Special entries, , Function entry points, The spec files
1133 @subsubsection Special entries of @file{.spec}-files
1135 The @file{.spec}-files offer the possibility to use some special
1136 entries. These entries are used for stubs (which allow linking for
1137 non-existing functions), dummy functions that do not perform any
1138 operations, Wine symbols that must be referenced directly, and constant
1142 @strong{Stub ordinals}
1144 This pseudo function type defines a stub function. It makes the name and
1145 ordinal available for dynamic linking, but will terminate execution with
1146 an error message if the function is ever called.
1149 @var{ORDINAL} stub @var{EXPORTNAME}
1152 @var{ORDINAL} is the ordinal number corresponding to the
1153 function. @var{EXPORTNAME} specifies the name (prototype) available for dynamic
1156 @strong{Return ordinals}
1158 This pseudo function type defines a function entry point whose handler
1159 should do nothing but return a value.
1161 @var{ORDINAL} return @var{EXPORTNAME} @var{ARGLENGTH} @var{RETVALUE}
1164 @var{ORDINAL} is replaced by the ordinal number corresponding to the
1165 function. @var{ARGLENGTH} is the number of bytes that need to be removed
1166 from the stack before returning to the caller. @xref{Investigating the
1167 undocumented API}, for an explanation of the stdcall calling convention.
1168 @var{RETVALUE} is the return value which will be passed back to the
1171 @strong{Extern ordinals}
1174 @var{ORDINAL} extern @var{EXPORTNAME} @var{SYMBOLNAME}
1176 This type defines an entry that simply maps to a Wine symbol
1177 (variable or function); @var{EXPORTNAME} will point to the symbol
1178 @var{SYMBOLNAME} that must be defined in C code. This type only works with
1182 @strong{Equate ordinals}
1185 @var{ORDINAL} equate @var{EXPORTNAME} @var{DATA}
1188 This type defines an ordinal as an absolute value.
1189 @var{ORDINAL} is replaced by the ordinal number corresponding to the
1190 entry. @var{EXPORTNAME} will be the name available for dynamic linking.
1191 @var{DATA} can be a decimal number or a hex number preceeded by @samp{0x}.
1194 @node Installation, The Wine Project, Reference Manual, Top
1195 @chapter Wine installation and configuration
1196 FIXME: write installation guide
1199 * Applying patches:: How to update Wine to a newer version.
1202 @node Applying patches, , , Installation
1203 @section Applying patches
1204 @xref{Creating patches}, for instructions on creating patches.
1206 FIXME: write patch instructions
1209 @node The Wine Project, , Installation, Top
1210 @chapter The Wine project
1211 @cindex Wine project contributions
1212 @cindex project contributions to Wine
1214 If you are new to Wine and want to support this project, here are
1218 * Getting information on the API:: Official and unofficial sources
1219 of information on the @WIN32{} API.
1220 * Investigating the undocumented API:: You can find out some API
1221 information on your own.
1222 * Implementing an API type:: How to implement a data type
1223 of the API (a checklist).
1224 * Implementing an API function:: How to implement one function
1225 of the API (a checklist).
1226 * API function and type naming:: How to name API functions in Wine.
1227 * Creating patches:: How to create patches for Wine.
1228 * Adding Documentation:: Templates for the documentation.
1229 * File names:: How Wine treats @mswindows{} and
1231 * Wide character strings:: How Wine treats wide character
1235 @xref{Debugging}, for advice on how to debug Wine.
1236 @xref{Applying patches}, for instructions on applying patches.
1239 @node Getting information on the API, Investigating the undocumented API, , The Wine Project
1240 @section Official and unofficial documentation on the @mswindows{} API
1241 @cindex documentation of API functions
1242 @cindex undocumented API functions
1245 @strong{Official documentation}
1247 For documentation on @WIN32{} API functions, you might try one of these
1253 There is a free online version of the MSDN library (including
1254 documentation for the @WIN32{} API) on
1255 @url{http://www.microsoft.com/msdn/}.
1258 The @WINNT{} DDK gives information about some kernel (``executive'')
1259 routines. Some of the function documentation might also apply to user
1263 @strong{Unofficial documentation}
1265 Not all of the @WIN32{} API is well documented. Some functions are
1266 obscured, and undocumented. @xref{Ordinals}, for information about
1267 undocumented functions imported by ordinal. Getting to know what these
1268 functions do can be tiresome and tedious. Here is a quote from a
1269 news posting concerning two books that might help:
1270 @c From: vischne@ibm.net-nospam (root)
1271 @c Subject: Re: Functions
1272 @c Newsgroups: comp.emulators.ms-windows.wine
1273 @c Date: 24 Jul 97 16:45:11 GMT
1274 @c Organization: The Light
1275 @c NNTP-Posting-Host: 129.37.246.203
1276 @c Message-ID: <33d78697.0@news3.ibm.net>
1279 Well actually, there are at least _two_ books that address these problems.
1280 One is by Matt Pietrek, ``Windows 95 System Programming Secrets'', which
1281 gives some auxiliary programs for helping ferret out the information, and
1282 the other is by Shulman, ``Undocumented Windows 95''.
1285 @xref{Ordinals}, for some notes on undocumented kernel functions.
1290 @cindex book on undocumented API features by Pietrik
1291 ``Windows 95 System Programming Secrets'' @*
1293 Book & Disk Edition @*
1294 Paperback, 778 pages @*
1295 Published by IDG Books Worldwide @*
1296 Publication date: November 1, 1995 @*
1297 Dimensions (in inches): 9.25 x 7.42 x 2.06 @*
1301 @cindex book on undocumented API features by Schulman
1302 ``Undocumented Windows; A Programmers Guide
1303 to Reserved Microsoft Windows API Functions'' @*
1304 by Andrew Schulman @*
1305 Paperback, 715 pages @*
1306 Published by Addison-Wesley Pub Co @*
1307 Publication date: February 1, 1994 @*
1308 Dimensions (in inches): 9.11 x 7.37 x 1.53 @*
1312 More books on these topics (including Schulman and Pietrik): @*
1313 @url{http://www.sonic.net/~undoc/bookstore.html}
1316 More details about calling undocumented functions can be found at
1317 @url{http://ftp.uni-mannheim.de/info/OReilly/windows/win95.update/dirty.html}.
1320 In 1993 Dr. Dobbs Journal published a column called ``Undocumented
1323 You might want to check out BYTE from December 1983 as well.
1324 @* FIXME: is that to be taken seriously?
1326 And you might try to find out something on your own. @xref{Investigating
1327 the undocumented API}, for details.
1330 But, all in all, @url{news:comp.emulators.ms-windows.wine} says
1331 @c From: dacut@henry.ece.cmu.edu (David A. Cuthbert)
1332 @c Subject: Re: Getting Internet Explorer to work
1333 @c Newsgroups: comp.emulators.ms-windows.wine
1334 @c Date: 24 Jul 1997 03:10:30 GMT
1335 @c Organization: Electrical & Computer Engineering, Carnegie Mellon University
1336 @c Reply-To: henry.ece.cmu.edu!dacut
1337 @c Message-ID: <5r6h36$86c@fs7.ece.cmu.edu>
1338 @c NNTP-Posting-Host: henry.ece.cmu.edu
1341 Unfortunately, short of getting something like NuMega's SoftIce, I
1342 don't think there's a ``good'' reference on the mystery <100 ordinals in
1347 @node Investigating the undocumented API, Implementing an API type, Getting information on the API, The Wine Project
1348 @section Investigating the undocumented API
1349 @cindex undocumented API investigation
1350 @cindex parameters of undocumented API functions
1351 @cindex stdcall calling convention
1352 @cindex C calling convention
1353 @cindex API function parameters investigation
1354 @cindex stack handling under stdcall calling
1356 Besides reading the documentation in @ref{Getting information on the API},
1357 you can find out some properties of API functions on your own.
1359 Sometimes it is not known how many arguments an undocumented DLL
1360 function takes. Here is a text from a news posting that gives some
1361 hints on how you might proceed in this case.
1363 @c The following text is closely quoted from:
1364 @c From: dacut@henry.ece.cmu.edu (David A. Cuthbert)
1365 @c Subject: Win32 stub functions (Claus Fischer, please read)
1366 @c Newsgroups: comp.emulators.ms-windows.wine
1367 @c Date: 7 Aug 1997 22:33:09 GMT
1368 @c Organization: Electrical & Computer Engineering, Carnegie Mellon University
1369 @c Reply-To: henry.ece.cmu.edu!dacut
1370 @c Message-ID: <5sdif5$qt3@fs7.ece.cmu.edu>
1372 The problem with implementing stubs for @WIN32{} functions is that it is
1373 not sufficient to return a default value (usually 0) and leave the
1374 stack the way we found it. For most @WIN32{} functions -- those that use
1375 the @dfn{stdcall} calling convention -- the arguments sent to the function
1376 are removed from the stack.
1378 Some background: On the i386 class of machines, stack entries are
1379 usually dword (4 bytes) in size, little-endian. The stack grows
1380 downward in memory. The stack pointer, maintained in the @samp{esp}
1381 register, points to the last valid entry; thus, the operation of
1382 pushing a value onto the stack involves decrementing @samp{esp} and then
1383 moving the value into the memory pointed to by esp (i.e., @code{push p}
1384 in assembly resembles @code{*(--esp) = p;} in C). Removing (popping)
1385 values off the stack is the reverse (i.e., @code{pop p} corresponds to
1386 @code{p = *(esp++);}).
1388 In the @dfn{stdcall} calling convention, arguments are pushed onto the
1389 stack right-to-left. For example, the C call
1392 myfunction(40, 20, 70, 30);
1395 is expressed in Intel assembly as:
1405 In addition, the called function is responsible for removing the
1406 arguments off the stack. Thus, before the call to myfunction, the
1407 stack would look like:
1410 [local variable or temporary]
1411 [local variable or temporary]
1418 After the call returns, it should look like:
1421 [local variable or temporary]
1422 esp -> [local variable or temporary]
1425 To restore the stack to this state, the called function must know how
1426 many arguments to remove (which is the number of arguments it takes).
1427 This is a problem if the function is undocumented.
1429 One way to attempt to document the number of arguments each function
1430 takes is to create a wrapper around that function that detects the
1431 stack offset. @file{WinRelay} (see below) was written to create such
1432 wrappers. Essentially, each wrapper assumes that the function will take
1433 a large number of arguments (by default, 64 in @file{WinRelay}). The
1434 wrapper copies each of these arguments into its stack, calls the actual
1435 function, and then calculates the number of arguments by checking esp
1436 before and after the call.
1438 @cindex bsod (blue screen of death)
1439 @cindex blue screen of death
1440 The main problem with this scheme is that the function must actually
1441 be called from another program. Many of these functions are seldom
1442 used. An attempt was made to aggressively query each function in a
1443 given library (@file{ntdll.dll}) by passing 64 arguments, all 0, to each
1444 function. Unfortunately, @WINNT40{} quickly goes to a blue screen
1445 of death (@dfn{bsod}), even if the program is run from a
1446 non-administrator account.
1448 Another method that has been much more successful is to attempt to
1449 figure out how many arguments each function is removing from the
1450 stack. This instruction, @code{ret hhll} (where @samp{hhll} is the
1451 number of bytes to remove, i.e. the number of arguments times 4), contains
1452 the bytes @samp{0xc2 ll hh} in memory. It is a reasonable assumption
1453 that few, if any, functions take more than 16 arguments; therefore,
1454 @samp{hh} is 0x0 and @samp{ll} is less than 0x40. This utility,
1455 @file{MakeSpec} (see below), simply queries the address of a function
1456 and looks for the first occurrence of the bytes @samp{0xc2 ll 0x0},
1457 where @math{@samp{ll} <= 0x40}.
1459 Of course, this is not without errors. @code{ret 00ll} is not the only
1460 instruction that can have the byte sequence @samp{0xc2 ll 0x0}; for
1461 example, @code{push 0x000040c2} has the byte sequence
1462 @samp{0x68 0xc2 0x40 0x0 0x0}, which matches the above. Properly, the
1463 utility should look for this sequence only on an instruction boundary;
1464 unfortunately, finding instruction boundaries on an i386 requires
1465 implementing a full disassemble -- quite a daunting task. Besides,
1466 the probability of having such a byte sequence that is not the actual
1467 return instruction is fairly low.
1469 Much more troublesome is the non-linear flow of a function. For
1470 example, consider the following two functions:
1474 jmp somefunction1_impl
1483 @file{MakeSpec} would incorrectly list both @code{somefunction1} and
1484 @code{somefunction2} as taking only a single argument, whereas
1485 @code{somefunction1} really takes two arguments.
1487 With these limitations in mind, it is possible to implement more stubs
1488 in Wine and, eventually, the functions themselves.
1492 The program @file{WinRelay} can be downloaded from
1493 @url{http://www.ece.cmu.edu/afs/ece/usr/dacut/www/src},
1494 and @file{MakeSpec} will be available from the same location. You can
1495 compile them with Borland's C++Builder; you should not optimize when
1496 compiling (@file{WinRelay} needs the stack frames).
1499 @node Implementing an API type, Implementing an API function, Investigating the undocumented API, The Wine Project
1500 @section Implementing an API type
1502 Here is a checklist that should help you writing your first API type. It
1503 will of course not tell you which elements to put into the type
1504 (assuming it is a structure), but it should help you along the way of
1505 integrating this type into Wine.
1506 @xref{Implementing an API function}, for comparison.
1510 Find out how the type should be named in Wine and in the DLL's.
1511 @xref{API function and type naming}, for details.
1514 Find out where the type should go. Please try to keep the header files
1515 structure as similar to @mswindows{} as possible.
1518 Prepare for the later patch (by saving the original files before you
1519 work on them). @xref{Creating patches}, for details.
1522 Put the type declaration into the header file.
1525 Make sure the declaration is syntactically correct, i.e. it does not
1526 keep Wine from compiling.
1529 Make sure the declared type is layout-compatible with
1530 @mswindows{}-compiled types. Especially keep an eye on the packing of
1532 @* FIXME: a reference to packed structures here.
1535 Build Wine and test the type, if possible. If you cannot test the
1536 type by implementing a proper API function, write a small test program
1537 to test it on its own. Or rather stop here.
1540 Write the documentation of the type in the @file{wine.texinfo}
1541 file. @xref{Adding Documentation}, for details.
1542 With types, be especially careful and document all the details. Also
1543 document all constants or flags that are used in the type.
1546 Create an entry in the @file{ChangeLog} file.
1549 Collect some of these changes, and create a patch. @xref{Creating
1550 patches}, for details.
1553 Mail the patch to Alexandre Julliard, @email{julliard@@lrc.epfl.ch}.
1556 Wait for the patch to appear in the official distribution.
1560 @node Implementing an API function, API function and type naming, Implementing an API type, The Wine Project
1561 @section Implementing an API function
1563 Here is a checklist that should help you writing your first API
1564 function. It will of course not tell you what to do in the function,
1565 but it should help you along the way of integrating this function into
1570 Make sure all data types that appear in function arguments are properly
1571 declared in Wine. Otherwise, start with the data types.
1574 Find out how the function should be named in Wine and in the DLL's.
1575 @xref{API function and type naming}, for details.
1578 Find out what the function should do. This may be tricky for
1579 undocumented functions. @xref{Getting information on the API}, for some
1583 Find out where the function should go:
1586 Which header file for the prototype.
1588 Which C source file.
1590 Which DLL(s), and which ordinal the function will take there. Perhaps
1591 the function name is already present in one of the @file{.spec}-files in
1592 the @file{if1632} directory.
1596 Prepare for the later patch (by saving the original files before you
1597 work on them). @xref{Creating patches}, for details.
1600 Put the prototype into the header file, and the code into the C file.
1603 Make sure the code compiles.
1606 Create or change the information for the DLL entry points in the
1607 @file{.spec}-file in the @file{if1632} directory.
1608 @xref{The build program}, for details of the DLL spec files.
1611 Build Wine and test the function, if possible. If you cannot test the
1612 function in Wine, write a small test program to test it on its own.
1615 Write the documentation of the function in the @file{wine.texinfo}
1616 file. @xref{Adding Documentation}, for details.
1619 Create an entry in the @file{ChangeLog} file.
1622 Collect some of these changes, and create a patch. @xref{Creating
1623 patches}, for details.
1626 Mail the patch to Alexandre Julliard, @email{julliard@@lrc.epfl.ch}.
1629 Wait for the patch to appear in the official distribution.
1633 @node API function and type naming, Creating patches, Implementing an API function, The Wine Project
1634 @section API function and data type naming conventions
1635 @cindex API function names
1636 @cindex API type names
1637 @cindex names of API functions and types
1638 @cindex naming scheme for API functions and types
1639 @cindex suffixes for API functions and types
1640 @cindex endings of API function and type names
1642 This section describes Wine's naming scheme for API functions and data
1645 The purpose of these naming conventions is to ensure that
1648 both the @WIN16{} and @WIN32{} API are supported within the same source
1651 both wide character functions (with @unicode{} strings) and 8 bit
1652 character functions (with @ascii{} or extended @ascii{} encoding) are
1655 the source code can be shared between the emulator and the library
1659 A function or data type whose name in the @mswindows{} API is @var{xxx}
1660 will in the Wine code have the following name(s):
1663 This is the version for the 16 bit API. You might call it the ``16 bit
1664 version'' except that the function itself of course runs in true 32 bit
1665 mode (being part of Wine). So, the correct meaning of the suffix is that
1666 this function is part of the 16 bit API.
1668 This is the version for the 32 bit API. Use this suffix only if the
1669 function does not use character strings in its parameters or return
1670 values. Otherwise use the next two.
1672 This is the version for the 32 bit API which uses @ascii{} strings (or
1673 rather, strings with 8 bit character encodings, i.e. the standard C
1674 @code{char} type). This version always goes together with another
1675 version, using the next suffix.
1677 This is the version for the 32 bit API which uses @unicode{} strings,
1678 i.e. strings with wide characters. It goes together with the @ascii{}
1682 So, where the @mswindows{} API offers one name, Wine actually has two or
1683 three different functions implemented (which will hopefully share a
1684 large part of the code).
1686 Wine allows to use its API functions in two ways. The emulator part of
1687 Wine provides DLL's for the @mswindows{} programs it can run. The
1688 library part of Wine provides a @unix{} programmer with the facility to
1689 use the Wine API's in a standard @unix{} program.
1692 * Access from the emulator:: How to access API functions and types
1693 from applications that are run in the
1695 * Access in the library:: How to access API functions and types
1696 from applications that are linked with
1698 * Access from inside Wine:: How to access API functions and types
1699 from inside the Wine code.
1702 @node Access from the emulator, Access in the library, , API function and type naming
1703 @subsection Accessing API functions and types from the emulator
1704 @cindex access to DLL API functions and types
1705 @cindex Wine emulator access to API functions and types
1706 @cindex emulator access to Wine API functions and types
1708 The emulator part of Wine provides the hooks for dynamically linking the
1709 API functions to the @mswindows{} executables (@file{.EXE}-files). The
1710 Wine emulator contains all versions (16 or 32 bit, @ascii{} or
1711 @unicode{}) of the API functions in one executable. The emulator
1712 performs a mapping from the @mswindows{} name of the function,
1713 by which the executable calls it, to one of the Wine internal names that
1714 have been used in coding it.
1716 This mapping is done by the built-in DLL handling code of Wine. A
1717 programmer of Wine has to declare the function in one of the virtual
1718 DLL's that are provided by Wine. The declarations are done in the
1719 @file{.spec}-files in the @file{if1632/} directory. @xref{The build
1720 program}, for details.
1722 The @mswindows{} application simply calls the API function by its
1723 standard @mswindows{} name. Wine will apply the correct mapping
1724 according to Wine's selected appearance (as a 16 bit or 32 bit emulator,
1725 which is a parameter on invocation of Wine).
1728 @node Access in the library, Access from inside Wine, Access from the emulator, API function and type naming
1729 @subsection Accessing API functions and types in the library
1730 @cindex Wine library API function and type access
1731 @cindex access to Wine library API functions and types
1733 If Wine is built as a library, and linked to a user-level main program,
1734 the user will also use the standard @mswindows{} names for the API
1737 Some macros are defined in @file{include/wintypes.h} which perform the
1738 necessary name mappings.
1740 These macros are (see the examples below):
1741 @deffn_winemacro WINELIB_NAME (@var{xxx})
1742 This macro replaces @var{xxx} by one of @var{xxx}16 or
1743 @var{xxx}32, depending on the definition of the symbols
1744 @code{WINELIB16} and @code{WINELIB32}. @var{xxx} should
1745 be the name of an API function that uses no string arguments.
1746 Use this macro with a @code{#define} to establish the API name @var{xxx}.
1748 @deffn_winemacro WINELIB_NAME_AW (@var{xxx})
1749 This macro replaces @var{xxx} by one of @var{xxx}16, @var{xxx}32A, or
1750 @var{xxx}32W, depending on the definition of the symbols
1751 @code{WINELIB16}, @code{WINELIB32}, and @code{UNICODE}. @var{xxx} should
1752 be the name of an API function that uses string arguments.
1753 Use this macro with a @code{#define} to establish the API name @var{xxx}.
1755 @deffn_winemacro DECL_WINELIB_TYPE (@var{xxx})
1756 This macro declares @var{xxx} to be an equivalent to @var{xxx}16 or
1757 @var{xxx}32, depending on the definition of the symbols
1758 @code{WINELIB16} and @code{WINELIB32}. @var{xxx} should
1759 be the name of an API data type that contains no string arguments.
1761 @deffn_winemacro DECL_WINELIB_TYPE_AW (@var{xxx})
1762 This macro declares the type @var{xxx} to be an equivalent to
1763 @var{xxx}16, @var{xxx}32A, or @var{xxx}32W, depending on the definition
1764 of the symbols @code{WINELIB16}, @code{WINELIB32}, and
1765 @code{UNICODE}. @var{xxx} should be the name of an API data type that
1766 contains string arguments.
1769 If Wine is compiled as an emulator, these macros have no effect, for the
1770 mapping is then done by the DLL code. This means that within Wine the
1771 name @var{xxx} itself will not be defined.
1773 Note: If the definition of @var{xxx} is exactly the same in @WIN16{} and
1774 @WIN32{}, you can simply use the same name as @mswindows{}.
1776 Here are some examples:
1778 /* A simple type without strings */
1779 typedef short INT16;
1781 DECL_WINELIB_TYPE(INT);
1783 /* A type with strings */
1784 typedef struct @{ /* Win32 ASCII data structure */ @} WNDCLASS32A;
1785 typedef struct @{ /* Win32 Unicode data structure */ @} WNDCLASS32W;
1786 typedef struct @{ /* Win16 data structure */ @} WNDCLASS16;
1787 DECL_WINELIB_TYPE_AW(WNDCLASS);
1789 /* A function with strings */
1790 ATOM RegisterClass16( WNDCLASS16 * );
1791 ATOM RegisterClass32A( WNDCLASS32A * );
1792 ATOM RegisterClass32W( WNDCLASS32W * );
1793 #define RegisterClass WINELIB_NAME_AW(RegisterClass)
1796 The Winelib user can then say (in the application program):
1799 WNDCLASS wc = @{ @dots{} @};
1800 RegisterClass( &wc );
1802 and this will use the correct declaration depending on the definitions
1803 @code{WINELIB16}, @code{WINELIB32}, and @code{UNICODE}.
1805 Here are the primary defines that are used when Wine is compiled as a
1807 @defvr_cwine WINELIB16
1808 If this @code{#define} is set, the Wine library is to be compiled in its
1809 16 bit form. That means, the 16 bit variants of all functions will be
1810 used and the appearance of the application linked with the Wine library
1811 will be that of a 16 bit application. Of course, both the application
1812 and the Wine library function really run in 32 bit mode. The switch only
1813 selects the function with the name ending in @code{@dots{}16}, which
1814 will perhaps have a behaviour different from its 32 bit counterpart.
1816 @defvr_cwine WINELIB32
1817 If this @code{#define} is set, the Wine library is to be compiled in its
1818 32 bit form. That means, the 32 bit variants of all functions will be
1819 used and the appearance of the application linked with the Wine library
1820 will be that of a 32 bit application.
1822 @defvr_cwine UNICODE
1823 This @code{define} is used to select one of two possible 32 bit
1824 variants. Functions and data types of the 32 bit API come in two
1825 flavours: one handling @ascii{} strings (or rather strings with
1826 characters encoded in 8 bit), the other @unicode{} strings. This define
1827 selects the correct variant. As a user of the Wine library, you are
1828 responsible to use the correct character type in your part of the
1829 application which accesses the Wine API functions and data types.
1832 These switches are automatically set when Wine is compiled as a library.
1835 @node Access from inside Wine, , Access in the library, API function and type naming
1836 @subsection Accessing API functions from within Wine
1837 @cindex explicit names of API functions and types
1839 Within Wine and during the compilation of Wine, you cannot rely on the
1840 @mswindows{} names of the API functions and data types. If Wine is
1841 compiled as a library, they will be defined; if Wine is compiled as an
1842 emulator, they won't.
1844 You therefore have to access all functions and data types by their full
1845 names, with the proper suffix explicitely appended. In Wine, the 16 bit
1846 and 32 bit versions of the functions are distinct entities, which might
1847 (theoretically) show a completely different behaviour. They may even
1848 call each other (and they will quite frequently).
1850 Therefore Wine is a conglomerate that contains all two or
1851 three flavours of each function at once, and exports to the
1852 application whichever of these is appropriate. Remember that inside
1853 Wine, there is no memory segmentation, so all functions are 32 bit.
1854 The 16-to-32 bit mapping is done on exporting the DLL functions.
1857 @node Creating patches, Adding Documentation, API function and type naming, The Wine Project
1858 @section Creating patches
1859 @xref{Applying patches}, for instructions on applying patches.
1861 FIXME: how to create patches
1863 @node Adding Documentation, File names, Creating patches, The Wine Project
1864 @section Adding Documentation
1867 Here are some templates which should help you collaborate on this
1868 documentation. Read the text below before examining them.
1872 * Type Template:: How to document data types in Wine's
1874 * Function Template:: How to document an (API) function of
1879 These are my tips for adding documentation.
1881 Do not simply copy documentation from @mswindows{} related
1882 material. Except from risking copyright violations, which you would not
1883 want to do, there is another aspect to that:
1884 As Wine is a product to run on @unix{} and @unix{}-like workstations,
1885 it seems a good idea to me to organize this documentation primarily for
1886 the well-trained @unix{} reader. Please keep that in mind when you add
1889 Finally, read the info pages for @code{texinfo}.
1891 The rest of this section provides some templates which can serve as a
1892 start in writing documentation.
1894 @subsection Template introduction
1896 On the following pages you will find some @code{texinfo} templates, which
1897 should help you collaborate on this documentation.
1900 These templates give hints on how to document data types, functions,
1901 variables, constants etc. in Wine.
1902 As documentation evolves, you will find common features of data types
1903 that should be described in a unified fashion. In such a case, please
1904 add a corresponding style guide-line here, in this very place, to help
1905 keeping documentation of data types unified.
1908 Start out the type or function with a new node. Write a comment before
1909 the node, listing all data types (and functions) described in the node,
1913 @@c *** struct FILETIME ***
1915 @@node Type FILETIME, NextNodeName, PreviousNodeName, ParentNodeName
1918 The node command describes the node name and the names of the next node,
1919 the previous node, and the parent node. The parent node should contain
1920 a menu entry for this node. The previous node is the node that appears
1921 before this node in the parent node menu. The next node is the node
1922 succeeding this one in the parent node menu. If there is no previous or
1923 next node, omit the name (putting just a single space between the two
1926 The node name must be a unique sequence of words. Case is important, so
1927 @emph{Type} and @emph{type} are distinct. The node name must not contain
1928 special characters like @samp{@@, @{, @}} or the comma. If you need to
1929 give a node the same name as a function, data type, etc., use the words
1930 @samp{Type}, @samp{Function}, etc. before the identifier.
1932 Always put the names of the node and its links on the same line, even if
1933 it gets rather long.
1935 If there are two or more data types or functions described in the node,
1936 adapt the comment like this:
1940 @@c *** long Y() ***
1942 @@node Ints and Longs, NextNodeName, PreviousNodeName, ParentNodeName
1945 After the node name, put a sectioning command, such as @samp{@@chapter},
1946 @samp{@@section}, @samp{@@subsection}, or @samp{@@subsubsection}.
1947 Without that command, cross references to the node will fail.
1949 @@subsubsection Type FILETIME
1952 Start the description of the type(s) or function(s) with a single
1953 non-indented paragraph that gives a one-line description of the type(s)
1954 or function(s) and states the include files that are required.
1957 File times in Wine are specified by the data type @@code@{FILETIME@},
1958 defined in @@file@{windows.h@}.
1960 If several types or functions are closely connected, use one paragraph
1961 as a common description. If more paragraphs are required for a proper
1962 description, indent all but the first of them.
1964 Then start the definition of the data type or function. Use the proper
1965 macro, which you will find defined in the beginning of the texinfo file.
1966 If appropriate, add your own macros.
1967 Again, put everything that belongs to the header into a single line.
1968 Use continuation lines for additional headers.
1970 @@deftp_w32 FILETIME
1971 @@deftpx_w32 LPFILETIME
1974 In the definition, give a verbal explanation of the data type or
1975 function. The explanation should be rather complete, exact, and
1976 comprehensible, than well-structured. This is the point where you can
1977 tell everything you want. Do not be afraid of wasting space.
1978 Do not describe the @mswindows{} situation but only say what Wine
1979 does. That is important. (Sometimes they might even do the same.)
1981 This is the data type for specifying file times. The file times are
1982 stored with 64 bit precision. The actual data type is a structure with
1983 two 32 bit values which are interpreted as the low and high parts of a
1984 64-bit value. This value gives a time measured in a granularity of 100
1985 nanoseconds, so 1.5 seconds are specified by a value of 15,000,000. In
1986 Wine, this 64-bit value is signed, with the sign taken from the high
1987 part. The lower part is used as unsigned.
1990 For data types, it is recommended to quote the definition from the
1991 header file. For a function, you might give a short example of its
1992 usage. You may also put one example in the end of a node that explains
1993 several of the functions in the node. Remember that cut-and-paste from a
1994 well prepared example will help the readers write their code.
1996 The definition of @@code@{FILETIME@} reads:
2000 INT32 dwLowDateTime;
2001 INT32 dwHighDateTime;
2002 @@@} FILETIME, *LPFILETIME;
2006 You could also use the @code{cindex} command which creates an entry in
2007 the concept index. The @code{texinfo} manual recommends to keep concept
2008 entries distinct, so that a single concept index entry puts to one
2009 well-defined place in the document. Use lower case letters for index
2010 entries, unless they are proper names or quotes from actual code.
2012 @@cindex epoch in file time
2013 The @@code@{FILETIME@} structure may be used to hold absolute or relative
2014 times. Absolute times are given as the number of 100 nanoseconds
2015 intervals elapsed since 1 January 1601, 00:00:00 UTC (Coordinated
2016 Universal Time, which is GMT, Greenwich Mean Time). This might be
2017 called the @@dfn@{epoch@} for file times. With a signed 64-bit value, this
2018 representation covers absolute times of 29247 years around the epoch.
2021 After the verbal documentation, you can add some special fields
2022 describing bugs, implementation dependencies etc. Two of these are
2023 recommended to attach to all descriptions. One describes the
2024 conformance of the data type or function to @mswindows{} products,
2025 i.e. whether the item is also present in @WINNT{} and @WIN95{}. The
2026 other one describes known differences of the Wine item to its
2027 @mswindows{} counterpart. Both will greatly help in porting software
2028 from @mswindows{} to Wine and vice versa.
2033 In @@mswindows@{@}, the elements of the structure are apparently of type
2034 @@code@{DWORD@}. Whether the full 64 bit value is interpreted as signed or
2035 unsigned I do not know.
2038 If you find that more of these property attributes are necessary, feel
2039 free to create your own ones. But keep in mind that they should be
2040 applicable more or less to all described items. Very special properties
2041 will better be put into the verbal text.
2043 Finally end the definition of the data type or function:
2048 Do not forget to enter the node in the menu of its top node, and do
2049 properly link the node to its successor and predecessor.
2056 @node Type Template, Function Template, , Adding Documentation
2057 @subsection Data type template
2061 @node Function Template, , Type Template, Adding Documentation
2062 @subsection API function template
2064 Functions should be given category names, to indicate which API they
2065 belong to. Please add items to the list of categories possible.
2067 Category: WIN32 function
2071 @@c ***GetFileTime() ***
2073 @@node Get File Times, , Compare File Times, File Times
2075 The Wine function @@code@{GetFileTime@} returns the creation time and
2076 the times of last the read and modification access to a file. It is
2077 defined in @@file@{windows.h@}.
2079 @@deftypefn_w32 BOOL GetFileTime (@@w@{HANDLE @@var@{file@},@} @@w@{LPFILETIME @@var@{ctime@},@} @@w@{LPFILETIME @@var@{atime@},@} @@w@{LPFILETIME @@var@{mtime@})@}
2080 This function obtains for the specified @@var@{file@} the creation time
2081 @@var@{ctime@}, the time of the last access to the file @@var@{atime@}, and
2082 the time of the last modification (write) to the file, @@var@{mtime@}.
2083 The @@var@{file@} handle must have been obtained by opening the file with
2084 @@code@{GENERIC_READ@} access. The file time arguments of this function are
2085 pointers to @@code@{FILETIME@} variables, which are filled with a value that
2086 indicates an absolute time in UTC. To convert these values to local
2087 times, use the function @@code@{FileTimeToLocalFileTime@}. If you do not
2088 need some of the times, you can pass a @@code@{NULL@} pointer.
2089 The function returns @@code@{TRUE@} on success, @@code@{FALSE@} on failure.
2098 @node File names, Wide character strings, Adding Documentation, The Wine Project
2099 @section @mswindows{} and @unix{} file names in Wine
2100 @cindex file names in Wine
2101 @cindex Windows file names
2102 @cindex DOS file names in Wine
2103 @cindex UNIX file names in Wine
2104 @cindex POSIX file names in Wine
2108 @node Wide character strings, , File names, The Wine Project
2109 @section Wide character strings in API functions
2110 @cindex unicode strings in API functions
2111 @cindex wide character strings in API functions
2112 @cindex strings in API functions
2113 @cindex ascii strings in API functions
2114 @cindex 16 bit characters in API functions
2115 @cindex wchar_t in API functions
2117 Presently, all wide character strings in API functions of Wine are
2118 internally converted to 8 bit representation. Thus, the @WIN32{} API
2119 with @unicode{} strings is not fully functional for the application
2120 programmer at present.
2122 Even so, application programmers might consider developing their
2123 applications in wide character format with Wine, as future versions
2124 might bring a change. This might come when a @unix{} filesystem can
2125 handle @unicode{} file names.
2127 Furthermore, the @unicode{} API is required to let Wine run @mswindows{}
2128 applications which have been compiled for wide character strings.
2130 In Wine, wide characters are strictly 16 bit; the @code{wchar_t} type of
2131 standard C can therefore not be used.
2133 @node Concept Index, , , Top
2134 @comment node-name, next, previous, up
2135 @unnumbered Concept Index
2138 @node Type Index, , , Top
2139 @comment node-name, next, previous, up
2140 @unnumbered Type Index
2143 @node Function Index, , , Top
2144 @comment node-name, next, previous, up
2145 @unnumbered Function Index
2148 @node Variable Index, , , Top
2149 @comment node-name, next, previous, up
2150 @unnumbered Variable, Constants, and Variable-like Macros Index
2153 @node File Index, , , Top
2154 @comment node-name, next, previous, up
2155 @unnumbered File and Program Index