wine/documentation/wine.man.in

.\" -*- nroff -*-
.TH WINE 1 "July 16, 1999" "Version 20000326" "Windows On Unix"
.SH NAME
wine \- run Windows programs on Unix
.SH SYNOPSIS
.BI "wine " "[wine_options] " "program " "[arguments ... ]"
.PP
For instructions on passing arguments to Windows programs, please see the 
.B
PROGRAM/ARGUMENTS
section of the man page.
.SH DESCRIPTION
.B wine
.I program
loads and runs the given program, where the program is a DOS, Windows 3.x,
or Win32 executable (x86 binaries only).
.PP
For debugging wine, use
.B winedbg
.I program
instead.
.PP
.B wine 
currently runs a growing list of applications written for Win3.1,
Win95, Win98, and Windows NT. Older, simpler applications work better than
newer, more complex ones.  A large percentage of the API has been implemented,
although there are still several major pieces of work left to do.
.SH REQUIREMENTS
.B wine
requires kernel-level threads to run. Currently, only Linux version 2.0
or later, FreeBSD-current or FreeBSD 3.0 or later, and Solaris x86
version 2.5 or later are supported. Other operating systems which support
kernel threads may be supported in the future.
.PP
Although Linux version 2.0 will mostly work, certain features (specifically
LDT sharing) required for properly supporting Win32 threads were not
implemented until kernel version 2.2. If you get consistent thread-related
crashes, you may want to upgrade to 2.2. Also, some bugs were fixed and
additional features were added late in the Linux 2.0.x series, so if you have
a very old Linux kernel, you may want to upgrade to at least the latest 2.0.x
release.
.PP
If you have FreeBSD, make sure you have the USER_LDT,
SYSVSHM, SYSVSEM, and SYSVMSG options turned on in your kernel. If you
are building 
.B wine 
on Solaris, you will most likely need to build wine with the GNU toolchain 
(gcc, gas, etc.)
.PP
.B X
must be installed.  To use 
.B wine's 
support for multithreaded applications, your X libraries must be reentrant.  
If you have libc6 (glibc2), or you 
compiled the X libraries yourself, they were probably compiled with the 
reentrant option enabled.  
.PP
.B libXpm
must be installed.  If you're using Red Hat, make sure the following
packages are installed: XFree86-devel, xpm, and xpm-devel. If you're
using Debian, the packages you need are xpm4g and xpm4g-dev. If you 
have some other distribution, please send a list of packages required
to the address listed in the 
.B
BUGS
section to get it included in this man page.
.PP
.B gcc
2.7.2 or later is required to build
.B wine.
Versions earlier than 2.7.2.3 may have problems when certain files are
compiled with optimization, often due to problems with header file
management.
.B
pgcc
currently doesn't work with 
.B wine.  
The cause of this problem is unknown. 
.PP
.B flex
version 2.5 or later and 
.B yacc
are required.  Bison can be used in replace of yacc. If you have Redhat
or Debian, make sure the bison and flex packages are installed.
.SH INSTALLATION
To install 
.B wine,
run "./configure" in the top-level directory of the source, which will 
detect your specific setup and create the Makefiles.  You can run 
"./configure --help" to see the available configuration options.  Then do 
"make depend && make" to build the
.B wine
executable, and then "make install" to install it. By default,
.B wine
is installed in the /usr/local/ hierarchy (current configuration has it in
the @prefix@ hierarchy); you can specify a different path with
the --prefix or --sysconfdir options when running
.B configure.
.PP
For more information, see the 
.I README
file contained in the source distribution.
.SH OPTIONS
.TP
.I --config filename
Use the named configuration file rather than the default
(@sysconfdir@/wine.conf or ~/.winerc).
.TP
.I --debugmsg [xxx]#name[,[xxx1]#name1][,<+|->relay=yyy1[:yyy2]]
Turn debugging messages on or off.  
.RS +7
.PP
xxx is optional and can be one of the following: 
.I err, 
.I warn, 
.I fixme, 
or 
.I trace. 
If xxx is not specified, all debugging messages for the specified
channel are turned on.  Each channel will print messages about a particular
component of 
.B wine.  
# is required and can be either + or -.  Note that 
there is not a space after the comma between names. yyy are either the
name of a whole DLL or a single API entry by Name you either
want to include or exclude from the relay listing. These names must be in
the case as names used in the relaylisting. You can do the same for snoop.
.PP
For instance:
.PP
.I --debugmsg warn+dll,+heap
will turn on DLL warning messages and all heap messages.  
.br
.I --debugmsg fixme-all,warn+cursor,+relay
will turn off all FIXME messages, turn on cursor warning messages, and turn
on all relay messages (API calls).
.br 
.I --debugmsg -relay=LeaveCriticalSection:EnterCriticalSection
will turn on all relay messages except for LeaveCriticalSection and
EnterCriticalSection.
.br 
.I --debugmsg +relay=ADVAPI32
will only turn on relay messages into the ADVAPI32 code.
.PP
The full list of names is: all, accel, advapi, animate, aspi, atom, avifile, bitblt,
bitmap, caret, cdrom, class, clipboard, clipping, combo, comboex, comm, commctrl,
commdlg, console, crtdll, cursor, datetime, dc, ddeml, ddraw, debug, debugstr, delayhlp, 
dialog, dinput, dll, dosfs, dosmem, dplay, driver, dsound, edit, elfdll, enhmetafile, 
event, exec, file, fixup, font, gdi, global, graphics, header, heap, hook, hotkey, 
icmp, icon, imagehlp, imagelist, imm, int, int10, int16, int17, int19, int21, int31,
io, ipaddress, joystick, key, keyboard, ldt, listbox, listview, local, mci, mcianim, 
mciavi, mcicda, mcimidi, mciwave, mdi, menu, message, metafile, midi, mmaux, mmio, 
mmsys, mmtime, module, monthcal, mpr, msacm, msg, msvideo, nativefont, nonclientntdll, 
odbc, ole, pager, palette, pidl, print, process, profile, progress, prop, propsheet, 
psapi, psdrv, ras, rebar, reg, region, relay, resource, scroll, segment, seh, selector,
sendmsg, server, setupx, shell, snoop, sound, static, statusbar, storage, stress, string, 
syscolor, system, tab, tape, tapi, task, text, thread, thunk, timer, toolbar, toolhelp, 
tooltips, trackbar, treeview, ttydrv, tweak, typelib, updown, ver, virtual, vxd, wave, 
win, win16drv, win32, winedbg, wing, winsock, winspool, wnet, x11 and x11drv.

.PP
For more information on debugging messages, see the file 
.I documentation/debug-msgs
in the source distribution.
.RE
.TP
.I --desktop geom
Use a desktop window of the given geometry, e.g. "640x480"
.TP
.I --display name
Use the specified X display
.TP
.I --dll name[,name[,...]]={native|elfdll|so|builtin}[,{n|e|s|b}[,...]][+...]
Selects the override type and load order of dll used in the loading process
for any dll. The default is set in @sysconfdir@/wine.conf or ~/.winerc. There
are currently four types of libraries that can be loaded into a process' address
space: Native windows dlls (
.I native
), ELF encapsulated windows dlls (
.I elfdll
), native ELF libraries (
.I so
)and 
.B wine 
internal dlls (
.I builtin
). The type may be abbreviated with the first letter of the type (
.I n, e, s, b
). Each sequence of orders must be separated by commas.
.br
Each dll may have its own specific load order. The load order determines
which verion of the dll is attempted to be loaded into the address space. If
the first fails, then the next is tried and so on. Different load orders can
be specified by separating the entries with a plus sign. Multiple libraries
with the same load order can be separated with commas. It is also possible to 
use the --dll option several times, to specify different loadorders for different
libraries
.br
Examples:
.br
.I --dll comdlg32,commdlg=n,b
.br
Try to load comdlg32 and commdlg as native windows dll first and try
the builtin version if the native load fails.
.br
.I --dll shell,shell32=n --dll c:\(rs\(rsfoo\(rs\(rsbar\(rs\(rsbaz=b
.br
Try to load the libraries shell and shell32 as native windows dlls. Furthermore, if 
an application request to load c:\(rsfoo\(rsbar\(rsbaz.dll load the builtin library baz. 
.br
.I --dll comdlg32,commdlg=e,n:shell,shell32=b+comctl32,commctrl=n
.br
Try to load comdlg32 and commdlg as elfdll first and try the native version
if the elfdll load fails; load shell32/shell always as builtin and
comctl32/commctrl always as native.
.br
Note: It is wise to keep dll pairs (comdlg32/commdlg, shell/shell32, etc.)
having exactly the same load order. This will prevent mismatches at runtime.
See also configuration file format below.
.TP
.I --dosver version
Specify the DOS version 
.B wine 
should imitate (e.g. 6.22) This option
is only valid when used in conjunction with --winver win31.
.TP
.I --language xx
Set the language to
.I xx
(one of Br, Ca, Cs, Cy, Da, De, En, Eo, Es, Fi, Fr, Ga, Gd, Gv, Hr,
Hu, It, Ko, Kw, No, Pl, Pt, Ru, Sk, Sv, Wa)
.TP
.I --managed
Create each top-level window as a properly managed X window instead of
creating our own "sticky" window.
.TP
.I --synchronous
Turn on synchronous display mode. Useful for debugging X11 graphics problems.
.TP
.I --winver version
Specify which Windows version 
.B wine 
should imitate.
Possible arguments are: win31, win95, nt351, and nt40.
.PD 1
.SH PROGRAM/ARGUMENTS
The program name may be specified in DOS format (
.I
C:\(rs\(rsWINDOWS\(rs\(rsSOL.EXE)
or in Unix format (
.I /msdos/windows/sol.exe
).  The program being executed may be passed arguments by adding them on 
to the end of the command line invoking
.B wine
(such as: wine notepad C:\(rs\(rsTEMP\(rs\(rsREADME.TXT). Command line processing goes as
follows: first 
.B wine
checks, if one or more of the above mentioned 
.B wine 
options have been specified. These
are removed from the command line, which is passed to the windows program. You can use
the Parameter 
.I -- 
to indicate, that 
.B wine 
should stop command line processing. This is needed, if a windows program understands 
a option, which is usually interpreted (and thus removed from the command line) 
by 
.B wine. 
For example, if you want to execute 
.B wine 
with the options 
.I --managed --config myapp.winerc
and if 
.B wine 
should run the program 
.I myapp.exe
with the arguments
.I --config my.ini somefile
, then you could use the following command line to invoke 
.B wine:
.PP
.I wine --managed --config myapp.winerc -- myapp.exe --config my.ini somefile
.PP 
Note that in contrast to previous versions of 
.B wine, 
you must not pass 
program name and program option in one argument to 
.B wine. 
To run more
that one windows program, just execute 
.B wine 
once with the name 
of each program as argument. 
.SH ENVIRONMENT VARIABLES
.B wine
makes the environment variables of the shell from which
.B wine
is started accessible to the windows/dos processes started. So use the
appropriate syntax for your shell to enter environment variables you need.
.TP 
.I WINEPREFIX
If set, the content of this variable is taken as the name of the directory, where
.B wine
stores its data (usually 
.I $HOME/.wine
). This directory contains also the socket, which is used to communicate with the
.I wineserver.
All 
.B wine
processes, using the same 
.B wineserver
share certain things like registry and shared memory. By setting 
.I WINEPREFIX
to different values for different 
.B wine
processes, it is possible to run a number of truly independent 
.B wine
processes. 

.SH CONFIGURATION FILE
.B wine
expects a configuration file (
.I @sysconfdir@/wine.conf
), which must conform to the format specified in the
.BR wine.conf (5)
man page. A sample configuration file is wine.ini in the base directory of the 
.B wine 
source archive. Alternatively a configuration file with the name
.I.winerc 
in the home directory of the user running 
.B wine 
can be used. The third option is to specify the name of the 
configuration file with the 
.B --config
option. 
.SH AUTHORS
.B wine
is available thanks to the work of many developers. For a listing
of the authors, please see the file 
.B AUTHORS
in the top-level directory of the source distribution.
.SH BUGS
.PP
A status report on many appplications is available from
.I http://www.winehq.com/Apps.
Please add entries to this list for applications you currently run.
.PP
Bug reports and successes may be posted to 
.I comp.emulators.ms-windows.wine.
If you want to post a bug report, please read the file
.I documentation/bugreports
in the 
.B wine 
source to see what information is necessary.
.PP
For problems and suggestions with this manpage, please send a note to
James Juran <jrj120@psu.edu>.
.SH AVAILABILITY
The most recent public version of 
.B wine
can be obtained via FTP from metalab.unc.edu or tsx-11.mit.edu in the 
/pub/linux/ALPHA/Wine/development directory.  The releases are in the 
format 'Wine-yyyymmdd.tar.gz', or 'Wine-yyyymmdd.diff.gz' for the diff's 
from the previous release.
.PP
The latest snapshot of the code may be obtained via CVS.  For information
on how to do this, please see
.I
http://www.winehq.com/dev.html
.PP
WineHQ, the
.B wine
development headquarters, is at
.I http://www.winehq.com/.
This website contains a great deal of information about
.B wine.
.PP
The
.B wine 
newsgroup is 
.I comp.emulators.ms-windows.wine.
It is used for discussion of various 
.B wine end user aspects/help.
.PP
For further information about 
.B wine development, you might want to
subscribe to the 
.B wine 
"cvs", "devel" and "patches" mailing lists at
.I http://www.winehq.com/dev.html#ml.
.SH FILES
.PD 0
.TP
.I @prefix@/bin/wine
The 
.B wine 
program loader.
.TP
.I @prefix@/bin/dosmod
The DOS program loader.
.TP
.I @prefix@/bin/wineserver
The 
.B wine 
server 
.TP 
.I @prefix@/bin/wineclpsrv
The 
.B wine 
clipboard server
.TP 
.I @prefix@/lib/
Directory containing 
.B wines's
shared libraries 
.TP
.I @sysconfdir@/wine.conf
Global configuration file for 
.B wine.
.TP
.I ~/.winerc
User-specific configuration file
.TP 
.I ~/.wine
Directory containing user specific data managed by 
.B wine. 
.TP
.I @prefix@/lib/wine.sym
Global symbol table (used in debugger)
.SH "SEE ALSO"
.BR wine.conf (5),
.BR clone (2)