Make the winehq.org domain the official one.
[wine] / documentation / wine.man.in
1 .\" -*- nroff -*-
2 .TH WINE 1 "May 2002" "@PACKAGE_STRING@" "Windows On Unix"
3 .SH NAME
4 wine \- run Windows programs on Unix
5 .SH SYNOPSIS
6 .BI "wine " "[wine_options] " "[--] " "program " "[arguments ... ]"
7 .PP
8 For instructions on passing arguments to Windows programs, please see the
9 .B
10 PROGRAM/ARGUMENTS
11 section of the man page.
12 .SH DESCRIPTION
13 .B wine
14 .I program
15 loads and runs the given program, where the program is a DOS, Windows 3.x,
16 or Win32 executable (x86 binaries only).
17 .PP
18 For debugging wine, use
19 .B winedbg
20 .I program
21 instead.
22 .PP
23 For running CUI executables (Windows console programs), use
24 .B wineconsole
25 instead of
26 .B wine
27 . This will display all the output in a separate windows (this requires X11 to
28 run). Not using
29 .B wineconsole
30 for CUI programs will only provide very limited console support, and your
31 program might not function properly.
32 .PP
33 .B wine 
34 currently runs a growing list of applications written for all kinds of
35 Windows versions >= Win2.0, e.g. Win3.1, Win95/98, NT.
36 Older, simpler applications work better than newer, more complex ones.
37 Using Windows ME or Win2000 components with Wine is more problematic than
38 using none at all or the ones from older Windows versions.
39 A large percentage of the API has been implemented,
40 although there are still several major pieces of work left to do.
41 .SH REQUIREMENTS AND INSTALLATION
42 Read the README file in the Wine source distribution and the wine.conf
43 man page to know what Wine requires and how it is installed from source.
44 .SH OPTIONS
45 .TP
46 .I --debugmsg [xxx]#name[,[xxx1]#name1]
47 Turn debugging messages on or off.  
48 .RS +7
49 .PP
50 xxx is optional and can be one of the following: 
51 .I err, 
52 .I warn, 
53 .I fixme, 
54 or 
55 .I trace. 
56 If xxx is not specified, all debugging messages for the specified
57 channel are turned on.  Each channel will print messages about a particular
58 component of 
59 .B wine.  
60 # is required and can be either + or -.  Note that 
61 there is not a space after the comma between names. yyy are either the
62 name of a whole DLL or a single API entry by name you either
63 want to include or exclude from the relay listing.  Case doesn't matter
64 for these.  You can do the same for snoop.
65 .PP
66 For instance:
67 .PP
68 .I --debugmsg warn+all
69 will turn on all warning messages (recommended for debugging)
70 .br
71 .I --debugmsg warn+dll,+heap
72 will turn on DLL warning messages and all heap messages.  
73 .br
74 .I --debugmsg fixme-all,warn+cursor,+relay
75 will turn off all FIXME messages, turn on cursor warning messages, and turn
76 on all relay messages (API calls).
77 .br 
78 .I --debugmsg +relay
79 will turn on all relay messages. For more control on including or excluding
80 functions and dlls look into the [Debug] section of the wine configuration file.
81 .PP
82 The full list of names is:
83 all, accel, advapi, animate, aspi, atom, avifile, bitblt, bitmap, caret,
84 cdrom, class, clipboard, clipping, combo, comboex, comm, commctrl, commdlg,
85 console, crtdll, cursor, datetime, dc, ddeml, ddraw, debug, debugstr,
86 delayhlp, dialog, dinput, dll, dosfs, dosmem, dplay, driver, dsound, edit,
87 elfdll, enhmetafile, event, exec, file, fixup, font, gdi, global, graphics,
88 header, heap, hook, hotkey, icmp, icon, imagehlp, imagelist, imm, int, int10,
89 int16, int17, int19, int21, int31, io, ipaddress, joystick, key, keyboard,
90 loaddll, ldt, listbox, listview, local, mci, mcianim, mciavi, mcicda, mcimidi,
91 mciwave, mdi, menu, message, metafile, midi, mmaux, mmio, mmsys, mmtime,
92 module, monthcal, mpr, msacm, msg, msvideo, nativefont, nonclient, ntdll,
93 odbc, ole, opengl, pager, palette, pidl, print, process, profile, progress, 
94 prop, propsheet, psapi, psdrv, ras, rebar, reg, region, relay, resource, 
95 richedit, scroll, segment, seh, selector, sendmsg, server, setupapi, 
96 setupx, shell, snoop, sound, static, statusbar, storage, stress, string, 
97 syscolor, system, tab, tape, tapi, task, text, thread, thunk, timer, toolbar,
98 toolhelp, tooltips, trackbar, treeview, ttydrv, tweak, typelib, updown, ver,
99 virtual, vxd, wave, win, win16drv, win32, winedbg, wing, wininet, winsock,
100 winspool, wnet, x11 and x11drv.
101
102 .PP
103 For more information on debugging messages, see the file 
104 .I documentation/running.sgml
105 in the source distribution (FIXME: outdated).
106 .RE
107 .PD 1
108 .SH PROGRAM/ARGUMENTS
109 The program name may be specified in DOS format (
110 .I
111 C:\(rs\(rsWINDOWS\(rs\(rsSOL.EXE)
112 or in Unix format (
113 .I /msdos/windows/sol.exe
114 ).  You may pass arguments to the program being executed by adding them 
115 to the end of the command line invoking
116 .B wine
117 (such as: wine notepad C:\(rs\(rsTEMP\(rs\(rsREADME.TXT).
118 Note that you need to '\(rs' escape special characters (and spaces) when invoking Wine via
119 a shell, e.g.
120 .PP
121 wine C:\(rs\(rsProgram\(rs Files\(rs\(rsMyPrg\(rs\(rstest.exe
122 .PP
123 Command line processing goes as
124 follows: first 
125 .B wine
126 checks whether one or more of the above mentioned 
127 .B wine 
128 options have been specified. These
129 are removed from the command line, which is passed to the windows program. You can use
130 the parameter 
131 .I -- 
132 to indicate that 
133 .B wine 
134 should stop command line processing. This is needed in case a windows program understands 
135 an option that is usually interpreted (and thus removed from the command line) 
136 by 
137 .B wine. 
138 For example, if you want to execute 
139 .B wine 
140 with the options 
141 .I --debugmsg +module
142 and if 
143 .B wine 
144 should run the program 
145 .I myapp.exe
146 with the arguments
147 .I --display 3d somefile
148 , then you could use the following command line to invoke 
149 .B wine:
150 .PP
151 .I wine --debugmsg +module -- myapp.exe --display 3d somefile
152 .PP 
153 Note that in contrast to previous versions of 
154 .B wine, 
155 you must not pass 
156 program name and program option in one argument to 
157 .B wine. 
158 To run more
159 than one windows program, just execute 
160 .B wine 
161 once with the name of each program as argument. 
162 .SH ENVIRONMENT VARIABLES
163 .B wine
164 makes the environment variables of the shell from which
165 .B wine
166 is started accessible to the windows/dos processes started. So use the
167 appropriate syntax for your shell to enter environment variables you need.
168 .TP 
169 .I WINEPREFIX
170 If set, the content of this variable is taken as the name of the directory where
171 .B wine
172 stores its data (the default is 
173 .I $HOME/.wine
174 ). This directory contains also the socket, which is used to communicate with the
175 .I wineserver.
176 All 
177 .B wine
178 processes using the same 
179 .B wineserver
180 (i.e.: same user) share certain things like registry, shared memory,
181 and config file.
182 By setting 
183 .I WINEPREFIX
184 to different values for different 
185 .B wine
186 processes, it is possible to run a number of truly independent 
187 .B wine
188 processes. 
189 .TP
190 .I WINESERVER
191 Specifies the path and name of the
192 .B wineserver
193 binary. If not set, Wine will try to load
194 .B @bindir@/wineserver,
195 and if this doesn't exist it will then look for a file named
196 "wineserver" in the path and in a few other likely locations.
197 .TP
198 .I WINELOADER
199 Specifies the path and name of the
200 .B wine
201 binary to use to launch new Windows processes. If not set, Wine will
202 try to load
203 .B @bindir@/wine,
204 and if this doesn't exist it will then look for a file named "wine" in
205 the path and in a few other likely locations.
206 .TP
207 .I WINEDLLPATH
208 Specifies the path(s) in which to search for builtin dlls and Winelib
209 applications. This is a list of directories separated by ":". In
210 addition to any directory specified in
211 .I WINEDLLPATH,
212 Wine will also look in
213 .B @dlldir@.
214 .TP
215 .I WINEDLLOVERRIDES
216 Defines the override type and load order of dlls used in the loading
217 process for any dll. The default is set in the configuration
218 file. There are currently two types of libraries that can be loaded
219 into a process' address space: Native windows dlls (
220 .I native
221 ), 
222 .B wine 
223 internal dlls (
224 .I builtin
225 ). The type may be abbreviated with the first letter of the type (
226 .I n, b
227 ). Each sequence of orders must be separated by commas.
228 .br
229 Each dll may have its own specific load order. The load order
230 determines which version of the dll is attempted to be loaded into the
231 address space. If the first fails, then the next is tried and so
232 on. Multiple libraries with the same load order can be separated with
233 commas. It is also possible to use specify different loadorders for
234 different libraries by separating the entries by ";".
235 .br
236 Examples:
237 .RS
238 .TP
239 WINEDLLOVERRIDES="comdlg32,commdlg=n,b"
240 .br
241 Try to load comdlg32 and commdlg as native windows dll first and try
242 the builtin version if the native load fails.
243 .TP
244 WINEDLLOVERRIDES="shell,shell32=n;c:\(rs\(rsfoo\(rs\(rsbar\(rs\(rsbaz=b"
245 .br
246 Try to load the libraries shell and shell32 as native windows dlls. Furthermore, if 
247 an application request to load c:\(rsfoo\(rsbar\(rsbaz.dll load the builtin library baz. 
248 .TP
249 WINEDLLOVERRIDES="comdlg32,commdlg=b,n;shell,shell32=b;comctl32,commctrl=n"
250 .br
251 Try to load comdlg32 and commdlg as builtin first and try the native version
252 if the builtin load fails; load shell32/shell always as builtin and
253 comctl32/commctrl always as native.
254 .br
255 Note: It is wise to keep dll pairs (comdlg32/commdlg, shell/shell32, etc.)
256 having exactly the same load order. This will prevent mismatches at runtime.
257 See also configuration file format below.
258 .RE
259 .TP
260 .I DISPLAY
261 Specifies the X11 display to use.
262 .SH CONFIGURATION FILE
263 .B wine
264 expects a configuration file (
265 .I $WINEPREFIX/config
266 or
267 .I ~/.wine/config
268 if WINEPREFIX is not set), which must conform to the format specified
269 in the
270 .BR wine.conf (5)
271 man page. A sample configuration file is documentation/samples/config in the 
272 .B wine 
273 source archive.
274 .SH AUTHORS
275 .B wine
276 is available thanks to the work of many developers. For a listing
277 of the authors, please see the file 
278 .B AUTHORS
279 in the top-level directory of the source distribution.
280 .SH COPYRIGHT
281 .B wine
282 can be distributed under the terms of the LGPL license. A copy of the
283 license is in the file
284 .B LICENSE
285 in the top-level directory of the source distribution.
286 .SH BUGS
287 .PP
288 A status report on many applications is available from
289 .I http://www.winehq.org/Apps.
290 Please add entries to this list for applications you currently run.
291 .PP
292 Bug reports may be posted to Wine Bugzilla
293 .I http://bugs.winehq.org
294 If you want to post a bug report, please read the file
295 .I documentation/bugs.sgml
296 in the 
297 .B wine 
298 source to see what information is necessary
299 .PP
300 Problems and suggestions with this manpage please also report to
301 .I http://bugs.winehq.org
302 .SH AVAILABILITY
303 The most recent public version of 
304 .B wine
305 can be obtained via FTP from ibiblio.org in the
306 /pub/Linux/ALPHA/Wine/development directory.  The releases are in the
307 format 'Wine-yyyymmdd.tar.gz', or 'Wine-yyyymmdd.diff.gz' for the
308 diff's from the previous release. The same directory holds the
309 pre-built contents of the documentation in various formats
310 (wine-doc.xxx.gz).
311 .PP
312 The latest snapshot of the code may be obtained via CVS.  For information
313 on how to do this, please see
314 .I
315 http://www.winehq.org/development/
316 .PP
317 WineHQ, the
318 .B wine
319 development headquarters, is at
320 .I http://www.winehq.org/.
321 This website contains a great deal of information about
322 .B wine.
323 .PP
324 The
325 .B wine 
326 newsgroup is 
327 .I comp.emulators.ms-windows.wine.
328 It is used for discussion of various 
329 .B wine end user aspects/help.
330 .PP
331 For further information about 
332 .B wine
333 development, you might want to subscribe to the 
334 .B wine 
335 mailing lists at
336 .I http://www.winehq.org/development/#ml
337 .SH FILES
338 .PD 0
339 .TP
340 .I @bindir@/wine
341 The 
342 .B wine 
343 program loader.
344 .TP
345 .I @bindir@/wineconsole
346 The 
347 .B wine 
348 program loader for CUI (console) applications.
349 .TP
350 .I @bindir@/wineserver
351 The 
352 .B wine 
353 server 
354 .TP 
355 .I @bindir@/winedbg
356 The 
357 .B wine 
358 debugger
359 .TP 
360 .I @bindir@/wineclipsrv
361 The 
362 .B wine 
363 clipboard server
364 .TP 
365 .I @dlldir@
366 Directory containing 
367 .B wine's
368 shared libraries 
369 .TP
370 .I ~/.wine/config
371 User-specific configuration file
372 .TP 
373 .I ~/.wine
374 Directory containing user specific data managed by 
375 .B wine. 
376
377 .SH "SEE ALSO"
378 .BR wine.conf (5)