GetCPInfo should return FALSE if called with NULL info buffer.
[wine] / documentation / winedev-kernel.sgml
1   <chapter>
2     <title>Kernel modules</title>
3     <para>
4       This section covers the kernel modules.  As already stated, Wine
5       implements the NT architecture, hence provides <filename>NTDLL</filename>
6       for the core kernel functions, and <filename>KERNEL32</filename>, which is
7       the implementation of the basis of the Win32 subsystem, on top of
8       <filename>NTDLL</filename>.
9     </para>
10     <para>
11       This chapter is made of two types of material (depending of their point of
12       view).  Some items will be tackled from a global point of view and then,
13       when needed, explaining the split of work between
14       <filename>NTDLL</filename> and <filename>KERNEL32</filename>; some others
15       will be tackled from a DLL point of view (<filename>NTDLL</filename> or
16       <filename>KERNEL32</filename>).  The choice is made so that the output is
17       more readable and understantable.  At least, that's the intend (sigh).
18     </para>
19
20     <sect1 id="initialization">
21
22       <title>The Wine initialization process</title>
23
24       <para>
25         Wine has a rather complex startup procedure, so unlike many programs the
26         best place to begin exploring the code-base is
27         <emphasis>not</emphasis> in fact at the <function>main()</function>
28         function but instead at some of the  more straightforward DLLs that
29         exist on the periphery such as MSI, the widget library (in
30         <filename>USER</filename> and <filename>COMCTL32</filename>) etc. The
31         purpose of this section is to document and explain how Wine starts up
32         from the moment the user runs "<command>wine myprogram.exe</command>" to
33         the point at which <filename>myprogram</filename> gets control.
34       </para>
35
36       <sect2>
37         <title>First Steps</title>
38
39         <para>
40           The actual wine binary that the user runs does not do very much, in
41           fact it is only responsible for checking the threading model in use
42           (NPTL vs LinuxThreads) and then invoking a new binary which performs
43           the next stage in the startup sequence. See the beginning of this
44           chapter for more information on this check and why it's necessary. You
45           can find this code in <filename>loader/glibc.c</filename>. The result
46           of this check is an exec of either <command>wine-pthread</command> or
47           <command>wine-kthread</command>, potentially (on Linux) via the
48           <emphasis>preloader</emphasis>. We need to use separate binaries here
49           because overriding the native pthreads library requires us to exploit
50           a property of ELF symbol fixup semantics: it's not possible to do this
51           without starting a new process.
52         </para>
53
54         <para>
55           The Wine preloader is found in
56           <filename>loader/preloader.c</filename>, and is required in order to
57           impose a Win32 style address space layout upon the newly created Win32
58           process. The details of what this does is covered in the address space
59           layout chapter. The preloader is a statically linked ELF binary which
60           is passed the name of the actual Wine binary to run (either
61           <command>wine-kthread</command> or <command>wine-pthread</command>)
62           along with the arguments the user passed in from the command line. The
63           preloader is an unusual program: it does not have a
64           <function>main()</function> function. In standard ELF applications,
65           the entry point is actually at a symbol named
66           <function>_start()</function>: this is provided  by the
67           standard <command>gcc</command> infrastructure and normally jumps to
68           <function>__libc_start_main()</function> which initializes glibc before
69           passing control to the main function as defined by the programmer.
70         </para>
71
72         <para>
73           The preloader takes control direct from the entry point for a few
74           reasons. Firstly, it is required that glibc is not initialized twice:
75           the result of such behaviour is undefined and subject to change
76           without notice. Secondly, it's possible that as part of initializing
77           glibc, the address space layout could be changed - for instance, any
78           call to <function>malloc()</function> will initialize a heap arena
79           which modifies the VM mappings. Finally, glibc does not return to
80           <function>_start()</function> at any point, so by reusing it we avoid
81           the need to recreate the ELF bootstrap stack
82           (<varname>env</varname>, <varname>argv</varname>, auxiliary array etc).
83         </para>
84
85         <para>
86           The preloader is responsible for two things: protecting important
87           regions of the address space so the dynamic linker does not map shared
88           libraries into them, and once that is done loading the real Wine
89           binary off disk, linking it and starting it up. Normally all this is 
90           automatically by glibc and the kernel but as we intercepted this
91           process by using a static binary it's up to us to restart the
92           process. The bulk of the code in the preloader is about loading
93           <command>wine-[pk]thread</command> and
94           <filename>ld-linux.so.2</filename> off disk, linking them together,
95           then starting the dynamic linking process.
96         </para>
97
98         <para>
99           One of the last things the preloader does before jumping into the
100           dynamic linker is scan the symbol table of the loaded Wine binary and
101           set the value of a global variable directly: this is a more efficient
102           way of passing information to the main Wine program than flattening
103           the data structures into an environment variable or command line
104           parameter then unpacking it on the other side, but it achieves pretty
105           much the same thing. The global variable set points to the preload
106           descriptor table, which contains the VMA regions protected by the
107           preloader. This allows Wine to unmap them once the dynamic linker has
108           been run, so leaving gaps we can initialize properly later on.
109         </para>
110
111       </sect2>
112     
113       <sect2>
114         <title>Starting the emulator</title>
115
116         <para>
117           The process of starting up the emulator itself is mostly one of
118           chaining through various initializer functions defined in the core
119           libraries and DLLs: <filename>libwine</filename>, then
120           <filename>NTDLL</filename>, then <filename>KERNEL32</filename>.
121         </para>
122
123         <para>
124           Both the <command>wine-pthread</command> and
125           <command>wine-kthread</command> binaries share a common
126           <function>main()</function> function, defined in
127           <filename>loader/main.c</filename>, so no matter which binary is
128           selected after the preloader has run we start here. This passes the
129           information provided by the preloader into
130           <filename>libwine</filename> and then calls
131           <function>wine_init()</function>, defined in
132           <filename>libs/wine/loader.c</filename>. This is where the emulation
133           really starts: 
134           <function>wine_init()</function> can, with the correct preparation,
135           be called from programs other than the wine loader itself.
136         </para>
137
138         <para>
139           <function>wine_init()</function> does some very basic setup tasks such
140           as initializing the debugging infrastructure, yet more address space
141           manipulation (see the information on the 4G/4G VM split in the address
142           space chapter), before loading <filename>NTDLL</filename> - the core
143           of both Wine and the Windows NT series - and jumping to the
144           <function>__wine_process_init()</function> function defined
145           in <filename>dlls/ntdll/loader.c</filename>
146         </para>
147
148         <para>
149           This function is responsible for initializing the primary Win32
150           environment. In <function>thread_init()</function>, it sets up the
151           TEB, the <command>wineserver</command> connection for the main thread
152           and the process heap. See the beginning of this chapter for more
153           information on this.
154
155         </para>
156
157         <para>
158           Finally, it loads and jumps to
159           <function>__wine_kernel_init()</function> in
160           <filename>KERNEL32.DLL</filename>: this is defined in
161           <filename>dlls/kernel32/process.c</filename>. This is where the bulk
162           of the work is done. The <filename>KERNEL32</filename> initialization
163           code  retrieves the startup info for the process from the server,
164           initializes the registry, sets up the drive mapping system and locale
165           data, then begins loading the requested application itself. Each
166           process has a <structname>STARTUPINFO</structname> block that can be
167           passed into <function>CreateProcess</function> specifying various
168           things like how the first window should be displayed: this is sent to
169           the new process via the <command>wineserver</command>.
170         </para>
171
172         <para>
173           After determining the type of file given to Wine by the user (a Win32
174           EXE file, a Win16 EXE, a Winelib app etc), the program is loaded into
175           memory (which may involve loading and initializing other DLLs, the
176           bulk of Wines startup code), before control reaches the end of
177           <function>__wine_kernel_init()</function>. This function ends with the
178           new process stack being initialized, and start_process being called on
179           the new stack. Nearly there!
180         </para>
181
182         <para>
183           The final element of initializing Wine is starting the newly loaded
184           program itself. <function>start_process()</function> sets up the SEH
185           backstop handler, calls <function>LdrInitializeThunk()</function>
186           which performs the last part of the process initialization (such as
187           performing relocations and calling the <function>DllMain()</function>
188           with <constant>PROCESS_ATTACH</constant>), grabs the entry point of
189           the executable and then on this line:
190         </para>
191
192         <programlisting>
193 ExitProcess( entry( peb ) );
194         </programlisting>
195
196         <para>
197           ... jumps to the entry point of the program. At this point the users
198           program is running and the API provided by Wine is ready to be
199           used. When entry returns, the <function>ExitProcess()</function> API
200           will be used to initialize a graceful shutdown.
201         </para>
202       </sect2>
203     </sect1>
204
205     <sect1 id="threading">
206       <title>Multi-threading in Wine</title>
207
208       <para>
209         This section will assume you understand the basics of multithreading. If
210         not there are plenty of good tutorials available on the net to get you
211         started.
212       </para>
213
214       <para>
215         Threading in Wine is somewhat complex due to several factors. The first
216         is the advanced level of multithreading support provided by Windows -
217         there are far more threading related constructs available in Win32 than
218         the Linux equivalent (pthreads). The second is the need to be able to
219         map Win32 threads to native Linux threads which provides us with
220         benefits like having the kernel schedule them without our
221         intervention. While it's possible to implement threading entirely
222         without kernel support, doing so is not desirable on most platforms that
223         Wine runs on.
224       </para>
225
226       <sect2>
227         <title>Threading support in Win32</title>
228
229         <para>
230           Win32 is an unusually thread friendly API. Not only is it entirely
231           thread safe, but it provides many different facilities for working
232           with threads. These range from the basics such as starting and
233           stopping threads, to the extremely complex such as injecting threads
234           into other processes and COM inter-thread marshalling.
235         </para>
236
237         <para>
238           One of the primary challenges of writing Wine code therefore is
239           ensuring that all our DLLs are thread safe, free of race conditions
240           and so on. This isn't simple - don't be afraid to ask if you aren't
241           sure whether a piece of code is thread safe or not!
242         </para>
243
244         <para>
245           Win32 provides many different ways you can make your code thread safe
246           however the most common are <emphasis>critical section</emphasis> and
247           the <emphasis>interlocked functions</emphasis>. Critical sections are
248           a type of mutex designed to protect a geographic area of code. If you
249           don't want multiple threads running in a piece of code at once, you
250           can protect them with calls to
251           <function>EnterCriticalSection()</function> and
252           <function>LeaveCriticalSection()</function>. The first call to
253           <function>EnterCriticalSection()</function> by a thread will lock the
254           section and continue without stopping. If another thread calls it then
255           it will block until the original thread calls
256           <function>LeaveCriticalSection()</function> again.
257         </para>
258
259         <para>
260           It is therefore vitally important that if you use critical sections to
261           make some code thread-safe, that you check every possible codepath out
262           of the code to ensure that any held sections are left. Code like this:
263         </para>
264
265         <programlisting>
266 if (res != ERROR_SUCCESS) return res;
267         </programlisting>
268
269         <para>
270           is extremely suspect in a function that also contains a call to
271           <function>EnterCriticalSection()</function>. Be careful.
272         </para>
273
274         <para>
275           If a thread blocks while waiting for another thread to leave a
276           critical section, you will see an error from the
277           <function>RtlpWaitForCriticalSection()</function> function, along with
278           a note of which thread is holding the lock. This only appears after a
279           certain timeout, normally a few seconds. It's possible the thread
280           holding the lock is just being really slow which is why Wine won't
281           terminate the app like a non-checked build of Windows would, but the
282           most common cause is that for some reason a thread forgot to call
283           <function>LeaveCriticalSection()</function>, or died while holding the
284           lock (perhaps because it was in turn waiting for another lock). This
285           doesn't just happen in Wine code: a deadlock while waiting for a
286           critical section could be due to a bug in the app triggered by a
287           slight difference in the emulation.
288         </para>
289     
290         <para>
291           Another popular mechanism available is the use of functions like
292           <function>InterlockedIncrement()</function>
293           and <function>InterlockedExchange()</function>. These make use of native
294           CPU abilities to execute a single instruction while ensuring any other
295           processors on the system cannot access memory, and allow you to do
296           common operations like add/remove/check a variable in thread-safe code
297           without holding a mutex. These are useful for reference counting
298           especially in free-threaded (thread safe) COM objects.
299         </para>
300
301         <para>
302           Finally, the usage of TLS slots are also popular. TLS stands for
303           thread-local storage, and is a set of slots scoped local to a thread
304           which you can store pointers in. Look on MSDN for the
305           <function>TlsAlloc()</function> function to learn more about the Win32
306           implementation of this. Essentially, the contents of a given slot will
307           be different in each thread, so you can use this to store data that is
308           only meaningful in the context of a single thread. On recent versions
309           of Linux the __thread keyword provides a convenient interface to this
310           functionality - a more portable API is exposed in the pthread
311           library. However, these facilities are not used by Wine, rather, we
312           implement Win32 TLS entirely ourselves.
313         </para>
314       </sect2>
315
316       <sect2>
317         <title>SysLevels</title>
318
319         <para>
320           SysLevels are an undocumented Windows-internal thread-safety
321           system. They are basically critical sections which must be taken in a
322           particular order. The mechanism is generic but there are always three
323           syslevels: level 1 is the Win16 mutex, level 2 is the
324           <filename>USER</filename> mutex and level 3 is the
325           <filename>GDI</filename> mutex.
326         </para>
327
328         <para>
329           When entering a syslevel, the code (in
330           <filename>dlls/kernel/syslevel.c</filename>) will check that a higher
331           syslevel is not already held and produce an error if so. This is
332           because it's not legal to enter level 2 while holding level 3 - first,
333           you must leave level 3.
334         </para>
335
336         <para>
337           Throughout the code you may see calls to
338           <function>_ConfirmSysLevel()</function> and
339           <function>_CheckNotSysLevel()</function>. These functions are
340           essentially assertions about the syslevel states and can be used to
341           check that the rules have not been accidentally violated. In
342           particular, <function>_CheckNotSysLevel()</function> will break
343           probably into the debugger) if the check fails. If this happens the
344           solution is to get a backtrace and find out, by reading the source of
345           the wine functions called along the way, how Wine got into the invalid
346           state.
347         </para>
348       </sect2>
349
350       <sect2>
351         <title>POSIX threading vs. kernel threading</title>
352
353         <para>
354           Wine runs in one of two modes: either pthreads (posix threading) or
355           kthreads (kernel threading). This section explains the differences
356           between them. The one that is used is automatically selected on
357           startup by a small test program which then execs the correct binary,
358           either <command>wine-kthread</command> or 
359           <command>wine-pthread</command>. On NPTL-enabled systems pthreads
360           will be used, and on older non-NPTL systems kthreads is selected.
361         </para>
362
363         <para>
364           Let's start with a bit of history. Back in the dark ages when Wine's
365           threading support was first implemented a problem was faced - Windows
366           had much more capable threading APIs than Linux did. This presented a
367           problem - Wine works either by reimplementing an API entirely or by
368           mapping it onto the underlying systems equivalent. How could Win32
369           threading be implemented using a library which did not have all the
370           needed features? The answer, of course, was that it couldn't be.
371         </para>
372
373         <para>
374           On Linux the pthreads interface is used to start, stop and control
375           threads. The pthreads library in turn is based on top of so-called
376           "kernel threads" which are created using the
377           <function>clone(2)</function> syscall. Pthreads provides a nicer (more
378           portable) interface to this functionality and also provides APIs for
379           controlling mutexes. There is a <ulink
380             url="http://www.llnl.gov/computing/tutorials/pthreads/"> good
381             tutorial on pthreads</ulink> available if you want to learn more.
382         </para>
383
384         <para>
385           As pthreads did not provide the necessary semantics to implement Win32
386           threading, the decision was made to implement Win32 threading on top
387           of the underlying kernel threads by using syscalls like
388           <function>clone()</function> directly. This provided maximum
389           flexibility and allowed a correct implementation but caused some bad
390           side effects. Most notably, all the userland Linux APIs assumed that
391           the user was utilising the pthreads library. Some only enabled thread
392           safety when they detected that pthreads was in use - this is true of
393           glibc, for instance. Worse, pthreads and pure kernel threads had
394           strange interactions when run in the same process yet some libraries
395           used by Wine used pthreads internally. Throw in source code porting
396           using WineLib - where you have both UNIX and Win32 code in the same
397           process - and chaos was the result.
398         </para>
399
400         <para>
401           The solution was simple yet ingenious: Wine would provide its own
402           implementation of the pthread library <emphasis>inside</emphasis> its
403           own binary. Due to the semantics of ELF symbol scoping, this would
404           cause Wine's own implementation to override any implementation loaded
405           later on (like the real libpthread.so). Therefore, any calls to the
406           pthread APIs in external libraries would be linked to Wine's instead
407           of the system's pthreads library, and Wine implemented pthreads by
408           using the standard Windows threading APIs it in turn implemented
409           itself.
410         </para>
411
412         <para>
413           As a result, libraries that only became thread-safe in the presence of
414           a loaded pthreads implementation would now do so, and any external
415           code that used pthreads would actually end up creating Win32 threads
416           that Wine was aware of and controlled. This worked quite nicely for a
417           long time, even though it required doing some extremely un-kosher
418           things like overriding internal libc structures and functions. That
419           is, it worked until NPTL was developed at which point the underlying
420           thread implementation on Linux changed dramatically.
421         </para>
422
423         <para>
424           The fake pthread implementation can be found in
425           <filename>loader/kthread.c</filename>, which is used to
426           produce the <command>wine-kthread</command> binary. In contrast,
427           <filename>loader/pthread.c</filename> produces the
428           <command>wine-pthread</command> binary which is used on newer NPTL
429           systems.
430         </para>
431
432         <para>
433           NPTL is a new threading subsystem for Linux that hugely improves its
434           performance and flexibility. By allowing threads to become much more
435           scalable and adding new pthread APIs, NPTL made Linux competitive with
436           Windows in the multi-threaded world. Unfortunately it also broke many
437           assumptions made by Wine (as well as other applications such as the
438           Sun JVM and RealPlayer) in the process.
439         </para>
440
441         <para>
442           There was, however, some good news. NPTL made Linux threading powerful
443           enough that Win32 threads could now be implemented on top of pthreads
444           like any other normal application. There would no longer be problems
445           with mixing win32-kthreads and pthreads created by external libraries,
446           and no need to override glibc internals. As you can see from the
447           relative sizes of the <filename>loader/kthread.c</filename> and
448           <filename>loader/pthread.c</filename> files, the difference in code
449           complexity is considerable. NPTL also made several other semantic
450           changes to things such as signal delivery so changes were required in
451           many different places in Wine.
452         </para>
453
454         <para>
455           On non-Linux systems the threading interface is typically not powerful
456           enough to replicate the semantics Win32 applications expect and so
457           kthreads with the pthread overrides are used.
458         </para>
459       </sect2>
460
461       <sect2>
462         <title>The Win32 thread environment</title>
463
464         <para>
465           All Win32 code, whether from a native EXE/DLL or in Wine  itself,
466           expects certain constructs to be present in its environment. This
467           section explores what those constructs are and how Wine sets them
468           up. The lack of this environment is one thing that makes it hard to
469           use Wine code directly from standard Linux applications - in order to
470           interact with Win32 code a thread must first be
471           "adopted" by Wine.
472         </para>
473
474         <para>
475           The first thing Win32 code requires is the
476           <emphasis>TEB</emphasis> or "Thread Environment Block". This is an
477           internal (undocumented) Windows structure associated with every thread
478           which stores a variety of things such as TLS slots, a pointer to the
479           threads message queue, the last error code and so on. You can see the
480           definition of the TEB in <filename>include/thread.h</filename>, or at
481           least what we know of it so far. Being internal and subject to change,
482           the layout of the TEB has had to be reverse engineered from scratch.
483         </para>
484
485         <para>
486           A pointer to the TEB is stored in the %fs register and can be accessed
487           using <function>NtCurrentTeb()</function> from within Wine code. %fs
488           actually stores a selector, and setting it therefore requires
489           modifying the processes local descriptor table (LDT) - the code to do
490           this is in <filename>lib/wine/ldt.c</filename>. 
491         </para>
492
493         <para>
494           The TEB is required by nearly all Win32 code run in the Wine
495           environment, as any <command>wineserver</command> RPC will use it,
496           which in turn implies that any code which could possibly block for
497           instance by using a critical section) needs it. The TEB also holds the
498           SEH exception handler chain as the first element, so if disassembling
499           you see code like this:
500         </para>
501
502         <programlisting>movl %esp, %fs:0</programlisting>
503
504         <para>
505           ... then you are seeing the program set up an SEH handler frame. All
506           threads must have at least one SEH entry, which normally points to the
507           backstop handler which is ultimately responsible for popping up the
508           all-too-familiar  This program has performed an illegal operation and
509           will be terminated" message. On Wine we just drop straight into the
510           debugger. A full description of SEH is out of the scope of this
511           section, however there are some good articles in MSJ if you are
512           interested.
513         </para>
514
515         <para>
516           All Win32-aware threads must have a <command>wineserver</command>
517           connection. Many  different APIs require the ability to communicate
518           with the <command>wineserver</command>. In turn, the
519           <command>wineserver</command> must be aware of Win32 threads in order
520           to be able to accurately report information to other parts of the
521           program and do things like route inter-thread messages, dispatch APCs
522           (asynchronous procedure calls) and so on. Therefore a part of thread
523           initialization is initializing the thread server-side. The result is
524           not only correct information in the server, but a set of file
525           descriptors the thread can use to communicate with the server - the
526           request fd, reply fd and wait fd (used for blocking).
527         </para>
528       </sect2>
529     </sect1>
530
531     <sect1 id="seh">
532       <title>Structured Exception Handling</title>
533       
534       <para>
535         Structured Exception Handling (or SEH) is an implementation of
536         exceptions inside the Windows core. It allows code written in different
537         languages to throw exceptions across DLL boundaries, and Windows reports
538         various errors like access violations by throwing them. This section
539         looks at how it works, and how it's implemented in Wine.
540       </para>
541
542       <sect2>
543         <title>How SEH works</title>
544
545         <para>
546           SEH is based on embedding
547           <structname>EXCEPTION_REGISTRATION_RECORD</structname> structures in
548           the stack. Together they form a linked list rooted at offset zero in
549           the TEB (see the threading section if you don't know what this is). A
550           registration record points to a handler function, and when an
551           exception is thrown the handlers are executed in turn. Each handler
552           returns a code, and they can elect to either continue through the
553           handler chain or it can handle the exception and then restart the
554           program. This is referred to as unwinding the stack. After each
555           handler is called it's popped off the chain.
556         </para>
557
558         <para>
559           Before the system begins unwinding the stack, it runs vectored
560           handlers. This is an extension to SEH available in Windows XP, and
561           allows registered functions to get a first chance to watch or deal
562           with any exceptions thrown in the entire program, from any thread.
563         </para>
564
565         <para>
566           A thrown exception is represented by an
567           <structname>EXCEPTION_RECORD</structname> structure. It consists of a
568           code, flags, an address and an arbitrary number of <type>DWORD</type>
569           parameters. Language runtimes can use these parameters to associate
570           language-specific information with the exception.
571         </para>
572         
573         <para>
574           Exceptions can be triggered by many things. They can be thrown
575           explicitly by using the RaiseException API, or they can be triggered
576           by a crash (ie, translated from a signal). They may be used internally
577           by a language runtime to implement language-specific exceptions. They
578           can also be thrown across DCOM connections.
579         </para>
580
581         <para>
582           Visual C++ has various extensions to SEH which it uses to implement,
583           eg, object destruction on stack unwind as well as the ability to throw
584           arbitrary types. The code for this is in
585           <filename>dlls/msvcrt/except.c</filename>
586         </para>
587
588       </sect2>
589       
590       <sect2>
591         <title>Translating signals to exceptions</title>
592
593         <para>
594           In Windows, compilers are expected to use the system exception
595           interface, and the kernel itself uses the same interface to
596           dynamically insert exceptions into a running program. By contrast on
597           Linux the exception ABI is implemented at the compiler level
598           (inside GCC and the linker) and the kernel tells a thread of
599           exceptional events by sending <emphasis>signals</emphasis>. The
600           language runtime may or may not translate these signals into native
601           exceptions, but whatever happens the kernel does not care.
602         </para>
603
604         <para>
605           You may think that if an app crashes, it's game over and it really
606           shouldn't matter how Wine handles this. It's what you might
607           intuitively guess, but you'd be wrong. In fact some Windows programs
608           expect to be able to crash themselves and recover later without the
609           user noticing, some contain buggy binary-only components from third
610           parties and use SEH to swallow crashes, and still others execute
611           priviledged (kernel-level) instructions and expect it to work. In
612           fact, at least one set of APIs (the <function>IsBad*Ptr()</function>
613           series) can only be implemented by performing an operation that may
614           crash and returning <constant>TRUE</constant> if it does, and
615           <constant>FALSE</constant> if it doesn't! So, Wine needs to not only
616           implement the SEH infrastructure but also translate Unix signals into
617           SEH exceptions.
618         </para>
619
620         <para>
621           The code to translate signals into exceptions is a part of
622           <filename>NTDLL</filename>, and can be found in
623           <filename>dlls/ntdll/signal_i386.c</filename>. This file sets up
624           handlers for various signals during Wine startup, and for the ones
625           that indicate exceptional conditions translates them into
626           exceptions. Some signals are used by Wine internally and have nothing
627           to do with SEH.
628         </para>
629
630         <para>
631           Signal handlers in Wine run on their own stack. Each thread has its
632           own signal stack which resides 4k after the TEB. This is important for
633           a couple of reasons. Firstly, because there's no guarantee that the
634           app thread which triggered the signal has enough stack space for the
635           Wine signal handling code. In Windows, if a thread hits the limits of
636           its stack it triggers a fault on the stack guard page. The language
637           runtime can use this to grow the stack if it wants to.
638
639           <!-- fixme: is it really the language runtime that does this? i
640                can't find any code in Wine to reallocate the stack on
641                STATUS_GUARD_PAGE_VIOLATION -->
642
643           However, because a guard page violation is just a regular segfault to
644           the kernel, that would lead to a nested signal handler and that gets
645           messy really quick so we disallow that in Wine. Secondly, setting up
646           the exception to throw requires modifying the stack of the thread
647           which triggered it, which is quite hard to do when you're still
648           running on it.
649         </para>
650
651         <para>
652           Windows exceptions typically contain more information than the Unix
653           standard APIs provide. For instance, a
654           <constant>STATUS_ACCESS_VIOLATION</constant> exception (0xC0000005)
655           structure contains the faulting address, whereas a standard Unix
656           SIGSEGV just tells the app that it crashed. Usually this information
657           is passed as an extra parameter to the signal handler, however its
658           location and contents vary between kernels (BSD, Solaris,
659           etc). This data is provided in a <structname>SIGCONTEXT</structname>
660           structure, and on entry to the signal handler it contains the register
661           state of the CPU before the signal was sent. Modifying it will cause
662           the kernel to adjust the context before restarting the thread.
663         </para>
664       </sect2>
665     </sect1>
666
667     <sect1>
668       <title>File management</title>
669       <para>
670         With time, Windows API comes closer to the old Unix paradigm "Everything
671         is a file".  Therefore, this whole section dedicated to file management
672         will cover firstly the file management, but also some other objects like
673         directories, and even devices, which are manipulated in Windows in a
674         rather coherent way.  We'll see later on some other objects fitting
675         (more or less) in this picture (pipes or consoles to name a few).
676       </para>
677
678       <para>
679         First of all, Wine, while implementing the file interface from Windows,
680         needs to maps a file name (expressed in the Windows world) onto a file
681         name in the Unix world.  This encompasses several aspects: how to map
682         the file names, how to map access rights (both on files and
683         directories), how to map physical devices (hardisks, but also other
684         devices - like serial or parallel interfaces - and even VxDs).
685       </para>
686
687       <sect2>
688         <title>Various Windows formats for file names</title>
689         <para>
690           Let's first review a bit the various forms Windows uses when it comes
691           to file names.
692         </para>
693         
694         <sect3>
695           <title>The DOS inheritance</title>
696
697           <para>
698             At the beginning was DOS, where each file has to sit on a drive,
699             called from a single letter.  For separating device names from
700             directory or file names, a ':' was appended to this single letter,
701             hence giving the (in)-famous <filename>C:</filename> drive
702             designations.  Another great invention was to use some fixed names
703             for accessing devices: not only where these named fixed, in a way
704             you couldn't change the name if you'd wish to, but also, they were
705             insensible to the location where you were using them.  For example,
706             it's well known that <filename>COM1</filename> designates the first
707             serial port, but it's also true that
708             <filename>c:\foo\bar\com1</filename> also designates the first
709             serial port.  It's still true today: on XP, you still cannot name a
710             file <filename>COM1</filename>, whatever the directory!!!
711           </para>
712           <para>
713             Well later on (with Windows 95), Microsoft decided to overcome some
714             little details in file names: this included being able to get out of
715             the 8+3 format (8 letters for the name, 3 letters for the
716             extension), and so being able to use "long names" (that's the
717             "official" naming; as you can guess, the 8+3 format is a short
718             name), and also to use very strange characters in a file name (like
719             a space, or even a '.').  You could then name a file
720             <filename>My File V0.1.txt</filename>, instead of
721             <filename>myfile01.txt</filename>.  Just to keep on the fun side of
722             things, for many years the format used on the disk itself for
723             storing the names has been the short name as the real one and to use
724             some tricky aliasing techniques to store the long name.  When some
725             newer disk file systems have been introduced (NTFS with NT), in
726             replacement of the old FAT system (which had little evolved since
727             the first days of DOS), the long name became the real name while the
728             short name took the alias role.
729           </para>
730           <para>
731             Windows also started to support mounting network shares, and see
732             them as they were a local disk (through a specific drive letter).
733             The way it has been done changed along the years, so we won't go
734             into all the details (especially on the DOS and Win9x side).
735           </para>
736         </sect3>
737
738         <sect3>
739           <title>The NT way</title>
740           <para>
741             The introduction of NT allowed a deep change in the ways DOS had
742             been handling devices:
743             <itemizedlist>
744               <listitem>
745                 <para>
746                   There's no longer a forest of DOS drive letters (even if the
747                   <command>assign</command> was a way to create symbolic links
748                   in the forest), but a single hierarchical space.
749                 </para>
750               </listitem>
751               <listitem>
752                 <para>
753                   This hierarchy includes several distinct elements.  For
754                   example, <filename>\Device\Hardisk0\Partition0</filename>
755                   refers to the first partition on the first physical hard disk
756                   of the system.
757                 </para>
758               </listitem>
759               <listitem>
760                 <para>
761                   This hierarchy covers way more than just the files and drives
762                   related objects, but most of the objects in the system.  We'll
763                   only cover here the file related part.
764                 </para>
765               </listitem>
766               <listitem>
767                 <para>
768                   This hierarchy is not directly accessible for the Win32 API,
769                   but only the <filename>NTDLL</filename> API.  The Win32 API
770                   only allows to manipulate part of this hierarchy (the rest
771                   being hidden from the Win32 API). Of course, the part you see
772                   from Win32 API looks very similar to the one that DOS
773                   provided.
774                 </para>
775               </listitem>
776               <listitem>
777                 <para>
778                   Mounting a disk is performed by creating a symbol link in this
779                   hierarchy from <filename>\Global??\C:</filename> (the name
780                   seen from the Win32 API) to
781                   <filename>\Device\Harddiskvolume1</filename> which determines
782                   the partition on a physical disk where C: is going to be seen.
783                 </para>
784               </listitem>
785               <listitem>
786                 <para>
787                   Network shares are also accessible through a symbol link.
788                   However in this case, a symbol link is created from 
789                   <filename>\Global??\UNC\host\share\</filename> for the share
790                   <filename>share</filename> on the machine
791                   <filename>host</filename>) to what's called a network
792                   redirector, and which will take care of 1/ the connection to
793                   the remote share, 2/ handling with that remote share the rest
794                   of the path (after the name of the server, and the name of the
795                   share on that server).
796                 </para>
797                 <note>
798                   <para>
799                     In NT naming convention, <filename>\Global??</filename> can
800                     also be called <filename>\??</filename> to shorten the
801                     access.
802                   </para>
803                 </note>
804               </listitem>
805             </itemizedlist>
806           </para>
807           <para>
808             All of these things, make the NT system pretty much more flexible
809             (you can add new types of filesystems if you want), you provide a
810             unique name space for all objects, and most operations boil down to
811             creating relationship between different objects.
812           </para>
813         </sect3>
814
815         <sect3>
816           <title>Wrap up</title>
817           <para>
818             Let's end this chapter about files in Windows with a review of the
819             different formats used for file names:
820             <itemizedlist>
821               <listitem>
822                 <para><filename>c:\foo\bar</filename> is a full path.</para>
823               </listitem>
824               <listitem>
825                 <para>
826                   <filename>\foo\bar</filename> is an absolute path; the full
827                   path is created by appending the default drive (ie. the drive
828                   of the current directory).
829                 </para>
830               </listitem>
831               <listitem>
832                 <para>
833                   <filename>bar</filename> is a relative path; the full path is
834                   created by adding the current directory.
835                 </para>
836               </listitem>
837               <listitem>
838                 <para>
839                   <filename>c:bar</filename> is a drive relative path.  Note
840                   that the case where <filename>c:</filename> is the drive of
841                   the current directory is rather easy; it's implemented the
842                   same way as the case just below (relative path). In the rest
843                   of this chapter, drive relative path will only cover the case
844                   where the drive in the path isn't the drive of the default
845                   directory.  The resolution of this to a full pathname defers
846                   according to the version of Windows, and some parameters.
847                   Let's take some time browsing through these issues.  On
848                   Windows 9x (as well as on DOS), the system maintains a process
849                   wide set of default directories per drive.  Hence, in this
850                   case, it will resolve <filename>c:bar</filename> to the
851                   default directory on drive <filename>c:</filename> plus file
852                   <filename>bar</filename>.  Of course, the default per drive
853                   directory is updated each time a new current directory is set
854                   (only the current directory of the drive specified is
855                   modified).  On Windows NT, things differ a bit.  Since NT
856                   implements a namespace for file closer to a single tree
857                   (instead of 26 drives), having a current directory per drive
858                   is a bit ackward.  Hence, Windows NT default behavior is to
859                   have only one current directory across all drives (in fact, a
860                   current directory expressed in the global tree) - this
861                   directory is of course related to a given process -,
862                   <filename>c:bar</filename> is resolved this way:
863                   <itemizedlist>
864                     <listitem>
865                       <para>
866                         If <filename>c:</filename> is the drive of the default
867                         directory, the final path is the current directory plus
868                         <filename>bar</filename>.
869                       </para>
870                     </listitem>
871                     <listitem>
872                       <para>
873                         Otherwise it's resolved into
874                         <filename>c:\bar</filename>.
875                       </para>
876                     </listitem>
877                     <listitem>
878                       <para>
879                         In order to bridge the gap between the two
880                         implementations (Windows 9x and NT), NT adds a bit of
881                         complexity on the second case.  If the
882                         <envar>=C:</envar> environment variable is defined, then
883                         it's value is used as a default directory for drive
884                         <filename>C:</filename>.  This is handy, for example,
885                         when writing a DOS shell, where having a current drive
886                         per drive is still implemented, even on NT.  This
887                         mechanism (through environment variables) is implemented
888                         on <command>CMD.EXE</command>, where those variables are
889                         set when you change directories with the
890                         <command>cd</command>.  Since environment variables are
891                         inherited at process creation, the current directories
892                         settings are inherited by child processes, hence
893                         mimicing the behavior of the old DOS shell.  There's no
894                         mechanism (in <filename>NTDLL</filename> or
895                         <filename>KERNEL32</filename>) to set up, when current
896                         directory changes, the relevant environment variables.
897                         This behavior is clearly band-aid, not a full featured
898                         extension of current directory behavior.
899                       </para>
900                     </listitem>
901                   </itemizedlist>
902                   Wine fully implements all those behaviors (the Windows 9x vs
903                   NT ones are triggered by the version flag in Wine).
904                 </para>
905               </listitem>
906               <listitem>
907                 <para>
908                   <filename>\\host\share</filename> is <firstterm>UNC</firstterm>
909                   (Universal Naming Convention) path, ie. represents a file on a
910                   remote share.
911                 </para>
912               </listitem>
913               <listitem>
914                 <para>
915                   <filename>\\.\device</filename> denotes a physical device
916                   installed in the system (as seen from the Win32 subsystem).  A
917                   standard NT system will map it to the
918                   <filename>\??\device</filename> NT path.  Then, as a standard
919                   configuration, <filename>\??\device</filename> is likely to be
920                   a link to in a physical device described and hooked into the
921                   <filename>\Device\</filename> tree.  For example,
922                   <filename>COM1</filename> is a link to
923                   <filename>\Device\Serial0</filename>.
924                 </para>
925               </listitem>
926               <listitem>
927                 <para>
928                   On some versions of Windows, paths were limited to
929                   <constant>MAX_PATH</constant> characters.  To circumvent this,
930                   Microsoft allowed paths to be <constant>32,767</constant>
931                   characters long, under the conditions that the path is
932                   expressed in Unicode (no Ansi version), and that the path is
933                   prefixed with <filename>\\?\</filename>.  This convention is
934                   applicable to any of the cases described above.
935                 </para>
936               </listitem>
937             </itemizedlist>
938           </para>
939           <para>
940             To summarize, what we've discussed so, let's put everything into a
941             single table...
942             <table>
943               <title>DOS, Win32 and NT paths equivalences</title>
944               <tgroup cols="3" align="left">
945                 <thead>
946                   <row>
947                     <entry>Type of path</entry>
948                     <entry>Win32 example</entry>
949                     <entry>NT equivalent</entry>
950                     <entry>Rule to construct</entry>
951                   </row>
952                 </thead>
953                 <tbody>
954                   <row>
955                     <entry>Full path</entry>
956                     <entry><filename>c:\foo\bar.txt</filename></entry>
957                     <entry><filename>\Global??\C:\foo\bar.txt</filename></entry>
958                     <entry>Simple concatenation</entry>
959                   </row>
960                   <row>
961                     <entry>Absolute path</entry>
962                     <entry><filename>\foo\bar.txt</filename></entry>
963                     <entry><filename>\Global??\J:\foo\bar.txt</filename></entry>
964                     <entry>
965                       Simple concatenation using the drive of the default
966                       directory (here J:)
967                     </entry>
968                   </row>
969                   <row>
970                     <entry>Relative path</entry>
971                     <entry><filename>gee\bar.txt</filename></entry>
972                     <entry>
973                       <filename>
974                         \Global??\J:\mydir\mysubdir\gee\bar.txt
975                       </filename>
976                     </entry>
977                     <entry>
978                       Simple concatenation using the default directory
979                       (here <filename>J:\mydir\mysubdir</filename>)
980                     </entry>
981                   </row>
982                   <row>
983                     <entry>Drive relative path</entry>
984                     <entry><filename>j:gee\bar.txt</filename></entry>
985                     <entry>
986                       <msgtext>
987                         <para>
988                           <itemizedlist>
989                             <listitem>
990                               <para>
991                                 On Windows 9x (and DOS),
992                                 <filename>J:\toto\gee\bar.txt</filename>.
993                               </para>
994                             </listitem>
995                             <listitem>
996                               <para>
997                                 On Windows NT,
998                                 <filename>J:\gee\bar.txt</filename>.
999                               </para>
1000                             </listitem>
1001                             <listitem>
1002                               <para>
1003                                 On Windows NT,
1004                                 <filename>J:\tata\titi\bar.txt</filename>.
1005                               </para>
1006                             </listitem>
1007                           </itemizedlist>
1008                         </para>
1009                       </msgtext>
1010                     </entry>
1011                     <entry>
1012                     <msgtext>
1013                         <para>
1014                           <itemizedlist>
1015                             <listitem>
1016                               <para>
1017                                 On Windows NT (and DOS),
1018                                 <filename>\toto</filename> is the default
1019                                 directory on drive <filename>J:</filename>.
1020                               </para>
1021                             </listitem>
1022                             <listitem>
1023                               <para>
1024                                 On Windows NT, if <envar>=J:</envar> isn't set.
1025                               </para>
1026                             </listitem>
1027                             <listitem>
1028                               <para>
1029                                 On Windows NT, if <envar>=J:</envar> is set to
1030                                 <filename>J:\tata\titi</filename>.
1031                               </para>
1032                             </listitem>
1033                           </itemizedlist>
1034                         </para>
1035                       </msgtext>
1036                     </entry>
1037                   </row>
1038                   <row>
1039                     <entry>UNC (Uniform Naming Convention) path</entry>
1040                     <entry><filename>\\host\share\foo\bar.txt</filename></entry>
1041                     <entry>
1042                       <filename>\Global??\UNC\host\share\foo\bar.txt</filename>
1043                     </entry>
1044                     <entry>
1045                       Simple concatenation.
1046                     </entry>
1047                   </row>
1048                   <row>
1049                     <entry>Device path</entry>
1050                     <entry><filename>\\.\device</filename></entry>
1051                     <entry><filename>\Global??\device</filename></entry>
1052                     <entry>Simple concatenation</entry>
1053                   </row>
1054                   <row>
1055                     <entry>Long paths</entry>
1056                     <entry><filename>\\?\...</filename></entry>
1057                     <entry></entry>
1058                     <entry>
1059                       With this prefix, paths can take up to
1060                       <constant>32,767</constant> characters, instead of
1061                       <constant>MAX_PATH</constant> for all the others).  Once
1062                       the prefix stripped, to be handled like one of the
1063                       previous ones, just providing internal buffers large
1064                       enough).
1065                     </entry>
1066                   </row>
1067                 </tbody>
1068               </tgroup>
1069             </table>
1070           </para>
1071         </sect3>
1072       </sect2>
1073       
1074       <sect2>
1075         <title>Wine implementation</title>
1076         <para>
1077           We'll mainly cover in this section the way Wine opens a file (in the
1078           Unix sense) when given a Windows file name.  This will include mapping
1079           the Windows path onto a Unix path (including the devices case),
1080           handling the access rights, the sharing attribute if any...  
1081         </para>
1082         <sect3>
1083           <title>Mapping a Windows path into an absolute Windows path</title>
1084           <para>
1085             First of all, we described in previous section the way to convert
1086             any path in an absolute path.  Wine implements all the previous algorithms
1087             in order to achieve this.  Note also, that this transformation is
1088             done with information local to the process (default directory,
1089             environment variables...).  We'll assume in the rest of this section
1090             that all paths have now been transformed into absolute from.
1091           </para>
1092         </sect3>
1093         <sect3>
1094           <title>Mapping a Windows (absolute) path onto a Unix path</title>
1095           <para>
1096             When Wine is requested to map a path name (in DOS form, with a drive
1097             letter, e.g. <filename>c:\foo\bar\myfile.txt</filename>), Wine
1098             converts this into the following Unix path
1099             <filename>$(WINEPREFIX)/dosdevices/c:/foo/bar/myfile.txt</filename>.
1100             The Wine configuration process is responsible for setting
1101             <filename>$(WINEPREFIX)/dosdevices/c:</filename> to be a symbolic
1102             link pointing to the directory in Unix hierarchy the user wants to
1103             expose as the <filename>C:</filename> drive in the DOS forest of
1104             drives.  
1105           </para>
1106           <para>
1107             This scheme allows:
1108             <itemizedlist>
1109               <listitem>
1110                 <para>
1111                   a very simple algorithm to map a DOS path name into a Unix one
1112                   (no need of Wine server calls) 
1113                 </para>
1114               </listitem>
1115               <listitem>
1116                 <para>
1117                   a very configurable implementation: it's very easy to change a
1118                   drive mapping 
1119                 </para>
1120               </listitem>
1121               <listitem>
1122                 <para>
1123                   a rather readable configuration: no need of sophisticated
1124                   tools to read a drive mapping, a <command>ls -l
1125                    $(WINEPREFIX)/dosdevices</command> 
1126                   says it all.
1127                 </para>
1128               </listitem>
1129             </itemizedlist>
1130           </para>
1131           <para>
1132             This scheme is also used to implement UNC path names.  For example,
1133             Wine maps <filename>\\host\share\foo\bar\MyRemoteFile.txt</filename>
1134             into 
1135             <filename>$(WINEPREFIX)/dosdevices/unc/host/share/foo/bar/MyRemoteFile.txt</filename>.
1136             It's then up to the user to decide where
1137             <filename>$(WINEPREFIX)/dosdevices/unc/host/share</filename> shall
1138             point to (or be).  For example, it can either be a symbolic link to a
1139             directory inside the local machine (just for emulation purpose), or
1140             a symbolic link to the mount point of a remote disk (done through
1141             Samba or NFS), or even the real mount point.  Wine will not do any
1142             checking here, nor will help in actually mounting the remote drive.
1143           </para>
1144           <para>
1145             We've seen how Wine maps a drive letter or a UNC path onto the Unix
1146             hierarchy, we now have to look on a the filename is searched within
1147             this hierarchy.  The main issue is about case sensivity.  Here's a
1148             reminder of the various properties for the file systems in the
1149             field.
1150             <table>
1151               <title>File systems' properties</title>
1152               <tgroup cols="4" align="left">
1153                 <thead>
1154                   <row>
1155                     <entry>FS Name</entry>
1156                     <entry>Length of elements</entry>
1157                     <entry>Case sensitivity (on disk)</entry>
1158                     <entry>Case sensitivity for lookup</entry>
1159                   </row>
1160                 </thead>
1161                 <tbody>
1162                   <row>
1163                     <entry>FAT, FAT16 or FAT32</entry>
1164                     <entry>Short name (8+3)</entry>
1165                     <entry>Names are always stored in upper-case</entry> 
1166                     <entry>Case insensitive</entry>
1167                   </row>
1168                   <row>
1169                     <entry>VFAT</entry>
1170                     <entry>Short name (8+3) + alias on long name</entry> 
1171                     <entry>
1172                       Short names are always stored in upper-case.  Long names
1173                       are stored with case preservation.
1174                     </entry>
1175                     <entry>Case insensitive</entry>
1176                   </row>
1177                   <row>
1178                     <entry>NTFS</entry>
1179                     <entry>Long name + alias on short name (8+3).</entry>
1180                     <entry>
1181                       Long names are stored with case preservation.  Short names
1182                       are always stored in upper-case.
1183                     </entry>
1184                     <entry>Case insentivite</entry>
1185                   </row>
1186                   <row>
1187                     <entry>Linux FS (ext2fs, ext3fs, reiserfs...)</entry>
1188                     <entry>Long name</entry>
1189                     <entry>Case preserving</entry>
1190                     <entry>Case sensitive</entry>
1191                   </row>
1192                 </tbody>
1193               </tgroup>
1194             </table>
1195           </para>
1196           <para>
1197             <note>
1198               <para>
1199                 When we say that most systems in NT are case insensitive, this
1200                 has to be understood for looking up for a file, where the
1201                 matches are made in a case insensitive mode.  This is different
1202                 from VFAT or NTFS "case preservation" mechanism, which stores
1203                 the file names as they are given when creating the file, while
1204                 doing case insensitive matches.
1205               </para>
1206             </note>
1207             Since most file systems used in NT are case insensitive and since
1208             most Unix file systems are case sensitive, Wine undergo a case
1209             insensitive search when it has found the Unix path is has to look
1210             for.  This means, for example, that for opening the
1211             <filename>$(WINEPREFIX)/dosdevices/c:/foo/bar/myfile.txt</filename>,
1212             Wine will recursively open all directories in the path, and check,
1213             in this order, for the existence of the directory entry in the form
1214             given in the file name (ie. case sensitive), and if it's not found,
1215             in a case insensitive form.  This allows to also pass, in most Win32
1216             file API also a Unix path (instead of a DOS or NT path), but we'll
1217             come back to this later.  This also means that the algorithm
1218             described doesn't correctly handle the case of two files in the same
1219             directory, which names only differ on the case of the letters.  This
1220             means, that if, in the same directory, two files (which names match
1221             in a case sensitive comparison), Wine will pick-up the right one if
1222             the filename given matches on of the name (in a case sensitive way),
1223             but will pickup one of the two (without defining the one it's going
1224             to pickup) if the filename given matches none of the two names in a
1225             case sensitive way (but in a case insensitive way).  For example, if
1226             the two filenames are <filename>my_neat_file.txt</filename> and
1227             <filename>My_Neat_File.txt</filename>, Wine's behavior when opening
1228             <filename>MY_neat_FILE.txt</filename> is undefined.
1229           </para>
1230           <para>
1231             As Windows, at the early days, didn't support the notion of symbolic
1232             links on directories, lots of applications (and some old native
1233             DLLs) are not ready for this feature.  Mainly, they imply that the
1234             directory structure is a tree, which has lots of consequences on
1235             navigating in the forest of directories (ie: there cannot be two
1236             ways for going from directory to another, there cannot be
1237             cycles...).  In order to prevent some bad behavior for such
1238             applications, Wine sets up an option.  By default, symbolic links on
1239             directories are not followed by Wine.  There's an options to follow
1240             them (see the Wine User Guide), but this could be harmful.
1241           </para>
1242           <para>
1243             Wine considers that Unix file names <emphasis>are</emphasis> long
1244             filename.  This seems a reasonable approach; this is also the
1245             approach followed by most of the Unix OSes while mounting Windows
1246             partitions (with filesystems like FAT, FAT32 or NTFS).  Therefore,
1247             Wine tries to support short names the best it can.  Basically, they
1248             are two options:
1249             <itemizedlist>
1250               <listitem>
1251                 <para>
1252                   The filesystem on which the inspected directory lies in a real
1253                   Windows FS (like FAT, or FAT32, or NTFS) and the OS has
1254                   support to access the short filename (for example, Linux does
1255                   this on FAT, FAT32 or VFAT).  In this case, Wine makes full use
1256                   of this information and really mimics the Windows behavior:
1257                   the short filename used for any file is the same than on
1258                   Windows.
1259                 </para>
1260               </listitem>
1261               <listitem>
1262                 <para>
1263                   If conditions listed above are not met (either, FS has no
1264                   physical short name support, or OS doesn't provide the access
1265                   access to the short name), Wine decides and computes on its
1266                   own the short filename for a given long filename.  We cannot
1267                   ensure that the generated short name is the same than on
1268                   Windows (because the algorithm on Windows takes into account
1269                   the order of creation of files, which cannot be implemented in
1270                   Wine: Wine would have to cache the short names of every
1271                   directory it uses!).  The short name is made up of part of the
1272                   long name (first characters) and the rest with a hashed
1273                   value.  This has several advantages:
1274                   <itemizedlist>
1275                     <listitem>
1276                       <para>
1277                         The algorithm is rather simple and low cost.
1278                       </para>
1279                     </listitem>
1280                     <listitem>
1281                       <para>
1282                         The algorithm is stateless (doesn't depend of the other
1283                         files in the directory).
1284                       </para>
1285                     </listitem>
1286                   </itemizedlist>
1287                   But, it also has the drawbacks (of the advantages):
1288                   <itemizedlist>
1289                     <listitem>
1290                       <para>
1291                         The algorithm isn't the same as on Windows, which means
1292                         a program cannot use short names generated on
1293                         Windows.  This could happen when copying an existing
1294                         installed program from Windows (for example, on a dual
1295                         boot machine).
1296                       </para>
1297                     </listitem>
1298                     <listitem>
1299                       <para>
1300                         Two long file names can end up with the same short name
1301                         (Windows handles the collision in this case, while Wine
1302                         doesn't).  We rely on our hash algorithm to lower at most
1303                         this possibility (even if it exists).
1304                       </para>
1305                     </listitem>
1306                   </itemizedlist>
1307                 </para>
1308               </listitem>
1309             </itemizedlist>
1310           </para>
1311           <para>
1312             Wine also allows in most file API to give as a parameter a full Unix
1313             path name.  This is handy when running a Wine (or Winelib) program
1314             from the command line, and one doesn't need to convert the path into
1315             the Windows form.  However, Wine checks that the Unix path given can
1316             be accessed from one of the defined drives, insuring that only part
1317             of the Unix <filename>/</filename> hierarchy can be accessed.
1318           </para>
1319           <para>
1320             As a side note, as Unix doesn't widely provide a Unicode interface
1321             to the filenames, and that Windows implements filenames as Unicode
1322             strings (even on the physical layer with NTFS, the FATs variant are
1323             ANSI), we need to properly map between the two.  At startup, Wine
1324             defines what's called the Unix Code Page, that's is the code page
1325             the Unix kernel uses as a reference for the strings.  Then Wine uses
1326             this code page for all the mappings it has to do between a Unicode
1327             path (on the Windows side) and a Ansi path to be used in a Unix path
1328             API.  Note, that this will work as long as a disk isn't mounted with
1329             a different code page than the one the kernel uses as a default.
1330           </para>
1331           <para>
1332             We describe below how Windows devices are mapped to Unix devices.  
1333             Before that, let's finish the pure file round-up with some basic
1334             operations.
1335           </para>
1336         </sect3>
1337         <sect3>
1338           <title>Access rights and file attributes</title>
1339           <para>
1340             Now that we have looked how Wine converts a Windows pathname into a
1341             Unix one, we need to cover the various meta-data attached to a file
1342             or a directory.
1343           </para>
1344           <para>
1345             In Windows, access rights are simplistic: a file can be read-only or
1346             read-write.  Wine sets the read-only flag if the file doesn't have
1347             the Unix user-write flag set.  As a matter of fact, there's no way
1348             Wine can return that a file cannot be read (that doesn't exist under
1349             Windows).  The file will be seen, but trying to open it will return
1350             an error.  The Unix exec-flag is never reported.  Wine doesn't use
1351             this information to allow/forbid running a new process (as Unix does
1352             with the exec-flag).  Last but not least: hidden files.  This exists
1353             on Windows but not really on Unix! To be exact, in Windows, the
1354             hidden flag is a metadata associated to any file or directoy; in
1355             Unix, it's a convention based on the syntax of the file name
1356             (whether it starts with a '.' or not).  Wine implements two behaviors
1357             (chosen by configuration).  This impacts file names and directory
1358             names starting by a '.'.  In first mode
1359             (<option>ShowDotFile</option> is <constant>FALSE</constant>), every 
1360             file or directory starting by '.' is returned with the hidden flag
1361             turned on.  This is the natural behavior on Unix (for
1362             <command>ls</command> or even file explorer).  In the second mode
1363             (<option>ShowDotFile</option> is <constant>TRUE</constant>), Wine
1364             never sets the hidden flag, hence every file will be seen.
1365           </para>
1366           <para>
1367             Last but not least, before opening a file, Windows makes use of
1368             sharing attributes in order to check whether the file can be opened;
1369             for example, a process, being the first in the system to open a
1370             given file, could forbid, while it maintains the file opened, that
1371             another process opens it for write access, whereas open for read
1372             access would be granted.  This is fully supported in Wine by moving
1373             all those checks in the Wine server for a global view on the system.
1374             Note also that what's moved in the Wine server is the check, when
1375             the file is opened, to implement the Windows sharing semantics.
1376             Further operation on the file (like reading and writing) will not
1377             require heavy support from the server.
1378           </para>
1379           <para>
1380             The other good reason for putting the code for actually opening a
1381             file in the server is that an opened files in Windows is managed
1382             through a handle, and handles can only be created in Wine server!
1383           </para>
1384           <para>
1385             Just a note about attributes on directories: while we can easily map
1386             the meaning of Windows' <constant>FILE_ATTRIBUTE_READONLY</constant>
1387             on a file, we cannot do it for a directory.  Windows' semantic (when
1388             this flag is set) means do not delete the directory, while the
1389             <constant>w</constant> attribute in Unix means don't write nor
1390             delete it.  Therefore, Wine uses an asymetric mapping here: if the
1391             directory (in Unix) isn't writable, then Wine reports the
1392             <constant>FILE_ATTRIBUTE_READONLY</constant> attribute; on the other
1393             way around, when asked to set a directory with
1394             <constant>FILE_ATTRIBUTE_READONLY</constant> attribute, Wine simply
1395             does nothing.
1396           </para>
1397         </sect3>
1398         <sect3>
1399           <title>Operations on file</title>
1400           <sect4>
1401             <title>Reading and writing</title>
1402             <para>
1403               Reading and writing are the basic operations on files.  Wine of
1404               course implements this, and bases the implementation on client
1405               side calls to Unix equivalents (like <function>read()</function>
1406               or <function>write()</function>).  Note, that the Wine server is
1407               involved in any read or write operation, as Wine needs to
1408               transform the Windows-handle to the file into a Unix file
1409               descriptor it can pass to any Unix file function.
1410             </para>
1411           </sect4>
1412           <sect4>
1413             <title>Getting a Unix fd</title>
1414             <para>
1415               This is major operation in any file related operation.  Basically,
1416               each file opened (at the Windows level), is first opened in the
1417               Wine server, where the fd is stored.  Then, Wine (on client side)
1418               uses <function>recvmsg()</function> to pass the fd from the wine
1419               server process to the client process.  Since this operation could
1420               be lengthy, Wine implement some kind of cache mechanism to send it
1421               only once, but getting a fd from a handle on a file (or any other
1422               Unix object which can be manipulated through a file descriptor)
1423               still requires a round trip to the Wine server.
1424             </para>
1425           </sect4>
1426           <sect4>
1427             <title>Locking</title>
1428             <para>
1429               Windows provides file locking capabilities.  When a lock is set
1430               (and a lock can be set on any contiguous range in a file), it
1431               controls how other processes in the system will have access to the
1432               range in the file.  Since locking range on a file are defined on a
1433               system wide manner, its implementation resides in
1434               <command>wineserver</command>.  It tries to make use Unix file
1435               locking (if the underlying OS and the mounted disk where the file
1436               sits support this feature) with <function>fcntl()</function> and
1437               the <constant>F_SETLK</constant> command.  If this isn't
1438               supported, then <command>wineserver</command> just pretends it
1439               works. 
1440             </para>
1441           </sect4>
1442           <sect4>
1443             <title>I/O control</title>
1444             <para>
1445               There's no need (so far) to implement support (for files and
1446               directories) for <function>DeviceIoControl()</function>, even if
1447               this is supported by Windows, but for very specific needs
1448               (like compression management, or file system related information).
1449               This isn't the case for devices (including disks), but we'll cover
1450               this in the hereafter section related to devices.
1451             </para>
1452           </sect4>
1453           <sect4>
1454             <title>Buffering</title>
1455             <para>
1456               Wine doesn't do any buffering on file accesses but rely on the
1457               underlying Unix kernel for that (when possible). This scheme is
1458               needed because it's easier to implement multiple accesses on the
1459               same file at the kernel level, rather than at Wine levels.  Doing
1460               lots of small reads on the same file can turn into a performance
1461               hog, because each read operation needs a round trip to the server
1462               in order to get a file descriptor (see above).
1463             </para>
1464           </sect4>
1465           <sect4>
1466             <title>Overlapped I/O</title>
1467             <para>
1468               Windows introduced the notion of overlapped I/O.  Basically, it
1469               just means that an I/O operation (think read / write to start
1470               with) will not wait until it's completed, but rather return to the
1471               caller as soon as possible, and let the caller handle the wait
1472               operation and determine when the data is ready (for a read
1473               operation) or has been sent (for a write operation).  Note that the
1474               overlapped operation is linked to a specific thread.
1475             </para>
1476             <para>
1477               There are several interests to this: a server can handle several
1478               clients without requiring multi-threading techniques; you can
1479               handle an event driven model more easily (ie how to kill properly
1480               a server while waiting in the lengthy <function>read()</function>
1481               operation).
1482             </para>
1483             <para>
1484               Note that Microsoft's support for this feature evolved along the
1485               various versions of Windows.  For example, Windows 95 or 98 only
1486               supports overlapped I/O for serial and parallel ports, while NT
1487               supports also files, disks, sockets, pipes, or mailslots.
1488             </para>
1489             <para>
1490               Wine implements overlapped I/O operations.  This is mainly done by
1491               queueing in the server a request that will be triggered when
1492               something the current state changes (like data available for a
1493               read operation).  This readiness is signaled to the calling
1494               processing by queueing a specific APC, which will be called within
1495               the next waiting operation the thread will have.  This specific
1496               APC will then do the hard work of the I/O operation.  This scheme
1497               allows to put in place a wait mechanism, to attach a routine to be
1498               called (on the thread context) when the state changes, and to be
1499               done is a rather transparent manner (embedded any the generic wait
1500               operation).  However, it isn't 100% perfect.  As the heavy
1501               operations are done in the context of the calling threads, if
1502               those operations are lengthy, there will be an impact on the
1503               calling thread, especially its latency.  In order to provide an
1504               effective support for this overlapped I/O operations, we would
1505               need to rely on Unix kernel features (AIO is a good example).
1506             </para>
1507           </sect4>
1508         </sect3>
1509         <sect3>
1510           <title>Devices & volume management</title>
1511           <para>
1512             We've covered so far the ways file names are mapped into Unix
1513             pathes.  There's still need to cover it for devices.  As a regular
1514             file, devices are manipulated in Windows with both read / write
1515             operations, but also control mechanisms (speed or parity of a serial
1516             line; volume name of a hard disk...).  Since, this is also supported
1517             in Linux, there's also a need to open (in a Unix sense) a device
1518             when given a Windows device name.  This section applies to DOS device
1519             names, which are seen in NT as nicknames to other devices.
1520           </para>
1521           <para>
1522             Firstly, Wine implements the Win32 to NT mapping as described above,
1523             hence every device path (in NT sense) is of the following form:
1524             <filename>/??/devicename</filename> (or
1525             <filename>/DosDevices/devicename</filename>).  As Windows device
1526             names are case insensitive, Wine also converts them to lower case
1527             before any operation.  Then, the first operation Wine tries is to
1528             check whether
1529             <filename>$(WINEPREFIX)/dosdevices/devicename</filename> exists.  If
1530             so, it's used as the final Unix path for the device.  The
1531             configuration process is in charge of creating for example, a
1532             symbolic link between
1533             <filename>$(WINEPREFIX)/dosdevices/PhysicalDrive0</filename> and
1534             <filename>/dev/hda0</filename>.  If such a link cannot be found, and
1535             the device name looks like a DOS disk name (like
1536             <filename>C:</filename>), Wine first tries to get the Unix device
1537             from the path <filename>$(WINEPREFIX)/dosdevices/c:</filename>
1538             (i.e. the device which is mounted on the target of the symbol link);
1539             if this doesn't give a Unix device, Wine tries whether
1540             <filename>$(WINEPREFIX)/dosdevices/c::</filename> exists.  If so,
1541             it's assumed to be a link to the actual Unix device.  For example,
1542             for a CD Rom, <filename>$(WINEPREFIX)/dosdevices/e::</filename>
1543             would be a symbolic link to <filename>/dev/cdrom</filename>.  If
1544             this doesn't exist (we're still handling the a device name of the
1545             <filename>C:</filename> form), Wine tries to get the Unix device
1546             from the system information (<filename>/etc/mtab</filename> and
1547             <filename>/etc/fstab</filename> on Linux).  We cannot apply this
1548             method in all the cases, because we have no insurance that the
1549             directory can actually be found.  One could have, for example, a CD
1550             Rom which he/she want only to use as audio CD player (ie never
1551             mounted), thus not having any information of the device itself.  If
1552             all of this doesn't work either, some basic operations are checked:
1553             if the devicename is <filename>NUL</filename>, then
1554             <filename>/dev/null</filename> is returned.  If the device name is a
1555             default serial name (<filename>COM1</filename> up to
1556             <filename>COM9</filename>) (resp.  printer name
1557             <filename>LPT1</filename> up to <filename>LPT9</filename>), then
1558             Wine tries to open the Nth serial (resp. printer) in the system.
1559             Otherwise, some basic old DOS name support is done
1560             <filename>AUX</filename> is transformed into
1561             <filename>COM1</filename> and <filename>PRN</filename> into
1562             <filename>LPT1</filename>), and the whole process is retried with
1563             those new names.
1564           </para>
1565           <para>
1566             To sum up:
1567             <table>
1568               <title>
1569                 Mapping of Windows device names into Unix device names
1570               </title>
1571               <tgroup cols="3" align="left">
1572                 <thead>
1573                   <row>
1574                     <entry>Windows device name</entry>
1575                     <entry>NT device name</entry>
1576                     <entry>Mapping to Unix device name</entry>
1577                   </row>
1578                 </thead>
1579                 <tbody>
1580                   <row>
1581                     <entry><filename>&lt;any_path&gt;AUX</filename></entry>
1582                     <entry<filename>>\Global??\AUX</filename></entry>
1583                     <entry>
1584                       Treated as an alias to <filename>COM1</filename>
1585                     </entry>
1586                   </row>
1587                   <row>
1588                     <entry><filename>&lt;any_path&gt;PRN</filename></entry>
1589                     <entry><filename>\Global??\PRN</filename></entry>
1590                     <entry>Treated as an alias to <filename>LPT1</filename></entry>
1591                   </row>
1592                   <row>
1593                     <entry><filename>&lt;any_path&gt;COM1</filename></entry>
1594                     <entry><filename>\Global??\COM1</filename></entry>
1595                     <entry>
1596                       <filename>$(WINEPREFIX)/dosdevices/com1</filename>
1597                       (if the symbol link exists) or the Nth serial
1598                       line in the system (on Linux,
1599                       <filename>/dev/ttyS0</filename>).
1600                     </entry>
1601                   </row>
1602                   <row>
1603                     <entry><filename>&lt;any_path&gt;LPT1</filename></entry>
1604                     <entry><filename>\Global??\LPT1</filename></entry>
1605                     <entry>
1606                       <filename>$(WINEPREFIX)/dosdevices/lpt1</filename>
1607                       (if the symbol link exists) or the Nth printer
1608                       in the system (on Linux,
1609                       <filename>/dev/lp0</filename>).
1610                     </entry>
1611                   </row>
1612                   <row>
1613                     <entry><filename>&lt;any_path&gt;NUL</filename></entry>
1614                     <entry><filename>\Global??\NUL</filename></entry>
1615                     <entry><filename>/dev/null</filename></entry>
1616                   </row>
1617                   <row>
1618                     <entry><filename>\\.\E:</filename></entry>
1619                     <entry><filename>\Global??\E:</filename></entry>
1620                     <entry>
1621                       <filename>$(WINEPREFIX)/dosdevices/e::</filename> (if the
1622                       symbolic link exists) or guessing the device from
1623                       <filename>/etc/mtab</filename> or
1624                       <filename>/etc/fstab</filename>.
1625                     </entry>
1626                   </row>
1627                   <row>
1628                     <entry><filename>\\.\&lt;device_name&gt;</filename></entry>
1629                     <entry>
1630                       <filename>\Global??\&lt;device_name&gt;</filename>
1631                     </entry>
1632                     <entry>
1633                       <filename>$(WINEPREFIX)/dosdevices/&lt;device_name&gt;</filename>
1634                       (if the symbol link exists).
1635                     </entry>
1636                   </row>
1637                 </tbody>
1638               </tgroup>
1639             </table>
1640           </para>
1641           <para>
1642             Now that we know which Unix device to open for a given Windows
1643             device, let's cover the operation on it.  Those operations can either
1644             be read / write, io control (and even others).
1645           </para>
1646           <para>
1647             Read and write operations are supported on Real disks & CDROM
1648             devices, under several conditions:
1649             <itemizedlist>
1650               <listitem>
1651                 <para>
1652                   Foremost, as the <function>ReadFile()</function> and
1653                   <function>WriteFile()</function> calls are mapped onto the
1654                   Unix <function>read()</function> and
1655                   <function>write()</function> calls, the user (from the Unix
1656                   perspective of the one running the Wine executable) must have
1657                   read (resp.  write) access to the device.  It wouldn't be wise
1658                   to let a user write directly to a hard disk!!!
1659                 </para>
1660               </listitem>
1661               <listitem>
1662                 <para>
1663                   Blocks' size for read and write but be of the size of a
1664                   physical block (generally 512 for a hard disk, depends on the
1665                   type of CD used), and offsets must also be a multiple of the
1666                   block size.
1667                 </para>
1668               </listitem>
1669             </itemizedlist>
1670           </para>
1671           <para>
1672             Wine also reads (if the first condition above about access rights is
1673             met) the volume information from a hard disk or a CD ROM to be
1674             displayed to a user.
1675           </para>
1676           <!--
1677           <para>
1678             Handling of old DOS devices (<filename>COMx</filename>,
1679             <filename>LPTx</filename>, <filename>NUL</filename>...)
1680           </para>
1681           -->
1682           <para>
1683             Wine also recognizes VxD as devices.  But those VxD must be the
1684             Wine builtin ones (Wine will never allow to load native VxD).  Those
1685             are configured with symbolic links in the
1686             <filename>$(WINEPREFIX)/dosdevices/</filename> directory, and point
1687             to the actual builtin DLL.  This DLL exports a single entry point,
1688             that Wine will use when a call to
1689             <function>DeviceIoControl</function> is made, with a handle opened
1690             to this VxD.  This allows to provide some kind of compatibility for
1691             old Win9x apps, still talking directly to VxD.  This is no longer
1692             supported on Windows NT, newest programs are less likely to make use
1693             of this feature, so we don't expect lots of development in this
1694             area, eventhough the framework is there and working.  Note also that
1695             Wine doesn't provide support for native VxDs (as a game, report how
1696             many times this information is written in the documentation;  as an
1697             advanced exercice, find how many more occurences we need in order to
1698             stop questions whether it's possible or not).
1699           </para>
1700         </sect3>
1701       </sect2>
1702     </sect1>
1703     <sect1 id="ntdll">
1704       <title><filename>NTDLL</filename> module</title>
1705       <para>
1706         <filename>NTDLL</filename> provides most of the services you'd expect
1707         from a kernel. In lots of cases, <filename>KERNEL32</filename> APIs are
1708         just wrappers to <filename>NTDLL</filename> APIs. There are however,
1709         some difference in the APIs (the <filename>NTDLL</filename> ones have
1710         quite often a bit wider semantics than their
1711         <filename>KERNEL32</filename> counterparts). All the detailed functions
1712         we've described since the beginning of this chapter are in fact
1713         implemented in <filename>NTDLL</filename>, plus a great numbers of
1714         others we haven's written about yet.
1715       </para>
1716     </sect1>
1717
1718     <sect1>
1719       <title><filename>KERNEL32</filename> Module</title>
1720       
1721       <para>
1722         As already explained, <filename>KERNEL32</filename> maps quite a few of
1723         its APIs to <filename>NTDLL</filename>. There are however a couple of
1724         things which are handled directly in
1725         <filename>KERNEL32</filename>. Let's cover a few of them...
1726       </para>
1727       <sect2 id="consoles">
1728         <title>Console</title>
1729         <sect3>
1730           <title>NT implementation</title>
1731           <para>
1732             Windows implements console solely in the Win32 subsystem.  Under NT,
1733             the real implementation uses a dedicated subsystem
1734             <filename>csrss.exe</filename> Client/Server Run-time SubSystem)
1735             which is in charge, amont other things, of animating the consoles.
1736             Animating includes for example handling several processes on the
1737             same console (write operations must be atomic, but also a character
1738             keyed on the console must be read by a single process), or sending
1739             some information back to the processes (changing the size or
1740             attributes of the console, closing the console).  Windows NT uses a
1741             dedicated (RPC based) protocol between each process being attached
1742             to a console and the <command>csrss.exe</command> subsystem, which
1743             is in charge of the UI of every console in the system.
1744           </para>
1745         </sect3>
1746         <sect3>
1747           <title>Wine implementation</title>
1748           <para>
1749             Wine tries to integrate as much as possible into the Unix consoles,
1750             but the overall situation isn't perfect yet.  Basically, Wine
1751             implements three kinds of consoles:
1752             <itemizedlist>
1753               <listitem>
1754                 <para>
1755                   the first one is a direct mapping of the Unix console into the
1756                   Windows environment.  From the windows program point of view,
1757                   it won't run in a Windows console, but it will see its
1758                   standard input and output streams redirected to files; thoses
1759                   files are hooked into the Unix console's output and input
1760                   streams respectively.  This is handy for running programs from
1761                   a Unix command line (and use the result of the program as it
1762                   was a Unix programs), but it lacks all the semantics of the
1763                   Windows consoles.
1764                 </para>
1765               </listitem>
1766               <listitem>
1767                 <para>
1768                   the second and third ones are closer to the NT scheme, albeit
1769                   different to what NT does.  The <command>wineserver</command>
1770                   plays the role of the <filename>csrss.exe</filename> subsystem
1771                   (all requests are sent to it), and are then dispatched to a
1772                   dedicated wine process, called (surprise!)
1773                   <command>wineconsole</command> which manages the UI of the
1774                   console.  There is a running instance of
1775                   <command>wineconsole</command> for every console in the
1776                   system.  Two  flavors of this scheme are actually implemented:
1777                   they vary on the backend for the
1778                   <command>wineconsole</command>.  The first one,  dubbed
1779                   <constant>user</constant>, creates a real GUI window
1780                   (hence the USER name) and renders the console in this window.
1781                   The second one uses the <filename>(n)curses</filename> library
1782                   to take full control of an existing Unix console; of course,
1783                   interaction with other Unix programs will not be as smooth as
1784                   the first solution.
1785                 </para>
1786               </listitem>
1787             </itemizedlist>
1788           </para>
1789           <para>
1790             The following table describes the main implementation differences
1791             between the three approaches.
1792             <table>
1793               <title>Function consoles implementation comparison</title>
1794               <tgroup cols="4" align="left">
1795                 <thead>
1796                   <row>
1797                     <entry>Function</entry>
1798                     <entry>Bare streams</entry>
1799                     <entry>
1800                       <command>Wineconsole</command> &amp; user backend
1801                     </entry>
1802                     <entry>
1803                       <command>Wineconsole</command> &amp; curses backend
1804                     </entry>
1805                   </row>
1806                 </thead>
1807                 <tbody>
1808                   <row>
1809                     <entry>
1810                       Console as a Win32 Object (and associated handles)
1811                     </entry>
1812                     <entry>
1813                       No specific Win32 object is used in this case.  The
1814                       handles manipulated for the standard Win32 streams are in
1815                       fact "bare handles" to their corresponding Unix streams.
1816                       The mode manipulation functions
1817                       (<function>GetConsoleMode()</function> /
1818                       <function>SetConsoleMode()</function>) are not supported.
1819                     </entry>
1820                     <entry>
1821                       Implemented in server, and a specific Winelib program
1822                       (<command>wineconsole</command>) is in charge of the
1823                       rendering and user input.  The mode manipulation functions
1824                       behave as expected.
1825                     </entry>
1826                     <entry>
1827                       Implemented in server, and a specific Winelib program
1828                       (<command>wineconsole</command>) is in charge of the
1829                       rendering and user input.  The mode manipulation functions
1830                       behave as expected.
1831                     </entry>
1832                   </row>
1833                   <row>
1834                     <entry>
1835                       Inheritance (including handling in
1836                       <function>CreateProcess()</function> of
1837                       <constant>CREATE_DETACHED</constant>,
1838                       <constant>CREATE_NEW_CONSOLE</constant> flags).
1839                     </entry>
1840                     <entry>
1841                       Not supported.  Every process child of a process will
1842                       inherit the Unix streams, so will also inherit the Win32
1843                       standard streams.
1844                     </entry>
1845                     <entry>
1846                       Fully supported (each new console creation will be handled
1847                       by the creation of a new <filename>USER32</filename> window)
1848                     </entry>
1849                     <entry>
1850                       Fully supported, except for the creation of a new console,
1851                       which will be rendered on the same Unix terminal as the
1852                       previous one, leading to unpredictable results.
1853                     </entry>
1854                   </row>
1855                   <row>
1856                     <entry>
1857                       <function>ReadFile()</function> / 
1858                       <function>WriteFile()</function> operations
1859                     </entry> 
1860                     <entry>Fully supported</entry>
1861                     <entry>Fully supported</entry>
1862                     <entry>Fully supported</entry>
1863                   </row>
1864                   <row>
1865                     <entry>
1866                       Screen-buffer manipulation (creation, deletion, resizing...)
1867                     </entry>
1868                     <entry>Not supported</entry>
1869                     <entry>Fully supported</entry>
1870                     <entry>
1871                       Partly supported (this won't work too well as we don't
1872                       control (so far) the size of underlying Unix terminal
1873                     </entry>
1874                   </row>
1875                   <row>
1876                     <entry>
1877                       APIs for reading/writing screen-buffer content, cursor position
1878                     </entry>
1879                     <entry>Not supported</entry>
1880                     <entry>Fully supported</entry>
1881                     <entry>Fully supported</entry>
1882                   </row>
1883                   <row>
1884                     <entry>APIs for manipulating the rendering window size</entry>
1885                     <entry>Not supported</entry>
1886                     <entry>Fully supported</entry>
1887                     <entry>
1888                       Partly supported (this won't work too well as we don't
1889                       control (so far) the size of underlying Unix terminal
1890                     </entry>
1891                   </row>
1892                   <row>
1893                     <entry>
1894                       Signaling (in particular, Ctrl-C handling)
1895                     </entry>
1896                     <entry>
1897                       Nothing is done, which means that Ctrl-C will generate (as
1898                       usual) a <constant>SIGINT</constant> which will terminate
1899                       the program.
1900                     </entry>
1901                     <entry>
1902                       Partly supported (Ctrl-C behaves as expected, however the
1903                       other Win32 CUI signaling isn't properly implemented).
1904                     </entry>
1905                     <entry>
1906                       Partly supported (Ctrl-C behaves as expected, however the
1907                       other Win32 CUI signaling isn't properly implemented).
1908                     </entry>
1909                   </row>
1910                 </tbody>
1911               </tgroup>
1912             </table>
1913           </para>
1914           <para>
1915             The Win32 objects behind a console can be created in several
1916             occasions:
1917             <itemizedlist>
1918               <listitem>
1919                 <para>
1920                   When the program is started from
1921                   <command>wineconsole</command>, a new console object is
1922                   created and will be used (inherited) by the process launched
1923                   from <command>wineconsole</command>.
1924                 </para>
1925               </listitem>
1926               <listitem>
1927                 <para>
1928                   When a program, which isn't attached to a console, calls
1929                   <function>AllocConsole()</function>, Wine then launches
1930                   <command>wineconsole</command>, and attaches the current
1931                   program to this console.  In this mode, the
1932                   <filename>USER32</filename> mode is always selected as Wine
1933                   cannot tell the current state of the Unix console.
1934                 </para>
1935               </listitem>
1936             </itemizedlist>
1937           </para>
1938           <para>
1939             Please also note, that starting a child process with the
1940             <constant>CREATE_NEW_CONSOLE</constant> flag, will end-up calling
1941             <function>AllocConsole()</function> in the child process, hence
1942             creating a <command>wineconsole</command> with the
1943             <filename>USER32</filename> backend.
1944           </para>
1945           <para>
1946             Another interesting point to note is that Windows implements handles
1947             to console objects (input and screen buffers) only in the
1948             <filename>KERNEL32</filename> DLL, and those are not sent nor seen
1949             from the <filename>NTDLL</filename> level, albeit, for example,
1950             console are waitable on input.  How is this possible?  Well, Windows
1951             NT is a bit tricky here.  Regular handles have an interesting
1952             property: their integral value is always a multiple of four (they
1953             are likely to be offsets from the beginning of a table).  Console
1954             handles, on the other hand, are not multiple of four, but have the
1955             two lower bit set (being a multiple of four means having the two
1956             lower bits reset).  When <filename>KERNEL32</filename> sees a handle
1957             with the two lower bits set, it then knows it's a console handle and
1958             takes appropriate decisions.  For example, in the various
1959             <function>kernel32!WaitFor*()</function> functions, it transforms
1960             any console handle (input and <emphasis>output</emphasis> -
1961             strangely enough handles to console's screen buffers are waitable)
1962             into a dedicated wait event for the targetted console.  There's an
1963             (undocumented) <filename>KERNEL32</filename> function
1964             <function>GetConsoleInputWaitHandle()</function> which returns the
1965             handle to this event in case you need it.  Another interesting
1966             handling of those console's handles is in
1967             <function>ReadFile()</function>
1968             (resp. <function>WriteFile()</function>), which behavior, for
1969             console's handles, is transferred to
1970             <function>ReadConsole()</function> (resp.
1971             <function>WriteConsole()</function>).  Note that's always the ANSI
1972             version of
1973             <function>ReadConsole()</function> /
1974             <function>WriteConsole()</function>
1975             which is called, hence using the default console's code page.  There
1976             are some other spots affected, but you can look in
1977             <filename>dlls/kernel</filename> to find them all.  All of this is
1978             implemented in Wine.
1979           </para>
1980           <para>
1981             Wine also implements the same layout of the registry for storing the
1982             preferences of the console as Windows does.  Those settings can
1983             either be defined globally, or on a per process name basis.
1984             <command>wineconsole</command> provides the choice to the user to
1985             pick you which registry part (global, current running program) it
1986             wishes to modify the settings for.
1987             <table>
1988               <title>Console registry settings</title>
1989               <tgroup cols="3" align="left">
1990                 <thead>
1991                   <row>
1992                     <entry>Name</entry>
1993                     <entry>Default value</entry>
1994                     <entry>Purpose</entry>
1995                   </row>
1996                 </thead>
1997                 <tbody>
1998                   <row>
1999                     <entry>CursorSize</entry>
2000                     <entry>25</entry>
2001                     <entry>
2002                       Percentage of cell height to which the cursor extents
2003                     </entry>
2004                   </row>
2005                   <row>
2006                     <entry>CursorVisible</entry>
2007                     <entry>1</entry>
2008                     <entry>Whether the cursor is visible or not</entry>
2009                   </row>
2010                   <row>
2011                     <entry>EditionMode</entry>
2012                     <entry>0</entry>
2013                     <entry>
2014                       The way the edition takes place in the console: 0 is
2015                       insertion mode, 1 is overwrite mode.
2016                     </entry>
2017                   </row>
2018                   <row>
2019                     <entry>ExitOnDie</entry>
2020                     <entry>1</entry>
2021                     <entry>
2022                       Whether the console should close itself when last running
2023                       program attached to it dies
2024                     </entry>
2025                   </row>
2026                   <row>
2027                     <entry>FaceName</entry>
2028                     <entry>No default</entry>
2029                     <entry>
2030                       Name of the font to be used for display.  When none is
2031                       given, <command>wineconsole</command> tries its best to
2032                       pick up a decent font
2033                     </entry>
2034                   </row>
2035                   <row>
2036                     <entry>FontSize</entry>
2037                     <entry>0x0C08</entry>
2038                     <entry>
2039                       The high word in the font's cell height, and the low word
2040                       is the font cell's width.  The default value is 12 pixels
2041                       in height and 8 pixels in width.
2042                     </entry>
2043                   </row>
2044                   <row>
2045                     <entry>FontWeight</entry>
2046                     <entry>0</entry>
2047                     <entry>
2048                       Weigth of the font.  If none is given (or 0)
2049                       <command>wineconsole</command> picks up a decent font size
2050                     </entry>
2051                   </row>
2052                   <row>
2053                     <entry>HistoryBufferSize</entry>
2054                     <entry>50</entry>
2055                     <entry>
2056                       Number of entries in history buffer (not actually used)
2057                     </entry>
2058                   </row>
2059                   <row>
2060                     <entry>HistoryNoDup</entry>
2061                     <entry>0</entry>
2062                     <entry>
2063                       Whether the history should store twice the same entry
2064                     </entry>
2065                   </row>
2066                   <row>
2067                     <entry>MenuMask</entry>
2068                     <entry>0</entry>
2069                     <entry>
2070                       This mask only exists for Wine console handling.  It
2071                       allows to know which combination of extra keys are need to
2072                       open the configuration window on right click.  The mask
2073                       can include <constant>MK_CONTROL</constant> or
2074                       <constant>MK_SHIFT</constant> bits.  This can be needed
2075                       when programs actually need the right click to be passed
2076                       to them instead of being intercepted by
2077                       <command>wineconsole</command>.
2078                     </entry>
2079                   </row>
2080                   <row>
2081                     <entry>QuickEdit</entry>
2082                     <entry>0</entry>
2083                     <entry>
2084                       If null, mouse events are sent to the application.  If non
2085                       null, mouse events are used to select text on the window.
2086                       This setting must really be set on a application per
2087                       application basis, because it deals with the fact the CUI
2088                       application will use or not the mouse events.
2089                     </entry>
2090                   </row>
2091                   <row>
2092                     <entry>ScreenBufferSize</entry>
2093                     <entry>0x1950</entry>
2094                     <entry>
2095                       The high word is the number of font cells in the height of
2096                       the screen buffer, while the low word is the number of
2097                       font cells in the width of the screen buffer.
2098                     </entry>
2099                   </row>
2100                   <row>
2101                     <entry>ScreenColors</entry>
2102                     <entry>0x000F</entry>
2103                     <entry>
2104                       Default color attribute for the screen buffer (low char is
2105                       the foreground color, and high char is the background
2106                       color)
2107                     </entry>
2108                   </row>
2109                   <row>
2110                     <entry>WindowSize</entry>
2111                     <entry>0x1950</entry>
2112                     <entry>
2113                       The high word is the number of font cells in the height of
2114                       the window, while the low word is the number of font cells
2115                       in the width of the window.  This window is the visible
2116                       part of the screen buffer: this implies that a screen
2117                       buffer must always be bigger than its window, and that the
2118                       screen buffer can be scrolled so that every cell of the
2119                       screen buffer can be seen in the window.
2120                     </entry>
2121                   </row>
2122                 </tbody>
2123               </tgroup>
2124             </table>
2125           </para>
2126         </sect3>
2127       </sect2>
2128     </sect1>
2129     
2130   </chapter>
2131
2132 <!-- Keep this comment at the end of the file
2133 Local variables:
2134 mode: sgml
2135 sgml-parent-document:("wine-devel.sgml" "set" "book" "part" "chapter" "")
2136 End:
2137 -->