2 <title>Kernel modules</title>
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>.
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).
20 <sect1 id="initialization">
22 <title>The Wine initialization process</title>
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.
37 <title>First Steps</title>
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.
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.
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).
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.
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.
114 <title>Starting the emulator</title>
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>.
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
134 <function>wine_init()</function> can, with the correct preparation,
135 be called from programs other than the wine loader itself.
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>
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
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>.
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!
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:
193 ExitProcess( entry( peb ) );
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.
205 <sect1 id="threading">
206 <title>Multi-threading in Wine</title>
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
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
227 <title>Threading support in Win32</title>
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.
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!
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.
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:
266 if (res != ERROR_SUCCESS) return res;
270 is extremely suspect in a function that also contains a call to
271 <function>EnterCriticalSection()</function>. Be careful.
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.
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.
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.
317 <title>SysLevels</title>
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.
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.
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
351 <title>POSIX threading vs. kernel threading</title>
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.
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.
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.
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.
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
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.
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
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.
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.
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.
462 <title>The Win32 thread environment</title>
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
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.
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>.
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:
502 <programlisting>movl %esp, %fs:0</programlisting>
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
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).
532 <title>Structured Exception Handling</title>
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.
543 <title>How SEH works</title>
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.
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.
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.
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.
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>
591 <title>Translating signals to exceptions</title>
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.
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
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
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.
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 -->
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
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.
668 <title>File management</title>
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).
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).
688 <title>Various Windows formats for file names</title>
690 Let's first review a bit the various forms Windows uses when it comes
695 <title>The DOS inheritance</title>
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!!!
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.
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).
739 <title>The NT way</title>
741 The introduction of NT allowed a deep change in the ways DOS had
742 been handling devices:
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.
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
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.
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
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.
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).
799 In NT naming convention, <filename>\Global??</filename> can
800 also be called <filename>\??</filename> to shorten the
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.
816 <title>Wrap up</title>
818 Let's end this chapter about files in Windows with a review of the
819 different formats used for file names:
822 <para><filename>c:\foo\bar</filename> is a full path.</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).
833 <filename>bar</filename> is a relative path; the full path is
834 created by adding the current directory.
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:
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>.
873 Otherwise it's resolved into
874 <filename>c:\bar</filename>.
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.
902 Wine fully implements all those behaviors (the Windows 9x vs
903 NT ones are triggered by the version flag in Wine).
908 <filename>\\host\share</filename> is <firstterm>UNC</firstterm>
909 (Universal Naming Convention) path, ie. represents a file on a
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>.
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.
940 To summarize, what we've discussed so, let's put everything into a
943 <title>DOS, Win32 and NT paths equivalences</title>
944 <tgroup cols="3" align="left">
947 <entry>Type of path</entry>
948 <entry>Win32 example</entry>
949 <entry>NT equivalent</entry>
950 <entry>Rule to construct</entry>
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>
961 <entry>Absolute path</entry>
962 <entry><filename>\foo\bar.txt</filename></entry>
963 <entry><filename>\Global??\J:\foo\bar.txt</filename></entry>
965 Simple concatenation using the drive of the default
970 <entry>Relative path</entry>
971 <entry><filename>gee\bar.txt</filename></entry>
974 \Global??\J:\mydir\mysubdir\gee\bar.txt
978 Simple concatenation using the default directory
979 (here <filename>J:\mydir\mysubdir</filename>)
983 <entry>Drive relative path</entry>
984 <entry><filename>j:gee\bar.txt</filename></entry>
991 On Windows 9x (and DOS),
992 <filename>J:\toto\gee\bar.txt</filename>.
998 <filename>J:\gee\bar.txt</filename>.
1004 <filename>J:\tata\titi\bar.txt</filename>.
1017 On Windows NT (and DOS),
1018 <filename>\toto</filename> is the default
1019 directory on drive <filename>J:</filename>.
1024 On Windows NT, if <envar>=J:</envar> isn't set.
1029 On Windows NT, if <envar>=J:</envar> is set to
1030 <filename>J:\tata\titi</filename>.
1039 <entry>UNC (Uniform Naming Convention) path</entry>
1040 <entry><filename>\\host\share\foo\bar.txt</filename></entry>
1042 <filename>\Global??\UNC\host\share\foo\bar.txt</filename>
1045 Simple concatenation.
1049 <entry>Device path</entry>
1050 <entry><filename>\\.\device</filename></entry>
1051 <entry><filename>\Global??\device</filename></entry>
1052 <entry>Simple concatenation</entry>
1055 <entry>Long paths</entry>
1056 <entry><filename>\\?\...</filename></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
1075 <title>Wine implementation</title>
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...
1083 <title>Mapping a Windows path into an absolute Windows path</title>
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.
1094 <title>Mapping a Windows (absolute) path onto a Unix path</title>
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
1111 a very simple algorithm to map a DOS path name into a Unix one
1112 (no need of Wine server calls)
1117 a very configurable implementation: it's very easy to change a
1123 a rather readable configuration: no need of sophisticated
1124 tools to read a drive mapping, a <command>ls -l
1125 $(WINEPREFIX)/dosdevices</command>
1132 This scheme is also used to implement UNC path names. For example,
1133 Wine maps <filename>\\host\share\foo\bar\MyRemoteFile.txt</filename>
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.
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
1151 <title>File systems' properties</title>
1152 <tgroup cols="4" align="left">
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>
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>
1170 <entry>Short name (8+3) + alias on long name</entry>
1172 Short names are always stored in upper-case. Long names
1173 are stored with case preservation.
1175 <entry>Case insensitive</entry>
1179 <entry>Long name + alias on short name (8+3).</entry>
1181 Long names are stored with case preservation. Short names
1182 are always stored in upper-case.
1184 <entry>Case insentivite</entry>
1187 <entry>Linux FS (ext2fs, ext3fs, reiserfs...)</entry>
1188 <entry>Long name</entry>
1189 <entry>Case preserving</entry>
1190 <entry>Case sensitive</entry>
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.
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.
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.
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
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
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:
1277 The algorithm is rather simple and low cost.
1282 The algorithm is stateless (doesn't depend of the other
1283 files in the directory).
1287 But, it also has the drawbacks (of the advantages):
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
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).
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.
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.
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
1338 <title>Access rights and file attributes</title>
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
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.
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.
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!
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
1399 <title>Operations on file</title>
1401 <title>Reading and writing</title>
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.
1413 <title>Getting a Unix fd</title>
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.
1427 <title>Locking</title>
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
1443 <title>I/O control</title>
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.
1454 <title>Buffering</title>
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).
1466 <title>Overlapped I/O</title>
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.
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>
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.
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).
1510 <title>Devices & volume management</title>
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.
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
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
1569 Mapping of Windows device names into Unix device names
1571 <tgroup cols="3" align="left">
1574 <entry>Windows device name</entry>
1575 <entry>NT device name</entry>
1576 <entry>Mapping to Unix device name</entry>
1581 <entry><filename><any_path>AUX</filename></entry>
1582 <entry<filename>>\Global??\AUX</filename></entry>
1584 Treated as an alias to <filename>COM1</filename>
1588 <entry><filename><any_path>PRN</filename></entry>
1589 <entry><filename>\Global??\PRN</filename></entry>
1590 <entry>Treated as an alias to <filename>LPT1</filename></entry>
1593 <entry><filename><any_path>COM1</filename></entry>
1594 <entry><filename>\Global??\COM1</filename></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>).
1603 <entry><filename><any_path>LPT1</filename></entry>
1604 <entry><filename>\Global??\LPT1</filename></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>).
1613 <entry><filename><any_path>NUL</filename></entry>
1614 <entry><filename>\Global??\NUL</filename></entry>
1615 <entry><filename>/dev/null</filename></entry>
1618 <entry><filename>\\.\E:</filename></entry>
1619 <entry><filename>\Global??\E:</filename></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>.
1628 <entry><filename>\\.\<device_name></filename></entry>
1630 <filename>\Global??\<device_name></filename>
1633 <filename>$(WINEPREFIX)/dosdevices/<device_name></filename>
1634 (if the symbol link exists).
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).
1647 Read and write operations are supported on Real disks & CDROM
1648 devices, under several conditions:
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!!!
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
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.
1678 Handling of old DOS devices (<filename>COMx</filename>,
1679 <filename>LPTx</filename>, <filename>NUL</filename>...)
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).
1704 <title><filename>NTDLL</filename> module</title>
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.
1719 <title><filename>KERNEL32</filename> Module</title>
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...
1727 <sect2 id="consoles">
1728 <title>Console</title>
1730 <title>NT implementation</title>
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.
1747 <title>Wine implementation</title>
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:
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
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
1790 The following table describes the main implementation differences
1791 between the three approaches.
1793 <title>Function consoles implementation comparison</title>
1794 <tgroup cols="4" align="left">
1797 <entry>Function</entry>
1798 <entry>Bare streams</entry>
1800 <command>Wineconsole</command> & user backend
1803 <command>Wineconsole</command> & curses backend
1810 Console as a Win32 Object (and associated handles)
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.
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
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
1835 Inheritance (including handling in
1836 <function>CreateProcess()</function> of
1837 <constant>CREATE_DETACHED</constant>,
1838 <constant>CREATE_NEW_CONSOLE</constant> flags).
1841 Not supported. Every process child of a process will
1842 inherit the Unix streams, so will also inherit the Win32
1846 Fully supported (each new console creation will be handled
1847 by the creation of a new <filename>USER32</filename> window)
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.
1857 <function>ReadFile()</function> /
1858 <function>WriteFile()</function> operations
1860 <entry>Fully supported</entry>
1861 <entry>Fully supported</entry>
1862 <entry>Fully supported</entry>
1866 Screen-buffer manipulation (creation, deletion, resizing...)
1868 <entry>Not supported</entry>
1869 <entry>Fully supported</entry>
1871 Partly supported (this won't work too well as we don't
1872 control (so far) the size of underlying Unix terminal
1877 APIs for reading/writing screen-buffer content, cursor position
1879 <entry>Not supported</entry>
1880 <entry>Fully supported</entry>
1881 <entry>Fully supported</entry>
1884 <entry>APIs for manipulating the rendering window size</entry>
1885 <entry>Not supported</entry>
1886 <entry>Fully supported</entry>
1888 Partly supported (this won't work too well as we don't
1889 control (so far) the size of underlying Unix terminal
1894 Signaling (in particular, Ctrl-C handling)
1897 Nothing is done, which means that Ctrl-C will generate (as
1898 usual) a <constant>SIGINT</constant> which will terminate
1902 Partly supported (Ctrl-C behaves as expected, however the
1903 other Win32 CUI signaling isn't properly implemented).
1906 Partly supported (Ctrl-C behaves as expected, however the
1907 other Win32 CUI signaling isn't properly implemented).
1915 The Win32 objects behind a console can be created in several
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>.
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.
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.
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
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.
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.
1988 <title>Console registry settings</title>
1989 <tgroup cols="3" align="left">
1993 <entry>Default value</entry>
1994 <entry>Purpose</entry>
1999 <entry>CursorSize</entry>
2002 Percentage of cell height to which the cursor extents
2006 <entry>CursorVisible</entry>
2008 <entry>Whether the cursor is visible or not</entry>
2011 <entry>EditionMode</entry>
2014 The way the edition takes place in the console: 0 is
2015 insertion mode, 1 is overwrite mode.
2019 <entry>ExitOnDie</entry>
2022 Whether the console should close itself when last running
2023 program attached to it dies
2027 <entry>FaceName</entry>
2028 <entry>No default</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
2036 <entry>FontSize</entry>
2037 <entry>0x0C08</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.
2045 <entry>FontWeight</entry>
2048 Weigth of the font. If none is given (or 0)
2049 <command>wineconsole</command> picks up a decent font size
2053 <entry>HistoryBufferSize</entry>
2056 Number of entries in history buffer (not actually used)
2060 <entry>HistoryNoDup</entry>
2063 Whether the history should store twice the same entry
2067 <entry>MenuMask</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>.
2081 <entry>QuickEdit</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.
2092 <entry>ScreenBufferSize</entry>
2093 <entry>0x1950</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.
2101 <entry>ScreenColors</entry>
2102 <entry>0x000F</entry>
2104 Default color attribute for the screen buffer (low char is
2105 the foreground color, and high char is the background
2110 <entry>WindowSize</entry>
2111 <entry>0x1950</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.
2132 <!-- Keep this comment at the end of the file
2135 sgml-parent-document:("wine-devel.sgml" "set" "book" "part" "chapter" "")
projects / wine / blob