/
sosdocs.txt
2687 lines (2174 loc) · 105 KB
/
sosdocs.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
-------------------------------------------------------------------------------
NOTE: THIS FILE CONTAINS SOS DOCUMENTATION. THE FORMAT OF THE FILE IS:
<optional comments>
COMMAND: <cmd name, all lower case>
<descriptive text of the command>
\\ <these are two backslashes, immediately followed by a newline>
<repeat the sequence above>
The first command is "contents" which is the general help screen. The rest
correspond to SOS command names. This file is embedded as a resource in the SOS
binary. Be sure to list any new commands here.
-------------------------------------------------------------------------------
COMMAND: contents.
SOS is a debugger extension DLL designed to aid in the debugging of managed
programs. Functions are listed by category, then roughly in order of
importance. Shortcut names for popular functions are listed in parenthesis.
Type "!soshelp <functionname>" for detailed info on that function.
Object Inspection Examining code and stacks
----------------------------- -----------------------------
DumpObj (do) Threads (clrthreads)
DumpALC (dumpalc) ThreadState
DumpArray (da) IP2MD
DumpDelegate U
DumpStackObjects (dso) DumpStack
DumpHeap EEStack
DumpVC ClrStack
GCRoot GCInfo
ObjSize EHInfo
FinalizeQueue BPMD (bpmd)
PrintException (pe) COMState
TraverseHeap
Examining CLR data structures Diagnostic Utilities
----------------------------- -----------------------------
DumpDomain VerifyHeap
EEHeap VerifyObj
Name2EE FindRoots
SyncBlk HeapStat
DumpMT GCWhere
DumpClass ListNearObj (lno)
DumpMD GCHandles
Token2EE GCHandleLeaks
EEVersion FinalizeQueue (fq)
DumpModule FindAppDomain
ThreadPool (tp) SaveModule
DumpAssembly ProcInfo
DumpSigElem StopOnException (soe)
DumpRuntimeTypes DumpLog
DumpSig VMMap
RCWCleanupList VMStat
DumpIL MinidumpMode
DumpRCW AnalyzeOOM (ao)
DumpCCW SuppressJitOptimization
Examining the GC history Other
----------------------------- -----------------------------
HistInit SetHostRuntime (sethostruntime)
HistRoot SetSymbolServer (setsymbolserver)
HistObj SetClrPath (setclrpath)
HistObjFind SOSFlush (sosflush)
HistClear SOSStatus (sosstatus)
FAQ
Help (soshelp)
\\
COMMAND: faq.
>> How to install or update SOS? SOS is in the extension gallery and is automatically
loaded when the coreclr.dll is loaded in the target process. If the SOS isn't loaded
or a old version is loaded execute:
".update sos"
".load sos"
>> I have a chicken and egg problem. I want to use SOS commands, but the coreclr
isn't loaded yet. What can I do?
In the debugger at startup you can type:
"sxe clrn"
Let the program run, and it will stop with the notice
"CLR notification: module 'mscorlib' loaded"
At this time you can use SOS commands. To turn off spurious notifications,
type:
"sxd clrn"
>> I got the following error message. Now what?
0:000> .loadby sos coreclr
0:000> !DumpStackObjects
Failed to find runtime DLL (coreclr.dll), 0x80004005
Extension commands need coreclr.dll in order to have something to do.
0:000>
This means that the coreclr is not loaded yet, or has been unloaded. You need to
wait until your managed program is running in order to use these commands. If
you have just started the program a good way to do this is to type
bp clr!EEStartup "g @$ra"
in the debugger, and let it run. After the function EEStartup is finished,
there will be a minimal managed environment for executing SOS commands.
>> I have a partial memory minidump, and !DumpObj doesn't work. Why?
In order to run SOS commands, many CLR data structures need to be traversed.
When creating a minidump without full memory, special functions are called at
dump creation time to bring those structures into the minidump, and allow a
minimum set of SOS debugging commands to work. At this time, those commands
that can provide full or partial output are:
ClrStack
Threads
Help
PrintException
EEVersion
For a minidump created with this minimal set of functionality in mind, you
will get an error message when running any other commands. A full memory dump
(obtained with ".dump /ma <filename>" in the Windows Debugger) is often the
best way to debug a managed program at this level.
>> What other tools can I use to find my bug?
Turn on Managed Debugging Assistants. These enable additional runtime diagnostics,
particularly in the area of PInvoke/Interop. Adam Nathan has written some great
information about that:
http://blogs.msdn.com/adam_nathan/
>> Does SOS support DML?
Yes. SOS respects the .prefer_dml option in the debugger. If this setting is
turned on, then SOS will output DML by default. Alternatively, you may leave
it off and add /D to the beginning of a command to get DML based output for it.
Not all SOS commands support DML output.
\\
COMMAND: soe.
COMMAND: stoponexception.
!StopOnException [-derived]
[-create | -create2]
<Exception>
[<Pseudo-register number>]
!StopOnException helps when you want the Windows Debugger to stop on a
particular managed exception, say a System.OutOfMemoryException, but continue
running if other exceptions are thrown. The command can be used in two ways:
1) When you just want to stop on one particular CLR exception
At the debugger prompt, anytime after loading SOS, type:
!StopOnException -create System.OutOfMemoryException 1
The pseudo-register number (1) indicates that SOS can use register $t1 for
maintaining the breakpoint. The -create parameter allows SOS to go ahead
and set up the breakpoint as a first-chance exception. -create2 would set
it up as a 2nd-chance exception.
2) When you need more complex logic for stopping on a CLR exception
!StopOnException can be used purely as a predicate in a larger expression.
If you type:
!StopOnException System.OutOfMemoryException 3
then register $t3 will be set to 1 if the last thrown exception on the
current thread is a System.OutOfMemoryException. Otherwise, $t3 will be set
to 0. Using the Windows Debugger scripting language, you could chain
such calls together to stop on various exception types. You'll have to
manually create such predicates, for example:
sxe -c "!soe System.OutOfMemoryException 3;
!soe -derived System.IOException 4;
.if(@$t3==1 || @$t4==1) { .echo 'stop' } .else {g}"
The -derived option will cause StopOnException to set the pseudo-register to
1 even if the thrown exception type doesn't exactly match the exception type
given, but merely derives from it. So, "-derived System.Exception" would catch
every exception in the System.Exception heirarchy.
The pseudo-register number is optional. If you don't pass a number, SOS will
use pseudo-register $t1.
Note that !PrintException with no parameters will print out the last thrown
exception on the current thread (if any). You can use !soe as a shortcut for
!StopOnException.
\\
COMMAND: minidumpmode.
!MinidumpMode <0 or 1>
Minidumps created with ".dump /m" or ".dump" have a very small set of
CLR-specific data, just enough to run a subset of SOS commands correctly. You
are able to run other SOS commands, but they may fail with unexpected errors
because required areas of memory are not mapped in or only partially mapped
in. At this time, SOS cannot reliably detect if a dump file is of this type
(for one thing, custom dump commands can map in additional memory, but there
is no facility to read meta-information about this memory). You can turn this
option on to protect against running unsafe commands against small minidumps.
By default, MinidumpMode is 0, so there is no restriction on commands that will
run against a minidump.
\\
COMMAND: do.
COMMAND: dumpobj.
!DumpObj [-nofields] <object address>
This command allows you to examine the fields of an object, as well as learn
important properties of the object such as the EEClass, the MethodTable, and
the size.
You might find an object pointer by running !DumpStackObjects and choosing
from the resultant list. Here is a simple object:
0:000> !DumpObj a79d40
Name: Customer
MethodTable: 009038ec
EEClass: 03ee1b84
Size: 20(0x14) bytes
(C:\pub\unittest.exe)
Fields:
MT Field Offset Type VT Attr Value Name
009038ec 4000008 4 Customer 0 instance 00a79ce4 name
009038ec 4000009 8 Bank 0 instance 00a79d2c bank
Note that fields of type Customer and Bank are themselves objects, and you can
run !DumpObj on them too. You could look at the field directly in memory using
the offset given. "dd a79d40+8 l1" would allow you to look at the bank field
directly. Be careful about using this to set memory breakpoints, since objects
can move around in the garbage collected heap.
What else can you do with an object? You might run !GCRoot, to determine what
roots are keeping it alive. Or you can find all objects of that type with
"!DumpHeap -type Customer".
The column VT contains the value 1 if the field is a valuetype structure, and
0 if the field contains a pointer to another object. For valuetypes, you can
take the MethodTable pointer in the MT column, and the Value and pass them to
the command !DumpVC.
The abbreviation !do can be used for brevity.
The arguments in detail:
-nofields: do not print fields of the object, useful for objects like
String
\\
COMMAND: da.
COMMAND: dumparray.
!DumpArray
[-start <startIndex>]
[-length <length>]
[-details]
[-nofields]
<array object address>
This command allows you to examine elements of an array object.
The arguments in detail:
-start <startIndex>: optional, only supported for single dimension array.
Specify from which index the command shows the elements.
-length <length>: optional, only supported for single dimension array.
Specify how many elements to show.
-details: optional. Ask the command to print out details
of the element using !DumpObj and !DumpVC format.
-nofields: optional, only takes effect when -details is used. Do
not print fields of the elements. Useful for arrays of
objects like String
Example output:
0:000> !dumparray -start 2 -length 3 -details 00ad28d0
Name: Value[]
MethodTable: 03e41044
EEClass: 03e40fc0
Size: 132(0x84) bytes
Array: Rank 1, Number of elements 10, Type VALUETYPE
Element Type: Value
[2] 00ad28f0
Name: Value
MethodTable 03e40f4c
EEClass: 03ef1698
Size: 20(0x14) bytes
(C:\bugs\225271\arraytest.exe)
Fields:
MT Field Offset Type Attr Value Name
5b9a628c 4000001 0 System.Int32 instance 2 x
5b9a628c 4000002 4 System.Int32 instance 4 y
5b9a628c 4000003 8 System.Int32 instance 6 z
[3] 00ad28fc
Name: Value
MethodTable 03e40f4c
EEClass: 03ef1698
Size: 20(0x14) bytes
(C:\bugs\225271\arraytest.exe)
Fields:
MT Field Offset Type Attr Value Name
5b9a628c 4000001 0 System.Int32 instance 3 x
5b9a628c 4000002 4 System.Int32 instance 6 y
5b9a628c 4000003 8 System.Int32 instance 9 z
[4] 00ad2908
Name: Value
MethodTable 03e40f4c
EEClass: 03ef1698
Size: 20(0x14) bytes
(C:\bugs\225271\arraytest.exe)
Fields:
MT Field Offset Type Attr Value Name
5b9a628c 4000001 0 System.Int32 instance 4 x
5b9a628c 4000002 4 System.Int32 instance 8 y
5b9a628c 4000003 8 System.Int32 instance 12 z
\\
COMMAND: dumpalc.
DumpALC
<object address>
This command allows you to dump the AssemblyLoadContext into which the type of the
specified object was loaded.
Example output:
0:000> !dumpalc 000001c2800101a0
Name: Host.HostAssemblyLoadContext
MethodTable: 00007ff7c9cb1428
EEClass: 00007ff7c9ca4b40
Size: 88(0x58) bytes
File: c:\test\host.dll
Fields:
MT Field Offset Type VT Attr Value Name
00007ff7c9920eb8 4000ea3 8 System.Object 0 instance 000001c28000cff0 _unloadLock
0000000000000000 4000ea4 10 0 instance 0000000000000000 _resolvingUnmanagedDll
0000000000000000 4000ea5 18 0 instance 0000000000000000 _resolving
00007ff7c9d36850 4000ea6 20 ...Private.CoreLib]] 0 instance 000001c2800101b8 _unloading
00007ff7c9a74748 4000ea7 28 System.String 0 instance 0000000000000000 _name
00007ff7c9a427f0 4000ea8 30 System.IntPtr 1 instance 000001C2FA21DD50 _nativeAssemblyLoadContext
00007ff7c9a1c7e0 4000ea9 38 System.Int64 1 instance 0 _id
00007ff7c9ac57b8 4000eaa 40 System.Int32 1 instance 0 _state
00007ff7c9a107b8 4000eab 44 System.Boolean 1 instance 1 _isCollectible
00007ff7c9cb4070 4000ea1 b08 ...Private.CoreLib]] 0 static 000001c28000d090 s_allContexts
00007ff7c9a1c7e0 4000ea2 970 System.Int64 1 static 1 s_nextId
0000000000000000 4000eac b10 ...yLoadEventHandler 0 static 0000000000000000 AssemblyLoad
0000000000000000 4000ead b18 ...solveEventHandler 0 static 0000000000000000 TypeResolve
0000000000000000 4000eae b20 ...solveEventHandler 0 static 0000000000000000 ResourceResolve
0000000000000000 4000eaf b28 ...solveEventHandler 0 static 0000000000000000 AssemblyResolve
0000000000000000 4000eb0 b30 0 static 0000000000000000 s_asyncLocalCurrent
00007ff7c9cb26d0 4000001 48 ...ependencyResolver 0 instance 000001c28000d1c0 _resolver
\\
COMMAND: dso.
COMMAND: dumpstackobjects.
!DumpStackObjects [-verify] [top stack [bottom stack]]
This command will display any managed objects it finds within the bounds of
the current stack. Combined with the stack tracing commands like K and
!ClrStack, it is a good aid to determining the values of locals and
parameters.
If you use the -verify option, each non-static CLASS field of an object
candidate is validated. This helps to eliminate false positives. It is not
on by default because very often in a debugging scenario, you are
interested in objects with invalid fields.
The abbreviation !dso can be used for brevity.
\\
COMMAND: dumpdelegate.
!DumpDelegate <delegate address>
!DumpDelegate finds and outputs the one or more method descriptors associated with a delegate object.
For example:
0:000> !dumpdelegate
Target Method Name
000001461bacb0d8 00007ffc5c894b80 ConsoleApp16.Program.InstanceMethod()
000001461bacb098 00007ffc5c894b68 ConsoleApp16.Program.StaticMethod()
\\
COMMAND: dumpheap.
!DumpHeap [-stat]
[-strings]
[-short]
[-min <size>]
[-max <size>]
[-live]
[-dead]
[-thinlock]
[-startAtLowerBound]
[-mt <MethodTable address>]
[-type <partial type name>]
[start [end]]
!DumpHeap is a powerful command that traverses the garbage collected heap,
collection statistics about objects. With it's various options, it can look for
particular types, restrict to a range, or look for ThinLocks (see !SyncBlk
documentation). Finally, it will provide a warning if it detects excessive
fragmentation in the GC heap.
When called without options, the output is first a list of objects in the heap,
followed by a report listing all the types found, their size and number:
0:000> !dumpheap
Address MT Size
00a71000 0015cde8 12 Free
00a7100c 0015cde8 12 Free
00a71018 0015cde8 12 Free
00a71024 5ba58328 68
00a71068 5ba58380 68
00a710ac 5ba58430 68
00a710f0 5ba5dba4 68
...
total 619 objects
Statistics:
MT Count TotalSize Class Name
5ba7607c 1 12 System.Security.Permissions.HostProtectionResource
5ba75d54 1 12 System.Security.Permissions.SecurityPermissionFlag
5ba61f18 1 12 System.Collections.CaseInsensitiveComparer
...
0015cde8 6 10260 Free
5ba57bf8 318 18136 System.String
...
"Free" objects are simply regions of space the garbage collector can use later.
If 30% or more of the heap contains "Free" objects, the process may suffer from
heap fragmentation. This is usually caused by pinning objects for a long time
combined with a high rate of allocation. Here is example output where !DumpHeap
provides a warning about fragmentation:
<After the Statistics section>
Fragmented blocks larger than 1MB:
Addr Size Followed by
00a780c0 1.5MB 00bec800 System.Byte[]
00da4e38 1.2MB 00ed2c00 System.Byte[]
00f16df0 1.2MB 01044338 System.Byte[]
The arguments in detail:
-stat Restrict the output to the statistical type summary
-strings Restrict the output to a statistical string value summary
-short Limits output to just the address of each object. This allows you
to easily pipe output from the command to another debugger
command for automation.
-min Ignore objects less than the size given in bytes (hex)
-max Ignore objects larger than the size given in bytes (hex)
-live Only print live objects
-dead Only print dead objects (objects which will be collected in the
next full GC)
-thinlock Report on any ThinLocks (an efficient locking scheme, see !SyncBlk
documentation for more info)
-startAtLowerBound
Force heap walk to begin at lower bound of a supplied address range.
(During plan phase, the heap is often not walkable because objects
are being moved. In this case, DumpHeap may report spurious errors,
in particular bad objects. It may be possible to traverse more of
the heap after the reported bad object. Even if you specify an
address range, !DumpHeap will start its walk from the beginning of
the heap by default. If it finds a bad object before the specified
range, it will stop before displaying the part of the heap in which
you are interested. This switch will force !DumpHeap to begin its
walk at the specified lower bound. You must supply the address of a
good object as the lower bound for this to work. Display memory at
the address of the bad object to manually find the next method
table (use !dumpmt to verify). If the GC is currently in a call to
memcopy, You may also be able to find the next object's address by
adding the size to the start address given as parameters.)
-mt List only those objects with the MethodTable given
-type List only those objects whose type name is a substring match of the
string provided.
start Begin listing from this address
end Stop listing at this address
A special note about -type: Often, you'd like to find not only Strings, but
System.Object arrays that are constrained to contain Strings. ("new
String[100]" actually creates a System.Object array, but it can only hold
System.String object pointers). You can use -type in a special way to find
these arrays. Just pass "-type System.String[]" and those Object arrays will
be returned. More generally, "-type <Substring of interesting type>[]".
The start/end parameters can be obtained from the output of !EEHeap -gc. For
example, if you only want to list objects in the large heap segment:
0:000> !eeheap -gc
Number of GC Heaps: 1
generation 0 starts at 0x00c32754
generation 1 starts at 0x00c32748
generation 2 starts at 0x00a71000
segment begin allocated size
00a70000 00a71000 010443a8 005d33a8(6108072)
Large object heap starts at 0x01a71000
segment begin allocated size
01a70000 01a71000 01a75000 0x00004000(16384)
Total Size 0x5d73a8(6124456)
------------------------------
GC Heap Size 0x5d73a8(6124456)
0:000> !dumpheap 1a71000 1a75000
Address MT Size
01a71000 5ba88bd8 2064
01a71810 0019fe48 2032 Free
01a72000 5ba88bd8 4096
01a73000 0019fe48 4096 Free
01a74000 5ba88bd8 4096
total 5 objects
Statistics:
MT Count TotalSize Class Name
0019fe48 2 6128 Free
5ba88bd8 3 10256 System.Object[]
Total 5 objects
Finally, if GC heap corruption is present, you may see an error like this:
0:000> !dumpheap -stat
object 00a73d24: does not have valid MT
curr_object : 00a73d24
Last good object: 00a73d14
----------------
That indicates a serious problem. See the help for !VerifyHeap for more
information on diagnosing the cause.
\\
COMMAND: dumpvc.
!DumpVC <MethodTable address> <Address>
!DumpVC allows you to examine the fields of a value class. In C#, this is a
struct, and lives on the stack or within an Object on the GC heap. You need
to know the MethodTable address to tell SOS how to interpret the fields, as
a value class is not a first-class object with it's own MethodTable as the
first field. For example:
0:000> !DumpObj a79d98
Name: Mainy
MethodTable: 009032d8
EEClass: 03ee1424
Size: 28(0x1c) bytes
(C:\pub\unittest.exe)
Fields:
MT Field Offset Type Attr Value Name
0090320c 4000010 4 VALUETYPE instance 00a79d9c m_valuetype
009032d8 400000f 4 CLASS static 00a79d54 m_sExcep
m_valuetype is a value type. The value in the MT column (0090320c) is the
MethodTable for it, and the Value column provides the start address:
0:000> !DumpVC 0090320c 00a79d9c
Name: Funny
MethodTable 0090320c
EEClass: 03ee14b8
Size: 28(0x1c) bytes
(C:\pub\unittest.exe)
Fields:
MT Field Offset Type Attr Value Name
0090320c 4000001 0 CLASS instance 00a743d8 signature
0090320c 4000002 8 System.Int32 instance 2345 m1
0090320c 4000003 10 System.Boolean instance 1 b1
0090320c 4000004 c System.Int32 instance 1234 m2
0090320c 4000005 4 CLASS instance 00a79d98 backpointer
!DumpVC is quite a specialized function. Some managed programs make heavy use
of value classes, while others do not.
\\
COMMAND: gcroot.
!GCRoot [-nostacks] [-all] <Object address>
!GCRoot looks for references (or roots) to an object. These can exist in four
places:
1. On the stack
2. Within a GC Handle
3. In an object ready for finalization
4. As a member of an object found in 1, 2 or 3 above.
First, all stacks will be searched for roots, then handle tables, and finally
the reachable queue of the finalizer. Some caution about the stack roots:
!GCRoot doesn't attempt to determine if a stack root it encountered is valid
or is old (discarded) data. You would have to use !ClrStack and !U to
disassemble the frame that the local or argument value belongs to in order to
determine if it is still in use.
Because people often want to restrict the search to gc handles and reachable
objects, there is a -nostacks option.
The -all option forces all roots to be displayed instead of just the unique roots.
\\
COMMAND: objsize.
!ObjSize [<Object address>]
With no parameters, !ObjSize lists the size of all objects found on managed
threads. It also enumerates all GCHandles in the process, and totals the size
of any objects pointed to by those handles. In calculating object size,
!ObjSize includes the size of all child objects in addition to the parent.
For example, !DumpObj lists a size of 20 bytes for this Customer object:
0:000> !do a79d40
Name: Customer
MethodTable: 009038ec
EEClass: 03ee1b84
Size: 20(0x14) bytes
(C:\pub\unittest.exe)
Fields:
MT Field Offset Type Attr Value Name
009038ec 4000008 4 CLASS instance 00a79ce4 name
009038ec 4000009 8 CLASS instance 00a79d2c bank
009038ec 400000a c System.Boolean instance 1 valid
but !ObjSize lists 152 bytes:
0:000> !ObjSize a79d40
sizeof(00a79d40) = 152 ( 0x98) bytes (Customer)
This is because a Customer points to a Bank, has a name, and the Bank points to
an Address string. You can use !ObjSize to identify any particularly large
objects, such as a managed cache in a web server.
While running ObjSize with no arguments may point to specific roots that hold
onto large amounts of memory it does not provide information regarding the
amount of managed memory that is still alive. This is due to the fact that a
number of roots can share a common subgraph, and that part will be reported in
the size of all the roots that reference the subgraph.
Please note the -aggregate parameter to !ObjSize has been removed. Please see
'!DumpHeap -live' and '!DumpHeap -dead' for that functionality.
\\
COMMAND: fq.
COMMAND: finalizequeue.
!FinalizeQueue [-detail] | [-allReady] [-short]
This command lists the objects registered for finalization. Here is output from
a simple program:
0:000> !finalizequeue
SyncBlocks to be cleaned up: 0
MTA Interfaces to be released: 0
STA Interfaces to be released: 1
generation 0 has 4 finalizable objects (0015bc90->0015bca0)
generation 1 has 0 finalizable objects (0015bc90->0015bc90)
generation 2 has 0 finalizable objects (0015bc90->0015bc90)
Ready for finalization 0 objects (0015bca0->0015bca0)
Statistics:
MT Count TotalSize Class Name
5ba6cf78 1 24 Microsoft.Win32.SafeHandles.SafeFileHandle
5ba5db04 1 68 System.Threading.Thread
5ba73e28 2 112 System.IO.StreamWriter
Total 4 objects
The GC heap is divided into generations, and objects are listed accordingly. We
see that only generation 0 (the youngest generation) has any objects registered
for finalization. The notation "(0015bc90->0015bca0)" means that if you look at
memory in that range, you'll see the object pointers that are registered:
0:000> dd 15bc90 15bca0-4
0015bc90 00a743f4 00a79f00 00a7b3d8 00a7b47c
You could run !DumpObj on any of those pointers to learn more. In this example,
there are no objects ready for finalization, presumably because they still have
roots (You can use !GCRoot to find out). The statistics section provides a
higher-level summary of the objects registered for finalization. Note that
objects ready for finalization are also included in the statistics (if any).
Specifying -short will inhibit any display related to SyncBlocks or RCWs.
The arguments in detail:
-allReady Specifying this argument will allow for the display of all objects
that are ready for finalization, whether they are already marked by
the GC as such or not. The former means GC already put them in the
"Ready for finalization" list and their finalizers are ready to run
but haven't run yet. The latter means there is nothing holding onto
these objects but GC hasn't noticed it yet because a GC that collects
the generation this object lives in has not happened yet. When that
GC happens, this object will be moved to the "Ready for finalization"
list. For example, if a finalizable object lives in gen2 and a gen2 GC
has not happened, even if it's displayed by -allReady it's not actually
ready for finalization. This option can be very expensive, as it
verifies whether all the objects in the finalizable queues are still
rooted or not.
-short Limits the output to just the address of each object. If used in
conjunction with -allReady it enumerates all objects that have a
finalizer that are no longer rooted. If used independently it lists
all objects in the finalizable and "ready for finalization" queues.
-detail Will display extra information on any SyncBlocks that need to be
cleaned up, and on any RuntimeCallableWrappers (RCWs) that await
cleanup. Both of these data structures are cached and cleaned up by
the finalizer thread when it gets a chance to run.
\\
COMMAND: pe.
COMMAND: printexception.
!PrintException [-nested] [-lines] [-ccw] [<Exception object address>] [<CCW pointer>]
This will format fields of any object derived from System.Exception. One of the
more useful aspects is that it will format the _stackTrace field, which is a
binary array. If _stackTraceString field is not filled in, that can be helpful
for debugging. You can of course use !DumpObj on the same exception object to
explore more fields.
If called with no parameters, PrintException will look for the last outstanding
exception on the current thread and print it. This will be the same exception
that shows up in a run of !Threads.
!PrintException will notify you if there are any nested exceptions on the
current managed thread. (A nested exception occurs when you throw another
exception within a catch handler already being called for another exception).
If there are nested exceptions, you can re-run !PrintException with the
"-nested" option to get full details on the nested exception objects. The
!Threads command will also tell you which threads have nested exceptions.
!PrintException can display source information if available, by specifying the
-lines command line argument.
!PrintException prints the exception object corresponding to a given CCW pointer,
which can be specified using the -ccw option.
The abbreviation !pe can be used for brevity.
\\
COMMAND: traverseheap.
!TraverseHeap [-xml] [-verify] <filename>
!TraverseHeap writes out a file in a format understood by the CLR Profiler.
You can download the CLR Profiler from this link:
http://www.microsoft.com/downloads/details.aspx?FamilyId=86CE6052-D7F4-4AEB-
9B7A-94635BEEBDDA&displaylang=en
It creates a graphical display of the GC heap to help you analyze the state of
your application.
If you pass the -verify option it will do more sanity checking of the heap
as it dumps it. Use this option if heap corruption is suspected.
If you pass the "-xml" flag, the file is instead written out in an easy to
understand xml format:
<gcheap>
<types>
<type id="1" name="System.String">
...
</types>
<roots>
<root kind="handle" address="0x00a73ff0"/>
<root kind="stack" address="0x0069f0e0"/>
...
</roots>
<objects>
<object address="0x00b73030" typeid="1" size="300"/>
<object address="0x00b75054" typeid="5" size="20">
<member address="0x00b75088" />
...
</object>
...
</objects>
</gcheap>
You can break into your process, load SOS, take a snapshot of your heap with
this function, then continue.
\\
COMMAND: threadstate.
!ThreadState value
The !Threads command outputs, among other things, the state of the thread.
This is a bit field which corresponds to various states the thread is in.
To check the state of the thread, simply pass that bit field from the
output of !Threads into !ThreadState.
Example:
0:003> !Threads
ThreadCount: 2
UnstartedThread: 0
BackgroundThread: 1
PendingThread: 0
DeadThread: 0
Hosted Runtime: no
PreEmptive GC Alloc Lock
ID OSID ThreadOBJ State GC Context Domain Count APT Exception
0 1 250 0019b068 a020 Disabled 02349668:02349fe8 0015def0 0 MTA
2 2 944 001a6020 b220 Enabled 00000000:00000000 0015def0 0 MTA (Finalizer)
0:003> !ThreadState b220
Legal to Join
Background
CLR Owns
CoInitialized
In Multi Threaded Apartment
Possible thread states:
Thread Abort Requested
GC Suspend Pending
User Suspend Pending
Debug Suspend Pending
GC On Transitions
Legal to Join
Yield Requested
Hijacked by the GC
Blocking GC for Stack Overflow
Background
Unstarted
Dead
CLR Owns
CoInitialized
In Single Threaded Apartment
In Multi Threaded Apartment
Reported Dead
Fully initialized
Task Reset
Sync Suspended
Debug Will Sync
Stack Crawl Needed
Suspend Unstarted
Aborted
Thread Pool Worker Thread
Interruptible
Interrupted
Completion Port Thread
Abort Initiated
Finalized
Failed to Start
Detached
\\
COMMAND: clrthreads.
COMMAND: threads.
!Threads [-live] [-special]
!Threads lists all the mananaged threads in the process.
-live: optional. Only print threads associated with a live thread.
-special: optional. With this switch, the command will display all the special
threads created by CLR. Those threads might not be managed threads
so they might not be shown in the first part of the command's
output. Example of special threads include: GC threads (in
concurrent GC and server GC), Debugger helper threads, Finalizer
threads, AppDomain Unload threads, and Threadpool timer threads.
-managedexception: optional. Sets the current thread to first thread with
an managed exception for the "printexception" command.
Each thread has many attributes, many of which can be ignored. The important
ones are discussed below:
There are three ID columns:
1) The debugger shorthand ID (When the runtime is hosted this column might
display the special string "<<<<" when this internal thread object is not
associated with any physical thread - this may happen when the host reuses
the runtime internal thread object)
2) The CLR Thread ID
3) The OS thread ID.
If PreEmptiveGC is enabled for a thread, then a garbage collection
can occur while that thread is running. For example, if you break in while
a managed thread is making a PInvoke call to a Win32 function, that thread
will be in PreEmptive GC mode.
The Domain column indicates what AppDomain the thread is currently executing
in. You can pass this value to !DumpDomain to find out more.
The APT column gives the COM apartment mode.
Exception will list the last thrown exception (if any) for the thread. More
details can be obtained by passing the pointer value to !PrintException. If
you get the notation "(nested exceptions)", you can get details on those
exceptions by switching to the thread in question, and running
"!PrintException -nested".
\\
COMMAND: clrstack.
!ClrStack [-a] [-l] [-p] [-n] [-f] [-r] [-all]
!ClrStack [-a] [-l] [-p] [-i] [variable name] [frame]
ClrStack attempts to provide a true stack trace for managed code only. It is
handy for clean, simple traces when debugging straightforward managed
programs. The -p parameter will show arguments to the managed function. The
-l parameter can be used to show information on local variables in a frame.
SOS can't retrieve local names at this time, so the output for locals is in
the format <local address> = <value>. The -a (all) parameter is a short-cut
for -l and -p combined.
The -f option (full mode) displays the native frames intermixing them with
the managed frames and the assembly name and function offset for the managed
frames.
The -r option dumps the registers for each stack frame.
The -all option dumps all the managed threads' stacks.
If the debugger has the option SYMOPT_LOAD_LINES specified (either by the
.lines or .symopt commands), SOS will look up the symbols for every managed
frame and if successful will display the corresponding source file name and
line number. The -n (No line numbers) parameter can be specified to disable
this behavior.
When you see methods with the name "[Frame:...", that indicates a transition
between managed and unmanaged code. You could run !IP2MD on the return
addresses in the call stack to get more information on each managed method.
On x64 platforms, Transition Frames are not displayed at this time. To avoid
heavy optimization of parameters and locals one can request the JIT compiler
to not optimize functions in the managed app by creating a file myapp.ini
(if your program is myapp.exe) in the same directory. Put the following lines
in myapp.ini and re-run:
[.NET Framework Debugging Control]
GenerateTrackingInfo=1
AllowOptimize=0
The -i option is a new EXPERIMENTAL addition to ClrStack and will use the ICorDebug
interfaces to display the managed stack and variables. With this option you can also
view and expand arrays and fields for managed variables. If a stack frame number is
specified in the command line, ClrStack will show you the parameters and/or locals
only for that frame (provided you specify -l or -p or -a of course). If a variable
name and a stack frame number are specified in the command line, ClrStack will show
you the parameters and/or locals for that frame, and will also show you the fields
for that variable name you specified. Here are some examples:
!ClrStack -i -a : This will show you all parameters and locals for all frames
!ClrStack -i -a 3 : This will show you all parameters and locals, for frame 3
!ClrStack -i var1 0 : This will show you the fields of 'var1' for frame 0
!ClrStack -i var1.abc 2 : This will show you the fields of 'var1', and expand
'var1.abc' to show you the fields of the 'abc' field,
for frame 2.
!ClrStack -i var1.[basetype] 0 : This will show you the fields of 'var1', and
expand the base type of 'var1' to show you its
fields.
!ClrStack -i var1.[6] 0 : If 'var1' is an array, this will show you the element
at index 6 in the array, along with its fields
The -i options uses DML output for a better debugging experience, so typically you
should only need to execute "!ClrStack -i", and from there, click on the DML
hyperlinks to inspect the different managed stack frames and managed variables.
\\
COMMAND: ip2md.
!IP2MD <Code address>
Given an address in managed JITTED code, IP2MD attempts to find the MethodDesc
associated with it. For example, this output from K:
0:000> K
ChildEBP RetAddr
00a79c78 03ef02ab image00400000!Mainy.Top()+0xb
00a79c78 03ef01a6 image00400000!Mainy.Level(Int32)+0xb
00a79c78 5d3725a1 image00400000!Mainy.Main()+0xee
0012ea04 5d512f59 clr!CallDescrWorkerInternal+0x30
0012ee34 5d7946aa clr!CallDescrWorker+0x109
0:000> !IP2MD 03ef01a6
MethodDesc: 00902f40
Method Name: Mainy.Main()
Class: 03ee1424
MethodTable: 009032d8
mdToken: 0600000d
Module: 001caa38
IsJitted: yes
CodeAddr: 03ef00b8
Source file: c:\Code\prj.mini\exc.cs @ 39
We have taken a return address into Mainy.Main, and discovered information
about that method. You could run !U, !DumpMT, !DumpClass, !DumpMD, or
!DumpModule on the fields listed to learn more.
The "Source line" output will only be present if the debugger can find the
symbols for the managed module containing the given <code address>, and if the
debugger is configured to load line number information.
\\
COMMAND: u.
!U [-gcinfo] [-ehinfo] [-n] [-o] <MethodDesc address> | <Code address>
Presents an annotated disassembly of a managed method when given a MethodDesc
pointer for the method, or a code address within the method body. Unlike the
debugger "U" function, the entire method from start to finish is printed,
with annotations that convert metadata tokens to names.
<example output>
...
03ef015d b901000000 mov ecx,0x1
03ef0162 ff156477a25b call dword ptr [mscorlib_dll+0x3c7764 (5ba27764)] (System.Console.InitializeStdOutError(Boolean), mdToken: 06000713)
03ef0168 a17c20a701 mov eax,[01a7207c] (Object: SyncTextWriter)
03ef016d 89442414 mov [esp+0x14],eax
If you pass the -gcinfo flag, you'll get inline display of the GCInfo for
the method. You can also obtain this information with the !GCInfo command.
If you pass the -ehinfo flag, you'll get inline display of exception info
for the method. (Beginning and end of try/finally/catch handlers, etc.).