Debug

slackner edited this page Apr 19, 2015 · 3 revisions

Debug Output

Wine consists of a lot of different modules and provides ways to control debug output for each of the modules independently. In order to enable or disable the debug output for one these debug channels, you need to set the WINEDEBUG environment variable while starting a program. The WINEDEBUG variable needs to be specified in the following format:

WINEDEBUG=[+process:][class]+channel,[-process:][class]-channel,...

You need to specify at least the channel for which you would like to change the debug level. This usually matches the name of a dll provided by Wine, but there are also exceptions (see list at the end of the page). If you want to see all debug messages from ntdll, you would use the following line:

WINEDEBUG=+ntdll wine test.exe

In order to suppress all messages by ntdll you would simply use '-' instead of '+':

WINEDEBUG=-ntdll wine test.exe

Besides turning off/on all debug messages, you can also control different classes of debug levels. The supported classes are:

  • err (critical errors, turned ON by default)
  • fixme (warnings about unimplemented features, turned ON by default)
  • warn (non critical errors, turned OFF by default)
  • trace (all functions calls, turned OFF by default)

In case you want to see all warnings from ntdll (additionally to errors and fixmes), you could use the following line:

WINEDEBUG=warn+ntdll wine test.exe

Wine Staging also provides a way to control the debug settings for each (child) process independently. This is especially useful if you want to debug a game which needs to be started by a launcher or programs like Uplay. The following line will disable the debug output for all programs for which the executable image filename does not match game.exe:

WINEDEBUG=-game.exe:-all wine launcher.exe

If you also want to turn on relay for the game, you can use the following command line:

WINEDEBUG=-game.exe:-all,+game.exe:+relay wine launcher.exe

Usually you would write the debug messages into a file as the output can get quite big depending on the enabled debug channels. Several hundred megabytes or multiple gigabytes are not unusual when +relay is enabled for example. Another problem you may encounter are overlapped debug messages when a program uses multiple threads or sub processes. You can prevent this by using the append mode in the following way:

WINEDEBUG=... wine game.exe >> debug.log 2>&1

Now you should know everything required to create proper debug logs.

Debug Channels

As mentioned earlier the possible debug channels usually match the name of the dlls provided by Wine, but there are also exceptions and special debug channels. Those special debug channels do not control a single module but affect all modules or all debug messages. The most important ones are:

  • tid prints the thread id before all debug messages
  • timestamp prints the timestamp in front of all debug messages
  • relay prints all functions calls to wine dlls and their return values
  • seh show more detailed information about exceptions

You should use +tid if you are debugging multiple threads or processes and it generally doesn't hurt to enable it all the time. If you are searching for a bug and don't have a clue what is going wrong, the +relay channel might be useful. It prints a lot of information about all regular function calls and will often also contain a hint where the problem might be, but you should be aware that calls to COM interfaces are not logged with this method. You will for example not be able to find an error in d3d9 interfaces this way.

The +seh channel prints information about exceptions like invalid memory accesses. You should always take a look at it if the application crashes, especially when the application catches the exception and shows it's own crash dialog.

You can find more information about this special debug channels in the WineHQ Wiki.

Here is a list with all debug channels supported by Wine Staging:

accel acledit aclui actctx
activeds actxprxy adpcm advapi
advpack alsa amstream animate
appbar apphelp appwizcpl asmshader
aspi atl atom authz
avicap avifile avrt bcrypt
bidi bitblt bitmap browseui
button bytecodewriter cabinet capi
cards caret cdrom chain
class clipboard clipping clusapi
combase combo comboex comm
commctrl commdlg compstui computername
comsvcs connect console context
coreaudio cred credui crtdll
crypt cryptasn cryptdlg cryptdll
cryptext cryptnet cryptui ctapi32
cursor d2d d3d d3d10
d3d10core d3d11 d3d8 d3d9
d3d_bytecode d3dcompiler d3d_constants d3d_decl
d3d_draw d3d_perf d3drm d3d_shader
d3d_surface d3d_synchronous d3d_texture d3dx
d3dxof d3dxof_dump d3dxof_parsing datetime
dbgeng dbghelp dbghelp_coff dbghelp_dwarf
dbghelp_macho dbghelp_msc dbghelp_stabs dbghelp_symt
dc dciman ddeml ddraw
ddrawex debug_buffer debugstr devenum
dhcpcsvc dialog dib difxapi
dinput display dll dma
dmband dmcompos dmdump dmfile
dmfileraw dmime dmloader dmobj
dmscript dmstyle dmsynth dmusic
dmusic32 dnsapi dosmem dpa
dplay dpnet dpnhpast dpvoice
dragdrop driver drmclien dsa
dsound dsound3d dssenh dswave
dwmapi dwrite dxdiag dxgi
dxva2 eax edit enhmetafile
environ event eventlog exec
explorerframe faultrep file fixup
fltlib fltmgr font fontcache
fontsub fps fusion fwpuclnt
g711 gameux gdi gdiplus
gecko gl_compat global globalmem
glu gpkcsp graphics gsm
gstreamer handle header heap
hid hlink hlsl_parser hnetcfg
hook hotkey htmlhelp httpapi
iccvid icm icmp icon
ieframe image imagehlp imagelist
imm imports inetcomm inetcpl
inetmib1 infosoft initpki inkobj
inseng int int21 int31
io ipaddress iphlpapi itircl
itss joycpl joystick jpeg
jscript jscript_disas jsproxy key
keyboard ktmw32 listbox listview
loaddll loadperf local localspl
localui lsa macdrv mapi
mapistub mci mciavi mcicda
mcimidi mciqtz mciwave mdi
menu message metafile mfplat
mgmtapi midi mlang mmaux
mmc mmdevapi mmio mmsys
mmtime module monthcal mountmgr
mpeg3 mpr mprapi msacm
mscat mscms mscoree msctf
msdmo msftedit msg msgbox
mshtml msi msidb msident
msimg32 msimtf msisip msisys
msls31 msnet mspatcha msrle32
mssign mssip32 mstask msvcirt
msvcm msvcp msvcrt msvidc32
msvideo mswsock msxml nativefont
nddeapi ndis netapi32 netbios
netcfgx netprofm newdev nls
nonclient normaliz nstc ntdll
ntdsapi ntlm ntoskrnl ntprint
nvapi nvcuda nvcuvid nvencodeapi
objsel odbc ole oleacc
oledb oledlg olemalloc olepicture
olerelay olethk32 openal32 opencl
opengl oss packager pager
palette parsed_shader pdh pidgen
pidl powermgnt powrprof print
printui prntvpt process profile
progress propsheet propsys psdrv
pstores pulse qcap qcap_v4l
qedit qmgr qtdatahandler qtdecoder
qtsplitter quartz query ras
rasdlg rebar recyclebin reg
regapi region relay resource
resutils richedit richedit_check richedit_lists
richedit_style rpc rstrtmgr rtutils
samlib sblaster scarddlg sccbase
schannel schedsvc scroll scrrun
scsiport secur32 seh selector
sensapi server service setupapi
sfc shdocvw shell shlctrl
slbcsp slc snmpapi snoop
sound spoolss static statusbar
sti storage stress string
strmbase strmbase_qc svrapi sxs
sync synchronous syslevel syslink
system systray t2embed tab
tape tapi task taskschd
text theme_button theme_scroll theming
themingcombo thread threadpool thunk
tid time timestamp toolbar
toolhelp tooltips trackbar traffic
trash treeview twain typelib
uniscribe updown updspapi url
urlmon usbd user userenv
uxtheme variant vbscript vbscript_disas
vcomp vcomp100 vcomp90 vdmdbg
ver virtual volume vssapi
vxd wave wavemap wbemdisp
wbemprox webservices wer wevtapi
wgl wia win wincodecs
winediag winemapi wing winhttp
wininet winmm winscard winsock
winspool winsta winstation wintab
wintab32 wintrust wlanapi wldap32
wmiutils wmp wmvcore wnet
wpcap wshom wsnmp32 wtsapi
wuapi wuaueng x11drv x11settings
xapofx xaudio2 xdg xdnd
xim xinput xmllite xolehlp
xrandr xrender xvidmode