Added protocol type constants.
[wine] / documentation / wine.conf.man
1 .\" -*- nroff -*-
2 .TH WINE.CONF 5 "September 2003" "Version 20030911" "Wine Configuration File"
3 .SH NAME
4 wine.conf \- Wine configuration file
5 .SH DESCRIPTION
6 .B wine
7 expects a configuration file (
8 .I $WINEPREFIX/config
9 (~/.wine/config)
10 ), which should conform to the following rules.
11 A sample configuration file is available as
12 .I documentation/samples/config
13 in the Wine source distribution.
14 .SH CONFIGURATION FILE FORMAT
15 All entries are grouped in sections; a section begins with the line
16 .br
17 .I [section name]
18 .br
19 and continues until the next section starts. Individual entries
20 consist of lines of the form
21 .br
22 .I """entry""=""value"""
23 .br
24 The entry and value can be any text strings, included in double
25 quotes; it can also contain references to environment variables
26 surrounded by
27 .I ${}.
28 Inside the double quotes, special characters, backslashes and quotes
29 must be escaped with backslashes. Supported section names and entries
30 are listed below.
31 .PP
32 .B [Drive X]
33 .br
34 This section is used to specify the root directory and type of each emulated
35 .B DOS
36 drive, since most Windows applications require a DOS/MS-Windows based
37 disk drive & directory scheme, which is either provided by a real
38 DOS partition mounted somewhere or by some carefully crafted directory layout
39 on a Unix file system ("no-windows fake installation").
40 There is one such section for every drive you want to configure.
41 .PP
42 .I format: """Path""=""<rootdirectory>"""
43 .br
44 default: none
45 .br
46 If you mounted your dos partition as
47 .I /dos
48 and installed Microsoft Windows in
49 C:\\WINDOWS (thus it shows up as /dos/WINDOWS), then you should specify
50 .I """Path""=""/dos"""
51 in the
52 .I [Drive C]
53 section in order to configure /dos as the drive root of drive C:.
54 .PP
55 .I format: """Type""=""<type>"""
56 .br
57 default: "hd"
58 .br
59 Used to specify the drive type this drive appears as in Windows
60 or DOS programs; supported types are "floppy", "hd", "cdrom"
61 and "network".
62 .PP
63 .I format: """Label""=""<label>"""
64 .br
65 default: "Drive X"
66 .br
67 Used to specify the drive label; limited to 11 characters.
68 .PP
69 .I format: """Serial""=""<serial>"""
70 .br
71 default: "12345678"
72 .br
73 Used to specify the drive serial number, as an 8-character hexadecimal
74 number.
75 .PP
76 .I format: """Filesystem""=""<fstype>"""
77 .br
78 default: "win95"
79 .br
80 Used to specify the type of the file system Wine should emulate on a given
81 directory structure/underlying file system.
82 .br
83 Supported types are "msdos" (or "fat"), "win95" (or "vfat"), "unix".
84 .br
85 Recommended:
86 .br
87   "win95" for ext2fs, ReiserFS, ..., VFAT and FAT32
88 .br
89   "msdos" for FAT16 file systems (ugly, 8.3 naming)
90 .br
91 You definitely do not want to use "unix" unless you intend to port
92 programs using Winelib.  Always try to avoid using a FAT16 FS. Use the
93 VFAT/FAT32 OS file system driver instead.
94 .PP
95 .I format: """FailReadOnly""=""<boolean>"""
96 .br
97 Read-only files may not be opened in write mode (the default is to
98 allow opening read-only files for writing, because most Windows
99 programs always request read-write access, even on CD-ROM drives...).
100 .PP
101 .B [wine]
102 .br
103 .I format: """windows""=""<directory>"""
104 .br
105 default: "C:\\\\WINDOWS"
106 .br
107 Used to specify where Wine is supposed to have its Windows directory
108 (which is an essential part of a Windows environment); make sure to double
109 the backslashes.
110 In case of e.g. C:\\WINDOWS, with drive C: being configured as
111 /home/user/wine_c, the /home/user/wine_c/WINDOWS directory would be used for
112 this.
113 .PP
114 .I format: """system""=""<directory>"""
115 .br
116 default: "C:\\\\WINDOWS\\\\System"
117 .br
118 Used to specify where Wine is supposed to have its Windows system directory
119 (again, essential part of Windows environment); make sure to double the backslashes.
120 Given a setting of C:\\WINDOWS\\System (the standard setting on Windows)
121 and a C: drive again at /home/user/wine_c, the /home/user/wine_c/WINDOWS/System
122 directory would be used for this.
123 .PP
124 .I format: """temp""=""<directory>"""
125 .br
126 default: "C:\\\\TEMP"
127 .br
128 Used to specify a directory where Windows applications can store
129 temporary files. E.g. with a C: drive at /home/user/wine_c, this would be
130 the /home/user/wine_c/TEMP directory.
131 .PP
132 .I format: """profile""=""<directory>"""
133 .br
134 default: nothing
135 .br
136 Used to specify a directory where Windows stores special folders and
137 the user-registry files (user.dat or ntuser.dat).  Mapped to
138 environment variable %USERPROFILE%.  Set this value when running with
139 a native NT or a native win95 directory with per-user settings.
140 .PP
141 .I format: """path""=""<directories separated by semi-colons>"""
142 .br
143 default: "C:\\\\WINDOWS;C:\\\\WINDOWS\\\\SYSTEM"
144 .br
145 Used to specify the path which will be used to find executables and
146 dlls. Make sure to double the backslashes.
147 .PP
148 .I format: """GraphicsDriver""=""<x11drv|ttydrv>"""
149 .br
150 default: "x11drv"
151 .br
152 Tells Wine which graphics driver to use. Normally you'd want to use
153 x11drv (for X11). In case you want to run programs as text console/TTY only
154 without having Wine rely on X11 support, then use ttydrv.
155 .PP
156 .I format: """ShowDirSymlinks""=""<0|1>"""
157 .br
158 default: "0"
159 .br
160 Wine doesn't pass directory symlinks to Windows programs by default.
161 Enabling this may crash some programs that do recursive lookups of a whole
162 subdir tree in case of a symlink pointing back to itself.
163 .PP
164 .I format: """ShowDotFiles""=""<0|1>"""
165 .br
166 default: "0"
167 .br
168 Under Unix, files starting with a dot, are considered hidden,
169 and should not be shown in directory listing (unless explicitly asked for),
170 just like DOS-style hidden files. If you want them treated as regular
171 files, set this value to 1.
172 .PP
173 .B [Version]
174 .br
175 .I format: """Windows""=""<version string>"""
176 .br
177 default: none; chosen by semi-intelligent detection mechanism based on DLL environment
178 .br
179 Used to specify which Windows version to return to programs (forced value,
180 overrides standard detection mechanism !).
181 Valid settings are e.g. "win31", "win95", "win98", "win2k", "winxp".
182 Also valid as an AppDefaults setting (recommended/preferred use).
183 .PP
184 .I format: """DOS""=""<version string>"""
185 .br
186 default: "<Windows version specific>"
187 .br
188 Used to specify the DOS version that should be returned to programs.
189 Only takes effect in case Wine acts as "win31" Windows version !
190 Common DOS version settings include 6.22, 6.20, 6.00, 5.00, 4.00, 3.30, 3.10.
191 Also valid as an AppDefaults setting (recommended/preferred use).
192 .PP
193 .B [DllOverrides]
194 .br
195 .I format: """modulename""=""native,builtin"""
196 .br
197 .I modulename
198 can be any valid DLL module name. If no extension is specified .dll is
199 assumed. The specified value is a comma separated list of module-types
200 to try to load in that specific order. Case is not important and only
201 the first letter of each type is enough to identify the type n[ative]
202 or b[uiltin]. Also whitespace is ignored. See also the description of
203 the
204 .I WINEDLLOVERRIDES
205 environment variable in
206 .BR wine (1)
207 for details about the allowed types.
208 .br
209 The wildcard entry
210 .I """*"""
211 specifies the load order to use for modules not explicitly
212 mentioned. If the wildcard entry is not found, then the order
213 "native,builtin" is used.
214 .br
215 Examples:
216 .br
217 .I """kernel32""=""builtin"""
218 .br
219 .I """comdlg32""=""native,builtin"""
220 .br
221 .I """*""=""builtin,native"""
222 .br
223 When the specified module name does not contain a path, it matches
224 only dlls loaded from the Windows system directory. If the application
225 explicitly loads a dll from a different directory, it has to be
226 configured separately. This can be done either by specifying the full
227 path in the module name, or by using a path wildcard of the form
228 .I """*modulename""".
229 .br
230 For instance, the following will load the native shell32 when loaded
231 from C:\\Program Files, and the builtin when loaded from any other
232 directory:
233 .br
234 .I """C:\\\\\\\\Program Files\\\\\\\\shell32"" = ""native"""
235 .br
236 .I """*shell32"" = ""builtin"""
237 .br
238 Changing the load order of low-level dlls like kernel32, gdi32 or
239 user32 to anything other than builtin will cause wine to fail because
240 wine cannot use native versions for these libraries.
241 .br
242 Always make sure that you have some kind of strategy in mind when you start
243 fiddling with the current defaults and needless to say that you must know
244 what you are doing.
245 --debugmsg +loaddll might come in handy for experimenting with that stuff.
246 .PP
247 .B [serialports]
248 .br
249 .I format: """com[12345678]""=""<devicename>"""
250 .br
251 default: none
252 .br
253 Used to specify the devices which are used as COM1 - COM8.
254 .PP
255 .B [parallelports]
256 .br
257 .I format: """lpt[12345678]""=""<devicename>"""
258 .br
259 default: none
260 .br
261 Used to specify the devices which are used as LPT1 - LPT8.
262 .PP
263 .B [Debug]
264 .br
265 .I format: """SpyExclude""=""<message names separated by semicolons>"""
266 .br
267 default: none
268 .br
269 Used to specify which messages will be excluded from the logfile.
270 .PP
271 .I format: """SpyInclude""=""<message names separated by semicolons>"""
272 .br
273 default: none
274 .br Used to specify which messages will be included in the logfile.
275 .PP
276 .I format: """RelayFromExclude""=""<module names separated by semicolons>"""
277 .br
278 default: none
279 .br
280 Used to specify a set of modules whose calls are excluded from a relay debug log.
281 .PP
282 .I format: """RelayFromInclude""=""<module names separated by semicolons>"""
283 .br
284 default: include all modules
285 .br 
286 Used to specify the set of modules whose calls are included in a relay debug log.
287 .PP
288 .I format: """RelayExclude""=""<functions or dll.functions separated by semicolons>"""
289 .br
290 default: none
291 .br
292 Used to specify which functions will be excluded from a relay debug log.
293 .PP
294 .I format: """RelayInclude""=""<functions or dll.functions separated by semicolons>"""
295 .br
296 default: include all functions
297 .br 
298 Used to specify which functions will be included in a relay debug log.
299 .PP
300 .I format: """SnoopExclude""=""<functions or dll.functions separated by semicolons>"""
301 .br
302 default: none
303 .br 
304 Used to specify which functions will be excluded from the snoop debug log.
305 .PP
306 .I format: """SnoopInclude""=""<functions or dll.functions separated by semicolons>"""
307 .br
308 default: include all functions
309 .br 
310 Used to specify which functions will be included in the snoop debug log.
311 .PP
312 For Relay and Snoop <dllname>.* includes or excludes the whole dll. Exclude
313 entries have priority over Include entries.
314 .PP
315 .B [Tweak.Layout]
316 .br
317 .I format: """WineLook""=""<Win31|Win95|Win98>"""
318 .br
319 default: "Win31"
320 .br
321 Use Win95-like window displays or Win3.1-like window displays.
322 .PP
323 .B [Registry]
324 .br
325 .I format: """LoadGlobalRegistryFiles""=""<boolean>"""
326 .br
327 Global registries (stored in /etc)
328 .PP
329 .I format: """LoadHomeRegistryFiles""=""<boolean>"""
330 .br
331 Home registries (stored in ~user/.wine/)
332 .PP
333 .I format: """WritetoHomeRegistryFiles""=""<boolean>"""
334 .br
335 TRY to write all changes to the home registry files
336 .PP
337 .I format: """LoadWindowsRegistryFiles""=""<boolean>"""
338 .br
339 Load Windows registry from the current Windows directory.
340 .PP
341 booleans: Y/y/T/t/1 are true, N/n/F/f/0 are false.
342 .br
343 Defaults are read all, write to home files.
344 .PP
345 .B [Network]
346 .br
347 .I format: """UseDnsComputerName""=""<boolean>"""
348 .br
349 If Y, always override the registry setting for ComputerName
350 with the Unix hostname.
351 .PP
352 .B [AppDefaults\\\\\\\\<appname>\\\\\\\\...]
353 .PP
354 This section allows specifying application-specific values for
355 the other sections described above.
356 .I <appname>
357 is the name of the application exe file, without path. The "..."
358 should be replaced by the name of one of the above configuration
359 sections.
360 .br
361 Example:
362 .br
363 .I [AppDefaults\\\\\\\\sol.exe\\\\\\\\DllOverrides]
364 .br
365 .I """shell32""" = """native"""
366 .br
367 means that Solitaire will use "native" load order for the shell32
368 dll. All other applications will continue to use what was specified in
369 the general
370 .I DllOverrides
371 section.
372 .br
373 The only sections that support application-specific information at the
374 moment are
375 .I DllOverrides, dsound, Version
376 and
377 .I x11drv.
378 .br
379 Make sure to use double backslashes in the section name.
380 .PP
381 .SH SAMPLE CONFIGURATION FILE
382 A sample configuration file is distributed as
383 .B documentation/samples/config
384 in the Wine source distribution.
385 .SH FILES
386 .TP
387 .I ~/.wine/config
388 User-specific configuration file
389 .SH ENVIRONMENT VARIABLES
390 .TP
391 .I WINEPREFIX
392 Specifies the directory that contains the per-user
393 .I config
394 file, the registry files, and the wineserver socket. The default is
395 .I $HOME/.wine.
396 .SH "SEE ALSO"
397 .BR wine (1)