1WINEDBG(1)                  Wine Developers Manual                  WINEDBG(1)
2
3
4

NAME

6       winedbg - Wine debugger
7

SYNOPSIS

9       winedbg [ options ] [ program_name [ program_arguments ] | wpid ]
10
11       winedbg --gdb [ options ] [ program_name [ program_arguments ] | wpid ]
12
13       winedbg --auto wpid
14
15       winedbg --minidump [ file.mdmp ] wpid
16
17       winedbg file.mdmp
18

DESCRIPTION

20       winedbg is a debugger for Wine. It allows:
21           + debugging native Win32 applications
22           + debugging Winelib applications
23           + being a drop-in replacement for Dr Watson
24

MODES

26       winedbg  can  be used in five modes.  The first argument to the program
27       determines the mode winedbg will run in.
28
29       default
30              Without any explicit mode, this is  standard  winedbg  operating
31              mode. winedbg will act as the front end for the user.
32
33       --gdb  winedbg  will  be used as a proxy for gdb. gdb will be the front
34              end for command handling, and winedbg will proxy  all  debugging
35              requests from gdb to the Win32 APIs.
36
37       --auto This  mode  is  used  when winedbg is set up in AeDebug registry
38              entry as the default debugger. winedbg will then  display  basic
39              information  about  a  crash. This is useful for users who don't
40              want to debug a crash, but rather  gather  relevant  information
41              about the crash to be sent to developers.
42
43       --minidump
44              This  mode  is similar to the --auto one, except that instead of
45              printing the information on the screen (as  --auto  does),  it's
46              saved  into  a  minidump  file.  The  name of the file is either
47              passed on the command line, or generated by WineDbg when none is
48              given.   This  file  could later on be reloaded into winedbg for
49              further examination.
50
51       file.mdmp
52              In this mode winedbg reloads the state of a debuggee  which  has
53              been saved into a minidump file. See either the minidump command
54              below, or the --minidump mode.
55
56

OPTIONS

58       When in default mode, the following options are available:
59
60       --command string
61              winedbg will execute the command string as if it  was  keyed  on
62              winedbg  command line, and then will exit. This can be handy for
63              getting the pid of running processes  (winedbg  --command  "info
64              proc").
65
66       --file filename
67              winedbg  will  execute  the  list  of commands contained in file
68              filename as if they were keyed on winedbg command line, and then
69              will exit.
70
71       When in gdb proxy mode, the following options are available:
72
73       --no-start
74              gdb  will not be automatically started. Relevant information for
75              starting gdb is printed on screen. This is somehow  useful  when
76              not  directly  using gdb but some graphical front-ends, like ddd
77              or kgbd.
78
79       --port port
80              Start the gdb server on the given port. If this  option  is  not
81              specified, a randomly chosen port will be used. If --no-start is
82              specified, the port used will be printed on startup.
83
84       --with-xterm
85              This will run gdb in its own xterm instead of using the  current
86              Unix console for textual display.
87
88       In  all  modes,  the  rest of the command line, when passed, is used to
89       identify which programs, if any, has to debugged:
90
91       program_name
92              This is the name of an executable to start for a debugging  ses‐
93              sion.   winedbg  will  actually  create a process with this exe‐
94              cutable. If programs_arguments are also given, they will be used
95              as arguments for creating the process to be debugged.
96
97       wpid   winedbg  will  attach  to the process which Windows pid is wpid.
98              Use the info proc command within winedbg to  list  running  pro‐
99              cesses and their Windows pids.
100
101       default
102              If nothing is specified, you will enter the debugger without any
103              run nor attached process. You'll have to do the job yourself.
104
105

COMMANDS

107   Default mode, and while reloading a minidump file:
108       Most of commands used in winedbg are similar  to  the  ones  from  gdb.
109       Please  refer  to the gdb documentations for some more details. See the
110       gdb differences section later on to get a list of variations  from  gdb
111       commands.
112
113       Misc. commands
114
115       abort  Aborts the debugger.
116
117       quit   Exits the debugger.
118
119       attach N
120              Attach  to a Wine process (N is its Windows ID, numeric or hexa‐
121              decimal).  IDs can be obtained using the  info process  command.
122              Note the info process command returns hexadecimal values
123
124       detach Detach from a Wine-process.
125
126       thread N
127              Change  the  current  thread  to  N (its Windows TID, numeric or
128              hexadecimal).
129
130       Help commands
131
132       help   Prints some help on the commands.
133
134       help info
135              Prints some help on info commands
136
137       Flow control commands
138
139       cont   Continue execution until next breakpoint or exception.
140
141       pass   Pass the exception event up to the filter chain.
142
143       step   Continue execution until next C line of  code  (enters  function
144              call)
145
146       next   Continue  execution  until  next  C  line of code (doesn't enter
147              function call)
148
149       stepi  Execute next assembly instruction (enters function call)
150
151       nexti  Execute next assembly instruction (doesn't enter function call)
152
153       finish Execute until return of current function is reached.
154
155       cont, step, next, stepi, nexti can be postfixed by a number (N),  mean‐
156       ing  that  the  command  must  be  executed  N  times before control is
157       returned to the user.
158
159       Breakpoints, watchpoints
160
161       enable N
162              Enables (break|watch)-point N
163
164       disable N
165              Disables (break|watch)-point N
166
167       delete N
168              Deletes (break|watch)-point N
169
170       cond N Removes any existing condition to (break|watch)-point N
171
172       cond N expr
173              Adds condition expr to (break|watch)-point N. expr will be eval‐
174              uated each time the (break|watch)-point is hit. If the result is
175              a zero value, the breakpoint isn't triggered.
176
177       break * N
178              Adds a breakpoint at address N
179
180       break id
181              Adds a breakpoint at the address of symbol id
182
183       break id N
184              Adds a breakpoint at the line N inside symbol id.
185
186       break N
187              Adds a breakpoint at line N of current source file.
188
189       break  Adds a breakpoint at current $PC address.
190
191       watch * N
192              Adds a watch command (on write) at address N (on 4 bytes).
193
194       watch id
195              Adds a watch command (on write) at the  address  of  symbol  id.
196              Size depends on size of id.
197
198       rwatch * N
199              Adds a watch command (on read) at address N (on 4 bytes).
200
201       rwatch id
202              Adds a watch command (on read) at the address of symbol id. Size
203              depends on size of id.
204
205       info break
206              Lists all (break|watch)-points (with their state).
207
208       You can use the symbol EntryPoint to stand for the entry point  of  the
209       Dll.
210
211       When setting a (break|watch)-point by id, if the symbol cannot be found
212       (for example, the symbol is contained in  a  not  yet  loaded  module),
213       winedbg  will  recall  the  name  of the symbol and will try to set the
214       breakpoint each time a new module is loaded (until it succeeds).
215
216       Stack manipulation
217
218       bt     Print calling stack of current thread.
219
220       bt N   Print calling stack of thread of ID N. Note: this doesn't change
221              the  position of the current frame as manipulated by the up & dn
222              commands).
223
224       up     Goes up one frame in current thread's stack
225
226       up N   Goes up N frames in current thread's stack
227
228       dn     Goes down one frame in current thread's stack
229
230       dn N   Goes down N frames in current thread's stack
231
232       frame N
233              Sets N as the current frame for current thread's stack.
234
235       info locals
236              Prints information  on  local  variables  for  current  function
237              frame.
238
239       Directory & source file manipulation
240
241       show dir
242              Prints the list of dirs where source files are looked for.
243
244       dir pathname
245              Adds pathname to the list of dirs where to look for source files
246
247       dir    Deletes the list of dirs where to look for source files
248
249       symbolfile pathname
250              Loads external symbol definition file pathname
251
252       symbolfile pathname N
253              Loads external symbol definition file pathname (applying an off‐
254              set of N to addresses)
255
256       list   Lists 10 source lines forwards from current position.
257
258       list - Lists 10 source lines backwards from current position
259
260       list N Lists 10 source lines from line N in current file
261
262       list pathname:N
263              Lists 10 source lines from line N in file pathname
264
265       list id
266              Lists 10 source lines of function id
267
268       list * N
269              Lists 10 source lines from address N
270
271       You can specify the end target (to change the 10 lines value) using the
272       ',' separator. For example:
273
274       list 123, 234
275              lists source lines from line 123 up to line 234 in current file
276
277       list foo.c:1,56
278              lists source lines from line 1 up to 56 in file foo.c
279
280       Displaying
281
282       A  display is an expression that's evaluated and printed after the exe‐
283       cution of any winedbg command.
284
285       display
286
287       info display
288              Lists the active displays
289
290       display expr
291              Adds a display for expression expr
292
293       display /fmt expr
294              Adds a display for expression expr. Printing evaluated  expr  is
295              done  using the given format (see print command for more on for‐
296              mats)
297
298       del display N
299
300       undisplay N
301              Deletes display N
302
303       Disassembly
304
305       disas  Disassemble from current position
306
307       disas expr
308              Disassemble from address expr
309
310       disas expr,expr
311              Disassembles code between addresses specified by the two expres‐
312              sions
313
314       Memory (reading, writing, typing)
315
316       x expr Examines memory at address expr
317
318       x /fmt expr
319              Examines memory at address expr using format fmt
320
321       print expr
322              Prints the value of expr (possibly using its type)
323
324       print /fmt expr
325              Prints the value of expr (possibly using its type)
326
327       set var = expr
328              Writes the value of expr in var variable
329
330       whatis expr
331              Prints the C type of expression expr
332
333       fmt    is either letter or count letter, where letter can be:
334
335           s      an ASCII string
336
337           u      a UTF16 Unicode string
338
339           i      instructions (disassemble)
340
341           x      32-bit unsigned hexadecimal integer
342
343           d      32-bit signed decimal integer
344
345           w      16-bit unsigned hexadecimal integer
346
347           c      character (only printable 0x20-0x7f are actually printed)
348
349           b      8-bit unsigned hexadecimal integer
350
351           g      Win32 GUID
352
353       Expressions
354
355       Expressions  in  Wine Debugger are mostly written in a C form. However,
356       there are a few discrepancies:
357
358           Identifiers can take a '!' in their names. This  allows  mainly  to
359           specify  a module where to look the ID from, e.g. USER32!CreateWin‐
360           dowExA.
361
362           In a cast operation, when specifying a structure or  a  union,  you
363           must  use  the struct or union keyword (even if your program uses a
364           typedef).
365
366       When specifying an identifier, if several symbols with this name exist,
367       the  debugger  will  prompt for the symbol you want to use. Pick up the
368       one you want from its number.
369
370       Misc.
371
372       minidump file.mdmp saves the debugging context of the debuggee  into  a
373       minidump file called file.mdmp.
374
375       Information on Wine internals
376
377       info class
378              Lists all Windows classes registered in Wine
379
380       info class id
381              Prints information on Windows class id
382
383       info share
384              Lists  all  the dynamic libraries loaded in the debugged program
385              (including .so files, NE and PE DLLs)
386
387       info share N
388              Prints information on module at address N
389
390       info regs
391              Prints the value of the CPU registers
392
393       info all-regs
394              Prints the value of the CPU and Floating Point registers
395
396       info segment
397              Lists all allocated segments (i386 only)
398
399       info segment N
400              Prints information on segment N (i386 only)
401
402       info stack
403              Prints the values on top of the stack
404
405       info map
406              Lists all virtual mappings used by the debugged program
407
408       info map N
409              Lists all virtual mappings used by the program of Windows pid N
410
411       info wnd
412              Displays the window hierarchy starting from the desktop window
413
414       info wnd N
415              Prints information of Window of handle N
416
417       info process
418              Lists all w-processes in Wine session
419
420       info thread
421              Lists all w-threads in Wine session
422
423       info frame
424              Lists the exception frames (starting from current stack  frame).
425              You can also pass, as optional argument, a thread id (instead of
426              current thread) to examine its exception frames.
427
428       Debug messages can be turned on and off as you are debugging using  the
429       set command, but only for channels initialized with the WINEDEBUG envi‐
430       ronment variable.
431
432       set warn + win
433              Turns on warn on win channel
434
435       set + win
436              Turns on warn/fixme/err/trace on win channel
437
438       set - win
439              Turns off warn/fixme/err/trace on win channel
440
441       set fixme - all
442              Turns off fixme class on all channels
443
444   Gdb mode:
445       See the gdb documentation for all the gdb commands.
446
447       However, a few Wine extensions are available, through the monitor  com‐
448       mand:
449
450       monitor wnd
451              Lists all windows in the Wine session
452
453       monitor proc
454              Lists all processes in the Wine session
455
456       monitor mem
457              Displays memory mapping of debugged process
458
459   Auto and minidump modes:
460       Since no user input is possible, no commands are available.
461
462

ENVIRONMENT

464       WINE_GDB
465              When  used  in  gdb proxy mode, WINE_GDB specifies the name (and
466              the path) of the executable to be used for gdb. "gdb" is used by
467              default.
468

AUTHORS

470       The first version was written by Eric Youngdale.
471
472       See Wine developers list for the rest of contributors.
473

BUGS

475       Bugs can be reported on the Wine bug tracker https://bugs.winehq.org⟩.
476

AVAILABILITY

478       winedbg  is  part  of the Wine distribution, which is available through
479       WineHQ, the Wine development headquarters https://www.winehq.org/⟩.
480

SEE ALSO

482       wine(1),
483       Wine documentation and support https://www.winehq.org/help⟩.
484
485
486
487Wine 4.21                        October 2005                       WINEDBG(1)
Impressum