- always declare the lstr* functions, even if they're inline
[wine] / documentation / wine.man.in
1 .\" -*- nroff -*-
2 .TH WINE 1 "May 2004" "@PACKAGE_STRING@" "Windows On Unix"
3 .SH NAME
4 wine \- run Windows programs on Unix
5 .SH SYNOPSIS
6 .BI "wine " "program " "[arguments ... ]"
7 .br
8 .B wine --help
9 .br
10 .B wine --version
11 .PP
12 For instructions on passing arguments to Windows programs, please see the
13 .B
14 PROGRAM/ARGUMENTS
15 section of the man page.
16 .SH DESCRIPTION
17 .B wine
18 loads and runs the given program, where the program is a DOS, Windows
19 3.x, or Win32 executable (x86 binaries only).
20 .PP
21 For debugging wine, use
22 .B winedbg
23 instead.
24 .PP
25 For running CUI executables (Windows console programs), use
26 .B wineconsole
27 instead of
28 .B wine.
29 This will display all the output in a separate windows (this requires X11 to
30 run). Not using
31 .B wineconsole
32 for CUI programs will only provide very limited console support, and your
33 program might not function properly.
34 .PP
35 When invoked with
36 .B --help
37 or
38 .B --version
39 as the only argument,
40 .B wine
41 will simply print a small help message or its version respectively and exit.
42 .SH REQUIREMENTS AND INSTALLATION
43 Read the README file in the Wine source distribution and the
44 .BR wine.conf (5)
45 man page to know what Wine requires and how it is installed from
46 source.
47 .SH PROGRAM/ARGUMENTS
48 The program name may be specified in DOS format (
49 .I
50 C:\(rs\(rsWINDOWS\(rs\(rsSOL.EXE)
51 or in Unix format (
52 .I /msdos/windows/sol.exe
53 ).  You may pass arguments to the program being executed by adding them 
54 to the end of the command line invoking
55 .B wine
56 (such as: wine notepad C:\(rs\(rsTEMP\(rs\(rsREADME.TXT).
57 Note that you need to '\(rs' escape special characters (and spaces) when invoking Wine via
58 a shell, e.g.
59 .PP
60 wine C:\(rs\(rsProgram\(rs Files\(rs\(rsMyPrg\(rs\(rstest.exe
61 .PP
62 .SH ENVIRONMENT VARIABLES
63 .B wine
64 makes the environment variables of the shell from which
65 .B wine
66 is started accessible to the windows/dos processes started. So use the
67 appropriate syntax for your shell to enter environment variables you need.
68 .TP 
69 .I WINEPREFIX
70 If set, the content of this variable is taken as the name of the directory where
71 .B wine
72 stores its data (the default is 
73 .I $HOME/.wine
74 ). This directory is also used to identify the socket which is used to
75 communicate with the
76 .I wineserver.
77 All 
78 .B wine
79 processes using the same 
80 .B wineserver
81 (i.e.: same user) share certain things like registry, shared memory,
82 and config file.
83 By setting 
84 .I WINEPREFIX
85 to different values for different 
86 .B wine
87 processes, it is possible to run a number of truly independent 
88 .B wine
89 processes. 
90 .TP
91 .I WINESERVER
92 Specifies the path and name of the
93 .B wineserver
94 binary. If not set, Wine will try to load
95 .B @bindir@/wineserver,
96 and if this doesn't exist it will then look for a file named
97 "wineserver" in the path and in a few other likely locations.
98 .TP
99 .I WINELOADER
100 Specifies the path and name of the
101 .B wine
102 binary to use to launch new Windows processes. If not set, Wine will
103 try to load
104 .B @bindir@/wine,
105 and if this doesn't exist it will then look for a file named "wine" in
106 the path and in a few other likely locations.
107 .TP
108 .I WINEDEBUG
109 Turns debugging messages on or off. The syntax of the variable is
110 of the form
111 .RI [ class ][+/-] channel [,[ class2 ][+/-] channel2 ].
112 .RS +7
113 .PP
114 .I class
115 is optional and can be one of the following: 
116 .B err, warn, fixme,
117 or 
118 .B trace. 
119 If
120 .I class
121 is not specified, all debugging messages for the specified
122 channel are turned on.  Each channel will print messages about a particular
123 component of 
124 .B wine.  
125 The following character can be either + or - to switch the specified
126 channel on or off respectively.  If there is no
127 .I class
128 part before it, a leading + can be omitted. Note that spaces are not
129 allowed anywhere in the string.
130 .PP
131 Examples:
132 .TP
133 WINEDEBUG=warn+all
134 will turn on all warning messages (recommended for debugging).
135 .br
136 .TP
137 WINEDEBUG=warn+dll,+heap
138 will turn on DLL warning messages and all heap messages.  
139 .br
140 .TP
141 WINEDEBUG=fixme-all,warn+cursor,+relay
142 will turn off all FIXME messages, turn on cursor warning messages, and turn
143 on all relay messages (API calls).
144 .br 
145 .TP
146 WINEDEBUG=relay
147 will turn on all relay messages. For more control on including or excluding
148 functions and dlls from the relay trace look into the [Debug] section
149 of the wine configuration file.
150 .PP
151 For more information on debugging messages, see the
152 .I Running Wine
153 chapter of the Wine User Guide.
154 .RE
155 .TP
156 .I WINEDLLPATH
157 Specifies the path(s) in which to search for builtin dlls and Winelib
158 applications. This is a list of directories separated by ":". In
159 addition to any directory specified in
160 .I WINEDLLPATH,
161 Wine will also look in
162 .B @dlldir@.
163 .TP
164 .I WINEDLLOVERRIDES
165 Defines the override type and load order of dlls used in the loading
166 process for any dll. The default is set in the configuration
167 file. There are currently two types of libraries that can be loaded
168 into a process' address space: Native windows dlls (
169 .I native
170 ), 
171 .B wine 
172 internal dlls (
173 .I builtin
174 ). The type may be abbreviated with the first letter of the type (
175 .I n, b
176 ). Each sequence of orders must be separated by commas.
177 .RS
178 .PP
179 Each dll may have its own specific load order. The load order
180 determines which version of the dll is attempted to be loaded into the
181 address space. If the first fails, then the next is tried and so
182 on. Multiple libraries with the same load order can be separated with
183 commas. It is also possible to use specify different loadorders for
184 different libraries by separating the entries by ";".
185 .PP
186 The load order for a 16-bit dll is always defined by the load order of
187 the 32-bit dll that contains it (which can be identified by looking at
188 the symbolic link of the 16-bit .dll.so file). For instance if
189 ole32.dll is configured as builtin, storage.dll will be loaded as
190 builtin too, since the 32-bit ole32.dll contains the 16-bit
191 storage.dll.
192 .PP
193 Examples:
194 .TP
195 WINEDLLOVERRIDES="comdlg32,shell32=n,b"
196 .br
197 Try to load comdlg32 and shell32 as native windows dll first and try
198 the builtin version if the native load fails.
199 .TP
200 WINEDLLOVERRIDES="comdlg32,shell32=n;c:\(rs\(rsfoo\(rs\(rsbar\(rs\(rsbaz=b"
201 .br
202 Try to load the libraries comdlg32 and shell32 as native windows dlls. Furthermore, if 
203 an application request to load c:\(rsfoo\(rsbar\(rsbaz.dll load the builtin library baz. 
204 .TP
205 WINEDLLOVERRIDES="comdlg32=b,n;shell32=b;comctl32=n"
206 .br
207 Try to load comdlg32 as builtin first and try the native version if
208 the builtin load fails; load shell32 always as builtin and comctl32
209 always as native.
210 .RE
211 .TP
212 .I DISPLAY
213 Specifies the X11 display to use.
214 .SH FILES
215 .TP
216 .I @bindir@/wine
217 The 
218 .B wine 
219 program loader.
220 .TP
221 .I @bindir@/wineconsole
222 The 
223 .B wine 
224 program loader for CUI (console) applications.
225 .TP
226 .I @bindir@/wineserver
227 The 
228 .B wine 
229 server 
230 .TP 
231 .I @bindir@/winedbg
232 The 
233 .B wine 
234 debugger
235 .TP 
236 .I @dlldir@
237 Directory containing 
238 .B wine's
239 shared libraries 
240 .TP
241 .I $WINEPREFIX/config
242 User-specific configuration file, which must conform to the format specified
243 in the
244 .BR wine.conf (5)
245 man page. A sample configuration file is documentation/samples/config in the 
246 .B wine 
247 source archive.
248 .TP
249 .I $WINEPREFIX/dosdevices
250 Directory containing the DOS device mappings. Each file in that
251 directory is a symlink to the Unix device file implementing a given
252 device. For instance, if COM1 is mapped to /dev/ttyS0 you'd have a
253 symlink of the form $WINEPREFIX/dosdevices/com1 -> /dev/ttyS0.
254 .br
255 DOS drives are also specified with symlinks; for instance if drive D:
256 corresponds to the CDROM mounted at /mnt/cdrom, you'd have a symlink
257 $WINEPREFIX/dosdevices/d: -> /mnt/cdrom. The Unix device corresponding
258 to a DOS drive can be specified the same way, except with '::' instead
259 of ':'. So for the previous example, if the CDROM device is mounted
260 from /dev/hdc, the corresponding symlink would be
261 $WINEPREFIX/dosdevices/d:: -> /dev/hdc.
262 .SH AUTHORS
263 .B wine
264 is available thanks to the work of many developers. For a listing
265 of the authors, please see the file 
266 .B AUTHORS
267 in the top-level directory of the source distribution.
268 .SH COPYRIGHT
269 .B wine
270 can be distributed under the terms of the LGPL license. A copy of the
271 license is in the file
272 .B COPYING.LIB
273 in the top-level directory of the source distribution.
274 .SH BUGS
275 .PP
276 A status report on many applications is available from
277 .I http://appdb.winehq.org.
278 Please add entries to this list for applications you currently run.
279 .PP
280 Bug reports may be posted to Wine Bugzilla
281 .I http://bugs.winehq.org
282 If you want to post a bug report, please read the file
283 .I documentation/bugs.sgml
284 in the 
285 .B wine 
286 source to see what information is necessary
287 .PP
288 Problems and suggestions with this manpage please also report to
289 .I http://bugs.winehq.org
290 .SH AVAILABILITY
291 The most recent public version of 
292 .B wine
293 can be downloaded from
294 .I http://www.winehq.org/download
295 .PP
296 The latest snapshot of the code may be obtained via CVS.  For information
297 on how to do this, please see
298 .I
299 http://www.winehq.org/cvs
300 .PP
301 WineHQ, the
302 .B wine
303 development headquarters, is at
304 .I http://www.winehq.org.
305 This website contains a great deal of information about
306 .B wine.
307 .PP
308 For further information about 
309 .B wine
310 development, you might want to subscribe to the 
311 .B wine 
312 mailing lists at
313 .I http://www.winehq.org/forums
314
315 .SH "SEE ALSO"
316 .BR wine.conf (5)