3 .\" Copyright 2003 Ximian, Inc.
4 .\" Copyright 2004-2009 Novell, Inc.
6 .\" Miguel de Icaza (miguel@gnu.org)
10 mono \- Mono's ECMA-CLI native code generator (Just-in-Time and Ahead-of-Time)
13 .B mono [options] file [arguments...]
15 \fImono\fP is a runtime implementation of the ECMA Common Language
16 Infrastructure. This can be used to run ECMA and .NET applications.
18 The runtime contains a native code generator that transforms the
19 Common Intermediate Language into native code.
21 The code generator can operate in two modes: just in time compilation
22 (JIT) or ahead of time compilation (AOT). Since code can be
23 dynamically loaded, the runtime environment and the JIT are always
24 present, even if code is compiled ahead of time.
26 The runtime loads the specified
33 is an ECMA assembly. They typically have a .exe or .dll extension.
35 The runtime provides a number of configuration options for running
36 applications, for developing and debugging, and for testing and
37 debugging the runtime itself.
39 On Unix-based systems, Mono provides a mechanism to emulate the
40 Windows-style file access, this includes providing a case insensitive
41 view of the file system, directory separator mapping (from \\ to /) and
42 stripping the drive letters.
44 This functionality is enabled by setting the
46 environment variable to one of
51 See the description for
53 in the environment variables section for more details.
55 The following options are available:
57 \fB--aot\fR, \fB--aot[=options]\fR
58 This option is used to precompile the CIL code in the specified
59 assembly to native code. The generated code is stored in a file with
60 the extension .so. This file will be automatically picked up by the
61 runtime when the assembly is executed.
63 Ahead-of-Time compilation is most useful if you use it in combination
64 with the -O=all,-shared flag which enables all of the optimizations in
65 the code generator to be performed. Some of those optimizations are
66 not practical for Just-in-Time compilation since they might be very
69 Unlike the .NET Framework, Ahead-of-Time compilation will not generate
70 domain independent code: it generates the same code that the
71 Just-in-Time compiler would produce. Since most applications use a
72 single domain, this is fine. If you want to optimize the generated
73 code for use in multi-domain applications, consider using the
76 This pre-compiles the methods, but the original assembly is still
77 required to execute as this one contains the metadata and exception
78 information which is not available on the generated file. When
79 precompiling code, you might want to compile with all optimizations
80 (-O=all). Pre-compiled code is position independent code.
82 Pre compilation is just a mechanism to reduce startup time, increase
83 code sharing across multiple mono processes and avoid just-in-time
84 compilation program startup costs. The original assembly must still
85 be present, as the metadata is contained there.
87 AOT code typically can not be moved from one computer to another
88 (CPU-specific optimizations that are detected at runtime) so you
89 should not try to move the pre-generated assemblies or package the
90 pre-generated assemblies for deployment.
92 A few options are available as a parameter to the
94 command line option. The options are separated by commas, and more
95 than one can be specified:
99 .I bind-to-runtime-version
101 If specified, forces the generated AOT files to be bound to the
102 runtime version of the compiling Mono. This will prevent the AOT
103 files from being consumed by a different Mono runtime.
105 This is currently an experimental feature as it is not complete.
106 This instructs Mono to precompile code that has historically not been
107 precompiled with AOT.
110 Instructs the AOT compiler to emit debug symbol information.
113 Create an ELF object file (.o) which can be statically linked into an executable
114 when embedding the mono runtime. When this option is used, the object file needs to
115 be registered with the embedded runtime using the mono_aot_register_module function
116 which takes as its argument the mono_aot_module_<ASSEMBLY NAME>_info global symbol
117 from the object file:
120 extern void *mono_aot_module_hello_info;
122 mono_aot_register_module (mono_aot_module_hello_info);
127 For more information about AOT, see: http://www.mono-project.com/AOT
130 \fB--attach=[options]\fR
131 Currently the only option supported by this command line argument is
132 \fBdisable\fR which disables the attach functionality.
135 This is an experimental flag that instructs the Mono runtime to not
136 generate any code at runtime and depend exclusively on the code
137 generated from using mono --aot=full previously. This is useful for
138 platforms that do not permit dynamic code generation.
140 Notice that this feature will abort execution at runtime if a codepath
141 in your program, or Mono's class libraries attempts to generate code
142 dynamically. You should test your software upfront and make sure that
143 you do not use any dynamic features.
145 \fB--config filename\fR
146 Load the specified configuration file instead of the default one(s).
147 The default files are /etc/mono/config and ~/.mono/config or the file
148 specified in the MONO_CONFIG environment variable, if set. See the
149 mono-config(5) man page for details on the format of this file.
152 Configures the virtual machine to be better suited for desktop
153 applications. Currently this sets the GC system to avoid expanding
154 the heap as much as possible at the expense of slowing down garbage
157 \fB--help\fR, \fB-h\fR
158 Displays usage instructions.
160 \fB--optimize=MODE\fR, \fB-O=MODE\fR
161 MODE is a comma separated list of optimizations. They also allow
162 optimizations to be turned off by prefixing the optimization name with
165 In general, Mono has been tuned to use the default set of flags,
166 before using these flags for a deployment setting, you might want to
167 actually measure the benefits of using them.
169 The following optimizations are implemented:
171 all Turn on all optimizations
172 peephole Peephole postpass
173 branch Branch optimizations
174 inline Inline method calls
175 cfold Constant folding
176 consprop Constant propagation
177 copyprop Copy propagation
178 deadce Dead code elimination
179 linears Linear scan global reg allocation
180 cmov Conditional moves [arch-dependency]
181 shared Emit per-domain code
182 sched Instruction scheduling
183 intrins Intrinsic method implementations
184 tailc Tail recursion and tail calls
185 loop Loop related optimizations
186 fcmov Fast x86 FP compares [arch-dependency]
187 leaf Leaf procedures optimizations
188 aot Usage of Ahead Of Time compiled code
189 precomp Precompile all methods before executing Main
190 abcrem Array bound checks removal
191 ssapre SSA based Partial Redundancy Elimination
192 sse2 SSE2 instructions on x86 [arch-dependency]
193 gshared Enable generic code sharing.
196 For example, to enable all the optimization but dead code
197 elimination and inlining, you can use:
199 -O=all,-deadce,-inline
202 The flags that are flagged with [arch-dependency] indicate that the
203 given option if used in combination with Ahead of Time compilation
204 (--aot flag) would produce pre-compiled code that will depend on the
205 current CPU and might not be safely moved to another computer.
207 \fB--runtime=VERSION\fR
208 Mono supports different runtime versions. The version used depends on the program
209 that is being run or on its configuration file (named program.exe.config). This option
210 can be used to override such autodetection, by forcing a different runtime version
211 to be used. Note that this should only be used to select a later compatible runtime
212 version than the one the program was compiled against. A typical usage is for
213 running a 1.1 program on a 2.0 version:
215 mono --runtime=v2.0.50727 program.exe
218 \fB--security\fR, \fB--security=mode\fR
219 Activate the security manager, a currently experimental feature in
220 Mono and it is OFF by default. The new code verifier can be enabled
221 with this option as well.
225 Using security without parameters is equivalent as calling it with the
228 The following modes are supported:
231 This allows mono to support declarative security attributes,
232 e.g. execution of Code Access Security (CAS) or non-CAS demands.
235 Enables the core-clr security system, typically used for
236 Moonlight/Silverlight applications. It provides a much simpler
237 security system than CAS, see http://www.mono-project.com/Moonlight
238 for more details and links to the descriptions of this new system.
241 Enables the new verifier and performs basic verification for code
242 validity. In this mode, unsafe code and P/Invoke are allowed. This
243 mode provides a better safety guarantee but it is still possible
244 for managed code to crash Mono.
247 Enables the new verifier and performs full verification of the code
248 being executed. It only allows verifiable code to be executed.
249 Unsafe code is not allowed but P/Invoke is. This mode should
250 not allow managed code to crash mono. The verification is not as
251 strict as ECMA 335 standard in order to stay compatible with the MS
254 The security system acts on user code: code contained in mscorlib or
255 the global assembly cache is always trusted.
260 Configures the virtual machine to be better suited for server
261 operations (currently, a no-op).
264 Verifies mscorlib and assemblies in the global
265 assembly cache for valid IL, and all user code for IL
268 This is different from \fB--security\fR's verifiable
269 or validil in that these options only check user code and skip
270 mscorlib and assemblies located on the global assembly cache.
272 \fB-V\fR, \fB--version\fR
273 Prints JIT version information (system configuration, release number
274 and branch names if available).
277 .SH DEVELOPMENT OPTIONS
278 The following options are used to help when developing a JITed application.
280 \fB--debug\fR, \fB--debug=OPTIONS\fR
281 Turns on the debugging mode in the runtime. If an assembly was
282 compiled with debugging information, it will produce line number
283 information for stack traces.
287 The optional OPTIONS argument is a comma separated list of debugging
288 options. These options are turned off by default since they generate
289 much larger and slower code at runtime.
291 The following options are supported:
294 Produces a detailed error when throwing a InvalidCastException. This
295 option needs to be enabled as this generates more verbose code at
299 Disable some JIT optimizations which are usually only disabled when
300 running inside the debugger. This can be helpful if you want to attach
301 to the running process with mdb.
304 Generate and register debugging information with gdb. This is only supported on some
305 platforms, and only when using gdb 7.0 or later.
309 \fB--profile[=profiler[:profiler_args]]\fR
310 Turns on profiling. For more information about profiling applications
311 and code coverage see the sections "PROFILING" and "CODE COVERAGE"
314 \fB--trace[=expression]\fR
315 Shows method names as they are invoked. By default all methods are
318 The trace can be customized to include or exclude methods, classes or
319 assemblies. A trace expression is a comma separated list of targets,
320 each target can be prefixed with a minus sign to turn off a particular
321 target. The words `program', `all' and `disabled' have special
322 meaning. `program' refers to the main program being executed, and
323 `all' means all the method calls.
325 The `disabled' option is used to start up with tracing disabled. It
326 can be enabled at a later point in time in the program by sending the
327 SIGUSR2 signal to the runtime.
329 Assemblies are specified by their name, for example, to trace all
330 calls in the System assembly, use:
333 mono --trace=System app.exe
336 Classes are specified with the T: prefix. For example, to trace all
337 calls to the System.String class, use:
340 mono --trace=T:System.String app.exe
343 And individual methods are referenced with the M: prefix, and the
344 standard method notation:
347 mono --trace=M:System.Console:WriteLine app.exe
350 As previously noted, various rules can be specified at once:
353 mono --trace=T:System.String,T:System.Random app.exe
356 You can exclude pieces, the next example traces calls to
357 System.String except for the System.String:Concat method.
360 mono --trace=T:System.String,-M:System.String:Concat
363 Finally, namespaces can be specified using the N: prefix:
366 mono --trace=N:System.Xml
370 \fB--no-x86-stack-align\fR
371 Don't align stack frames on the x86 architecture. By default, Mono
372 aligns stack frames to 16 bytes on x86, so that local floating point
373 and SIMD variables can be properly aligned. This option turns off the
374 alignment, which usually saves one intruction per call, but might
375 result in significantly lower floating point and SIMD performance.
376 .SH JIT MAINTAINER OPTIONS
377 The maintainer options are only used by those developing the runtime
378 itself, and not typically of interest to runtime users or developers.
381 Inserts a breakpoint before the method whose name is `method'
382 (namespace.class:methodname). Use `Main' as method name to insert a
383 breakpoint on the application's main method.
386 Inserts a breakpoint on exceptions. This allows you to debug your
387 application with a native debugger when an exception is thrown.
390 This compiles a method (namespace.name:methodname), this is used for
391 testing the compiler performance or to examine the output of the code
395 Compiles all the methods in an assembly. This is used to test the
396 compiler performance or to examine the output of the code generator
398 \fB--graph=TYPE METHOD\fR
399 This generates a postscript file with a graph with the details about
400 the specified method (namespace.name:methodname). This requires `dot'
401 and ghostview to be installed (it expects Ghostview to be called
404 The following graphs are available:
406 cfg Control Flow Graph (CFG)
408 code CFG showing code
409 ssa CFG showing code after SSA translation
410 optcode CFG showing code after IR optimizations
413 Some graphs will only be available if certain optimizations are turned
417 Instruct the runtime on the number of times that the method specified
418 by --compile (or all the methods if --compileall is used) to be
419 compiled. This is used for testing the code generator performance.
422 Displays information about the work done by the runtime during the
423 execution of an application.
425 \fB--wapi=hps|semdel\fR
426 Perform maintenance of the process shared data.
428 semdel will delete the global semaphore.
430 hps will list the currently used handles.
432 \fB-v\fR, \fB--verbose\fR
433 Increases the verbosity level, each time it is listed, increases the
434 verbosity level to include more information (including, for example,
435 a disassembly of the native code produced, code selector info etc.).
437 The Mono runtime allows external processes to attach to a running
438 process and load assemblies into the running program. To attach to
439 the process, a special protocol is implemented in the Mono.Management
442 With this support it is possible to load assemblies that have an entry
443 point (they are created with -target:exe or -target:winexe) to be
444 loaded and executed in the Mono process.
446 The code is loaded into the root domain, and it starts execution on
447 the special runtime attach thread. The attached program should
448 create its own threads and return after invocation.
450 This support allows for example debugging applications by having the
451 csharp shell attach to running processes.
453 The mono runtime includes a profiler that can be used to explore
454 various performance related problems in your application. The
455 profiler is activated by passing the --profile command line argument
456 to the Mono runtime, the format is:
459 --profile[=profiler[:profiler_args]]
462 Mono has a built-in profiler called 'default' (and is also the default
463 if no arguments are specified), but developers can write custom
464 profilers, see the section "CUSTOM PROFILERS" for more details.
468 is not specified, the default profiler is used.
472 is a profiler-specific string of options for the profiler itself.
474 The default profiler accepts the following options 'alloc' to profile
475 memory consumption by the application; 'time' to profile the time
476 spent on each routine; 'jit' to collect time spent JIT-compiling methods
477 and 'stat' to perform sample statistical profiling.
478 If no options are provided the default is 'alloc,time,jit'.
481 profile data is printed to stdout: to change this, use the 'file=filename'
482 option to output the data to filename.
487 mono --profile program.exe
491 That will run the program with the default profiler and will do time
492 and allocation profiling.
496 mono --profile=default:stat,alloc,file=prof.out program.exe
499 Will do sample statistical profiling and allocation profiling on
500 program.exe. The profile data is put in prof.out.
502 Note that the statistical profiler has a very low overhead and should
503 be the preferred profiler to use (for better output use the full path
504 to the mono binary when running and make sure you have installed the
505 addr2line utility that comes from the binutils package).
510 is a general purpose profiler that can track many different kinds of
511 events and logs those into a file as the program executes. This is
512 different than previous profilers in Mono that kept the information in
513 memory and rendered a summary of the results when the program shut
516 Using the logging profiler means that useful information can be
517 gathered for long-running applications, applications that terminate
518 abormally (crashes, segfaults, complicated tear down processes) or
519 when no data about the shutdown is required.
521 The data collected by the running threads is kept independent of each
522 other to minimize the runtime overhead and the information dumped into
523 the log at regular intervals.
525 A sample use is very simple:
527 $ mono --profile=logging program.exe
529 $ mprof-decoder program.mprof
532 In the above example the logging profiler is used in its default mode
533 that merely records GC statistics for the execution of program.exe.
534 The profiling data collected is stored in the file program.mprof. The
535 mprof-decoder tool is then used to analyze the data.
537 You can instruct the logging profiler to record different one or more
538 sets of events. These are the modes supported:
540 .I Statistical Profiling (stat)
541 the program instruction pointer is periodically sampled to determine
542 where the program is spending most of its time. Statistical
543 profiling has a very low impact on a running application and it is
544 very useful to get a general picture of where time is being spent on a
547 If call chains are requested, for each sample the profiler gets a
548 partial stack trace (limited by the specified depth) so that
549 caller-callee information is available.
552 each method enter and exit is logged with a timestamp; further processing of
553 the data can show the methods that took the longer to execute, with complete
554 accounting for callers and callees. However, this way of profiling is rather
555 intrusive and slows down the application significantly.
558 each allocation is logged.
560 .I Allocation summary:
561 shows, for each collection, a summary of the heap contents broken down by
562 class (for each class the number of allocated and released objects is
563 given, together with their aggregated size in bytes).
565 .I Heap snapshot mode:
566 dumps the whole heap contents at every collection (or at user specified
567 collections). It is also possible to request a collection and snapshot dump
570 Moreover, other events can be logged and analyzed, like jit time for each
571 method, load and unload for assemblies, modules and and individual classes,
572 and appdomain and thread creation and destruction.
574 This profiler is activated passing the \fB--profile=logging\fR option to
575 the mono runtime, and is controlled attaching further options, like
576 \fB--profile=logging:statistical\fR for doing statistical profiling (multiple
577 options are separated by commas).
579 As a quick primer, here are a few examples of the most common usage modes:
581 To perform statistical profiling:
584 mono --profile=logging:stat program.exe
587 To perform statistical profiling, inspecting call chains up to depth 8:
590 mono --profile=logging:stat=8 program.exe
593 To profile allocations (by default the call stack will be analized for
594 each allocation, producing detailed caller method attribution infornation):
597 mono --profile=logging:allocations program.exe
600 To profile garbage collection activity at a high level (collection time and objects freed
601 at each collection for each class are reported, but heap snapshots are not saved to disk):
604 mono --profile=logging:allocations-summary program.exe
607 To perform heap profiling taking heap snapshots:
610 mono --profile=logging:heap=all program.exe
613 To write the resulting data to a different file:
616 mono --profile=logging:output=mydata.mprof program.exe
619 Then you would need to invoke the decoder \fImprof-decoder(1)\fR
620 on the output file to see the profiling results, or to examine heap
621 snapshots and allocations in detail \fImprof-heap-viewer(1)\fR.
623 The operating modes described above are the default ones, and are sufficient
626 To further customize the profiler behavior there are more options, described
629 These options can be individually enabled and disabled prefixing them
630 with an (optional) '+' character or a '-' character. For instance,
631 the "allocations" option by default records also the full call stack
632 at each allocation. If only the caller is wanted, one should use
633 "allocations,-save-allocation-stack", or to disable call tracking
634 completely (making the profiler less intrusive)
635 "allocations,-save-allocation-caller,-save-allocation-stack". In
636 practice the "allocation" option by default behaves like
637 "allocations,save-allocation-caller,save-allocation-stack", but the
638 user can tune this to his needs.
640 These are all the available options, organized by category:
642 \fBExecution profiling modes\fR
646 \fIstatistical\fR, \fIstat\fR or \fIs\fR
647 Performs statistical profiling. This is a lightweight profiling
648 mechanism and it has a much lower overhead than the \fIenter-leave\fR
649 profiling as it works by sampling where the program is spending its
650 time by using a timer.
651 If specified with \fIs=<number>\fR, also inspect call chains up to level
654 \fIenter-leave\fR, \fIcalls\fR or \fIc\fR
655 Measure the time spent inside each method call, this is done by
656 logging the time when a method enters and when the method leaves.
657 This can be a time consuming operation.
660 Collect information about time spent by the JIT engine compiling
665 \fBAllocation profiling modes\fR
669 \fIallocations\fR, \fIalloc\fR or \fIa\fR
670 Collect information about each allocation (object class and size).
671 By default this also implies "+save-allocation-caller" and
672 "+save-allocation-stack".
674 \fIsave-allocation-caller\fR, \fIsac\fR
675 Save the direct caller of each allocation. The profiler filters out wrapper
676 methods, and also recognizes if the allocation has been performed by the
677 runtime while jitting a method.
679 \fIsave-allocation-stack\fR, \fIsas\fR
680 Save the full managed execution stack at each allocation.
681 While the "sac" option saves the direct caller, this one records the whole
683 Note that in the call stack the wrapper methods are not filtered out.
684 Anyway the "sac" and "sas" options can be combined, and the decoder will
685 attribute the allocation to the correct method even if the wrapper is at the
686 top of the stack trace.
688 \fIallocations-summary\fR or \fIas\fR
689 At each collection dump a summary
690 of the heap contents (for each class, the number and collective size of all
691 live and freed heap objects). This very lightweight compared to full heap
694 \fIunreachable\fR, \fIfree\fR or \fIf\fR
695 Performs a lightweight profile of the garbage collector. On each
696 collection performed by the GC, the list of unreachable objects is
697 recorded, and for each object the class and size is provided. This
698 information can be used to compute the heap size broken down by class
699 (combined with "a" can give the same information of "as", but the log
700 file contains info about each individual object, while in "as" the
701 processing is done directly at runtime and the log file contains only
702 the summarized data broken down by class).
705 Measure the time spent in each collection, and also trace heap resizes.
707 \fIheap-shot[=ARG]\fR, \fIheap[=ARG]\fR or \fIh[=ARH]\fR
708 Performs full heap profiling. In this case on each
709 collection a full heap snapshot is recorded to disk.
710 Inside the snapshots, each object reference is still represented so
711 that it's possible to investigate who is responsible for keeping objects
714 If the value of ARG is
716 a heap snapshot is taken at each collection.
718 If the value is an integer
720 a snapshot will be taken at the first
722 collections (like setting
726 If no additional argument is given to the heap option, the only way to take
727 heap snapshots is to requeste them using the runtime socket based command
728 interface described below (see "Profiler activity control").
730 Heap profiling also enables full allocation profiling (with call
731 stacks), and each allocation can be related to its corresponding
732 object in the snapshots, enabling investigations like "find all
733 objects of a given class allocated by a given method and still live at
734 a given collection, and then find all objects referencing them".
736 This kind of heap snapshot analysis is performed using the mprof-heap-viewer(1)
739 The number of heap snapshots taken (and the moment in which they are taken)
740 can be further customized with the following options:
742 \fIgc-dumps=N\fR, \fIgc-d=N\fR, \fIgcd=N\fR
743 states the number of snapshots that must be dumped (since the application
744 starts). Zero means no dumps at all, -1 means dump at all collections.
746 These options exist because it can happen that the user wants to investigate
747 what happens during collections but without forcing a collection using the
748 command interface, because forcing a collection alters the program behavior.
749 Of course it is possible to simply take a snapshot at every collection, but
750 in some workloads this is could not be feasible (too much data).
751 So we have this "garbage collection dumps" counter to control how many
756 \fBProfiler activity control\fR
760 \fIoutput=FILE\fR, \fIout=FILE\fR or \fIo=FILE\fR
761 Use this option to provide the output file name for the profile log.
762 If this option is not specified, it will default to "<program-name>.mprof".
764 \fIoutput-suffix=SUFFIX\fR, \fIsuffix=SUFFIX\fR or \fIos=SUFFIX\fR: makes
765 the output file name equals to "<program-name>-SUFFIX.mprof".
767 \fIstart-enabled\fR or \fIse\fR: start with the profiler active
768 (which is the default).
770 \fIstart-disabled\fR or \fIsd\fR: start with the profiler inactive.
772 \fIforce-accurate-timer\fR (or \fIfac\fR): the profiler by default uses
773 rtdsc to acquire timestamps for frequent events, but this can be imprecise;
774 using this option you force the use of "gettimeofday" at every event, which
775 is more accurate but much slower.
777 \fIcommand-port=port\fR or \fIcp=port\fR (where port is an integer between
779 Choose a TCP port where the profiler will listen for user commands.
780 The protocol is ASCII based and line oriented (one line per command), and the
781 profiler answers with one line containing either "OK" or "ERROR" to each
784 The user can telnet to this port and give commands manually, or a GUI can
785 use this facility to control the profiler at runtime.
787 The available commands are:
789 \fIenable\fR: Enables the profiler.
791 \fIdisable\fR: Disables the profiler.
793 \fIheap-snapshot\fR: Takes a heap snapshot now (forces a full garbage collection).
795 \fIheap-snapshot-counter=arg\fR: Set the counter of the next heap snapshots
796 that must be taken, where arg can be "all" (take a snapshot at every
797 collection), "none" (do not take snapshots), or an integer "n" (take a heap
798 snapshot for the next "n" collections).
802 \fBInternal buffer sizes\fR
806 \fIper-thread-buffer-size=N\fR, \fItbs=N\fR
807 Use to specify the number of events that a thread buffer
808 can hold. When the thread buffer is full, a log block is
811 This defaults to tbs=10000.
813 \fIstatistical-thread-buffer-size=N\fR, \fIsbs=N\fR
814 The number of statistical samples that
815 are held in memory before they are dumped to disk (the system does
816 double-buffering and the statistical samples are written by a helper
817 thread, so the statistical profiler never stops and is able to profile
818 the profiler itself).
820 This defaults to sbs=10000.
822 \fIwrite-buffer-size\fR, \fIwbs\fR
823 Specifies the size in bytes of the internal write buffers.
825 This defaults to wbs=1024.
829 In its current state, this profiler can also perform heap analysis
830 like the HeapShot profiler, but there is no UI to process this
833 Another known issue is that if the timer is not strictly monotonic (like
834 rtdsc), differences between times can underflow (they are handled as
835 unsigned integers) and weird numbers can show up in the logs.
837 Finally, it can happen that when exceptions are thrown the profiler temporarily
838 loses track of the execution stack and misattributes the caller for a few
839 allocations (and method execution time).
841 The output file contains compressed events, to process the data you should
842 use tools like the "Mono.Profiler" tool provided on the Mono SVN
845 More explanations are provided here: "http://www.mono-project.com/LoggingProfiler".
846 .SH EXTERNAL PROFILERS
847 There are a number of external profilers that have been developed for
848 Mono, we will update this section to contain the profilers.
850 The heap Shot profiler can track all live objects, and references to
851 these objects, and includes a GUI tool, this is our recommended
853 To install you must download the profiler
856 svn co svn://anonsvn.mono-project.com/source/trunk/heap-shot
863 See the included documentation for details on using it.
865 The Live Type profiler shows at every GC iteration all of the live
866 objects of a given type. To install you must download the profiler
869 svn co svn://anonsvn.mono-project.com/source/trunk/heap-prof
876 To use the profiler, execute:
878 mono --profile=desc-heap program.exe
881 The output of this profiler looks like this:
883 Checkpoint at 102 for heap-resize
884 System.MonoType : 708
885 System.Threading.Thread : 352
887 System.String[] : 104
888 Gnome.ModuleInfo : 112
889 System.Object[] : 160
890 System.Collections.Hashtable : 96
892 System.Collections.Hashtable+Slot[] : 296
893 System.Globalization.CultureInfo : 108
894 System.Globalization.NumberFormatInfo : 144
897 The first line describes the iteration number for the GC, in this case
900 Then on each line the type is displayed as well as the number of bytes
901 that are being consumed by live instances of this object.
903 The AOT profiler is used to feed back information to the AOT compiler
904 about how to order code based on the access patterns for pages. To
907 mono --profile=aot program.exe
909 The output of this profile can be fed back into Mono's AOT compiler to
910 order the functions on the disk to produce precompiled images that
911 have methods in sequential pages.
913 Mono provides a mechanism for loading other profiling modules which in
914 the form of shared libraries. These profiling modules can hook up to
915 various parts of the Mono runtime to gather information about the code
918 To use a third party profiler you must pass the name of the profiler
922 mono --profile=custom program.exe
926 In the above sample Mono will load the user defined profiler from the
927 shared library `mono-profiler-custom.so'. This profiler module must
928 be on your dynamic linker library path.
930 A list of other third party profilers is available from Mono's web
931 site (www.mono-project.com/Performance_Tips)
933 Custom profiles are written as shared libraries. The shared library
934 must be called `mono-profiler-NAME.so' where `NAME' is the name of
937 For a sample of how to write your own custom profiler look in the
938 Mono source tree for in the samples/profiler.c.
940 Mono ships with a code coverage module. This module is activated by
941 using the Mono --profile=cov option. The format is:
942 \fB--profile=cov[:assembly-name[/namespace]] test-suite.exe\fR
944 By default code coverage will default to all the assemblies loaded,
945 you can limit this by specifying the assembly name, for example to
946 perform code coverage in the routines of your program use, for example
947 the following command line limits the code coverage to routines in the
951 mono --profile=cov:demo demo.exe
957 does not include the extension.
959 You can further restrict the code coverage output by specifying a
963 mono --profile=cov:demo/My.Utilities demo.exe
967 Which will only perform code coverage in the given assembly and
970 Typical output looks like this:
973 Not covered: Class:.ctor ()
974 Not covered: Class:A ()
975 Not covered: Driver:.ctor ()
976 Not covered: Driver:method ()
977 Partial coverage: Driver:Main ()
982 The offsets displayed are IL offsets.
984 A more powerful coverage tool is available in the module `monocov'.
985 See the monocov(1) man page for details.
987 To debug managed applications, you can use the
989 command, a command line debugger.
991 It is possible to obtain a stack trace of all the active threads in
992 Mono by sending the QUIT signal to Mono, you can do this from the
993 command line, like this:
999 Where pid is the Process ID of the Mono process you want to examine.
1000 The process will continue running afterwards, but its state is not
1004 this is a last-resort mechanism for debugging applications and should
1005 not be used to monitor or probe a production application. The
1006 integrity of the runtime after sending this signal is not guaranteed
1007 and the application might crash or terminate at any given point
1010 The \fB--debug=casts\fR option can be used to get more detailed
1011 information for Invalid Cast operations, it will provide information
1012 about the types involved.
1014 You can use the MONO_LOG_LEVEL and MONO_LOG_MASK environment variables
1015 to get verbose debugging output about the execution of your
1016 application within Mono.
1020 environment variable if set, the logging level is changed to the set
1021 value. Possible values are "error", "critical", "warning", "message",
1022 "info", "debug". The default value is "error". Messages with a logging
1023 level greater then or equal to the log level will be printed to
1026 Use "info" to track the dynamic loading of assemblies.
1031 environment variable to limit the extent of the messages you get:
1032 If set, the log mask is changed to the set value. Possible values are
1033 "asm" (assembly loader), "type", "dll" (native library loader), "gc"
1034 (garbage collector), "cfg" (config file loader), "aot" (precompiler) and "all".
1035 The default value is "all". Changing the mask value allows you to display only
1036 messages for a certain component. You can use multiple masks by comma
1037 separating them. For example to see config file messages and assembly loader
1038 messages set you mask to "asm,cfg".
1040 The following is a common use to track down problems with P/Invoke:
1043 $ MONO_LOG_LEVEL="debug" MONO_LOG_MASK="dll" mono glue.exe
1048 Mono's XML serialization engine by default will use a reflection-based
1049 approach to serialize which might be slow for continuous processing
1050 (web service applications). The serialization engine will determine
1051 when a class must use a hand-tuned serializer based on a few
1052 parameters and if needed it will produce a customized C# serializer
1053 for your types at runtime. This customized serializer then gets
1054 dynamically loaded into your application.
1056 You can control this with the MONO_XMLSERIALIZER_THS environment
1059 The possible values are
1061 to disable the use of a C# customized
1062 serializer, or an integer that is the minimum number of uses before
1063 the runtime will produce a custom serializer (0 will produce a
1064 custom serializer on the first access, 50 will produce a serializer on
1065 the 50th use). Mono will fallback to an interpreted serializer if the
1066 serializer generation somehow fails. This behavior can be disabled
1067 by setting the option
1069 (for example: MONO_XMLSERIALIZER_THS=0,nofallback).
1070 .SH ENVIRONMENT VARIABLES
1073 Turns off the garbage collection in Mono. This should be only used
1074 for debugging purposes
1077 When Mono is compiled with LLVM support, this instructs the runtime to
1078 stop using LLVM after the specified number of methods are JITed.
1079 This is a tool used in diagnostics to help isolate problems in the
1080 code generation backend. For example \fBLLVM_COUNT=10\fR would only
1081 compile 10 methods with LLVM and then switch to the Mono JIT engine.
1082 \fBLLVM_COUNT=0\fR would disable the LLVM engine altogether.
1084 \fBMONO_AOT_CACHE\fR
1085 If set, this variable will instruct Mono to ahead-of-time compile new
1086 assemblies on demand and store the result into a cache in
1090 If set, this variable overrides the default system configuration directory
1091 ($PREFIX/etc). It's used to locate machine.config file.
1094 Sets the style of COM interop. If the value of this variable is "MS"
1095 Mono will use string marhsalling routines from the liboleaut32 for the
1096 BSTR type library, any other values will use the mono-builtin BSTR
1100 If set, this variable overrides the default runtime configuration file
1101 ($PREFIX/etc/mono/config). The --config command line options overrides the
1102 environment variable.
1105 If set, enables some features of the runtime useful for debugging.
1106 This variable should contain a comma separated list of debugging options.
1107 Currently, the following options are supported:
1111 \fBbreak-on-unverified\fR
1112 If this variable is set, when the Mono VM runs into a verification
1113 problem, instead of throwing an exception it will break into the
1114 debugger. This is useful when debugging verifier problems
1116 \fBcollect-pagefault-stats\fR
1117 Collects information about pagefaults. This is used internally to
1118 track the number of page faults produced to load metadata. To display
1119 this information you must use this option with "--stats" command line
1122 \fBdont-free-domains\fR
1123 This is an Optimization for multi-AppDomain applications (most
1124 commonly ASP.NET applications). Due to internal limitations Mono,
1125 Mono by default does not use typed allocations on multi-appDomain
1126 applications as they could leak memory when a domain is unloaded.
1128 Although this is a fine default, for applications that use more than
1129 on AppDomain heavily (for example, ASP.NET applications) it is worth
1130 trading off the small leaks for the increased performance
1131 (additionally, since ASP.NET applications are not likely going to
1132 unload the application domains on production systems, it is worth
1133 using this feature).
1136 Captures the interrupt signal (Control-C) and displays a stack trace
1137 when pressed. Useful to find out where the program is executing at a
1138 given point. This only displays the stack trace of a single thread.
1140 \fBkeep-delegates\fR
1141 This option will leak delegate trampolines that are no longer
1142 referenced as to present the user with more information about a
1143 delegate misuse. Basically a delegate instance might be created,
1144 passed to unmanaged code, and no references kept in managed code,
1145 which will garbage collect the code. With this option it is possible
1146 to track down the source of the problems.
1148 \fBno-gdb-backtrace\fR
1149 This option will disable the GDB backtrace emitted by the runtime
1150 after a SIGSEGV or SIGABRT in unmanaged code.
1152 \fBsuspend-on-sigsegv\fR
1154 This option will suspend the program when a native SIGSEGV is received.
1155 This is useful for debugging crashes which do not happen under gdb,
1156 since a live process contains more information than a core file.
1160 \fBMONO_DISABLE_AIO\fR
1161 If set, tells mono NOT to attempt using native asynchronous I/O services. In
1162 that case, a default select/poll implementation is used. Currently only epoll()
1165 \fBMONO_DISABLE_MANAGED_COLLATION\fR
1166 If this environment variable is `yes', the runtime uses unmanaged
1167 collation (which actually means no culture-sensitive collation). It
1168 internally disables managed collation functionality invoked via the
1169 members of System.Globalization.CompareInfo class. Collation is
1172 \fBMONO_EGD_SOCKET\fR
1173 For platforms that do not otherwise have a way of obtaining random bytes
1174 this can be set to the name of a file system socket on which an egd or
1175 prngd daemon is listening.
1177 \fBMONO_EVENTLOG_TYPE\fR
1178 Sets the type of event log provider to use (for System.Diagnostics.EventLog).
1180 Possible values are:
1185 Persists event logs and entries to the local file system.
1187 The directory in which to persist the event logs, event sources and entries
1188 can be specified as part of the value.
1190 If the path is not explicitly set, it defaults to "/var/lib/mono/eventlog"
1191 on unix and "%APPDATA%\mono\eventlog" on Windows.
1196 Uses the native win32 API to write events and registers event logs and
1197 event sources in the registry. This is only available on Windows.
1199 On Unix, the directory permission for individual event log and event source
1200 directories is set to 777 (with +t bit) allowing everyone to read and write
1201 event log entries while only allowing entries to be deleted by the user(s)
1206 Silently discards any events.
1209 The default is "null" on Unix (and versions of Windows before NT), and
1210 "win32" on Windows NT (and higher).
1213 \fBMONO_EXTERNAL_ENCODINGS\fR
1214 If set, contains a colon-separated list of text encodings to try when
1215 turning externally-generated text (e.g. command-line arguments or
1216 filenames) into Unicode. The encoding names come from the list
1217 provided by iconv, and the special case "default_locale" which refers
1218 to the current locale's default encoding.
1220 When reading externally-generated text strings UTF-8 is tried first,
1221 and then this list is tried in order with the first successful
1222 conversion ending the search. When writing external text (e.g. new
1223 filenames or arguments to new processes) the first item in this list
1224 is used, or UTF-8 if the environment variable is not set.
1226 The problem with using MONO_EXTERNAL_ENCODINGS to process your
1227 files is that it results in a problem: although its possible to get
1228 the right file name it is not necessarily possible to open the file.
1229 In general if you have problems with encodings in your filenames you
1230 should use the "convmv" program.
1232 \fBMONO_GAC_PREFIX\fR
1233 Provides a prefix the runtime uses to look for Global Assembly Caches.
1234 Directories are separated by the platform path separator (colons on
1235 unix). MONO_GAC_PREFIX should point to the top directory of a prefixed
1236 install. Or to the directory provided in the gacutil /gacdir command. Example:
1237 .B /home/username/.mono:/usr/local/mono/
1240 Enables some filename rewriting support to assist badly-written
1241 applications that hard-code Windows paths. Set to a colon-separated
1242 list of "drive" to strip drive letters, or "case" to do
1243 case-insensitive file matching in every directory in a path. "all"
1244 enables all rewriting methods. (Backslashes are always mapped to
1245 slashes if this variable is set to a valid option.)
1248 For example, this would work from the shell:
1251 MONO_IOMAP=drive:case
1255 If you are using mod_mono to host your web applications, you can use
1258 directive instead, like this:
1261 MonoIOMAP <appalias> all
1264 See mod_mono(8) for more details.
1266 \fBMONO_MANAGED_WATCHER\fR
1267 If set to "disabled", System.IO.FileSystemWatcher will use a file watcher
1268 implementation which silently ignores all the watching requests.
1269 If set to any other value, System.IO.FileSystemWatcher will use the default
1270 managed implementation (slow). If unset, mono will try to use inotify, FAM,
1271 Gamin, kevent under Unix systems and native API calls on Windows, falling
1272 back to the managed implementation on error.
1275 If set causes the mono process to be bound to a single processor. This may be
1276 useful when debugging or working around race conditions.
1279 Provides a search path to the runtime where to look for library
1280 files. This is a tool convenient for debugging applications, but
1281 should not be used by deployed applications as it breaks the assembly
1282 loader in subtle ways.
1284 Directories are separated by the platform path separator (colons on unix). Example:
1285 .B /home/username/lib:/usr/local/mono/lib
1287 Alternative solutions to MONO_PATH include: installing libraries into
1288 the Global Assembly Cache (see gacutil(1)) or having the dependent
1289 libraries side-by-side with the main executable.
1291 For a complete description of recommended practices for application
1293 http://www.mono-project.com/Guidelines:Application_Deployment
1296 Experimental RTC support in the statistical profiler: if the user has
1297 the permission, more accurate statistics are gathered. The MONO_RTC
1298 value must be restricted to what the Linux rtc allows: power of two
1299 from 64 to 8192 Hz. To enable higher frequencies like 4096 Hz, run as root:
1302 echo 4096 > /proc/sys/dev/rtc/max-user-freq
1309 MONO_RTC=4096 mono --profiler=default:stat program.exe
1314 Disable inlining of thread local accesses. Try setting this if you get a segfault
1315 early on in the execution of mono.
1317 \fBMONO_SHARED_DIR\fR
1318 If set its the directory where the ".wapi" handle state is stored.
1319 This is the directory where the Windows I/O Emulation layer stores its
1320 shared state data (files, events, mutexes, pipes). By default Mono
1321 will store the ".wapi" directory in the users's home directory.
1323 \fBMONO_SHARED_HOSTNAME\fR
1324 Uses the string value of this variable as a replacement for the host name when
1325 creating file names in the ".wapi" directory. This helps if the host name of
1326 your machine is likely to be changed when a mono application is running or if
1327 you have a .wapi directory shared among several different computers.
1329 Mono typically uses the hostname to create the files that are used to
1330 share state across multiple Mono processes. This is done to support
1331 home directories that might be shared over the network.
1333 \fBMONO_STRICT_IO_EMULATION\fR
1334 If set, extra checks are made during IO operations. Currently, this
1335 includes only advisory locks around file writes.
1337 \fBMONO_DISABLE_SHM\fR
1338 If set, disables the shared memory files used for cross-process
1339 handles: process have only private handles. This means that process
1340 and thread handles are not available to other processes, and named
1341 mutexes, named events and named semaphores are not visible between
1344 This is can also be enabled by default by passing the
1345 "--disable-shared-handles" option to configure.
1348 The name of the theme to be used by Windows.Forms. Available themes today
1349 include "clearlooks", "nice" and "win32".
1351 The default is "win32".
1353 \fBMONO_TLS_SESSION_CACHE_TIMEOUT\fR
1354 The time, in seconds, that the SSL/TLS session cache will keep it's entry to
1355 avoid a new negotiation between the client and a server. Negotiation are very
1356 CPU intensive so an application-specific custom value may prove useful for
1357 small embedded systems.
1359 The default is 180 seconds.
1361 \fBMONO_THREADS_PER_CPU\fR
1362 The maximum number of threads in the general threadpool will be
1363 20 + (MONO_THREADS_PER_CPU * number of CPUs). The default value for this
1366 \fBMONO_XMLSERIALIZER_THS\fR
1367 Controls the threshold for the XmlSerializer to produce a custom
1368 serializer for a given class instead of using the Reflection-based
1369 interpreter. The possible values are `no' to disable the use of a
1370 custom serializer or a number to indicate when the XmlSerializer
1371 should start serializing. The default value is 50, which means that
1372 the a custom serializer will be produced on the 50th use.
1374 \fBMONO_XMLSERIALIZER_DEBUG\fR
1375 Set this value to 1 to prevent the serializer from removing the
1376 temporary files that are created for fast serialization; This might
1377 be useful when debugging.
1379 \fBMONO_ASPNET_INHIBIT_SETTINGSMAP\fR
1380 Mono contains a feature which allows modifying settings in the .config files shipped
1381 with Mono by using config section mappers. The mappers and the mapping rules are
1382 defined in the $prefix/etc/mono/2.0/settings.map file and, optionally, in the
1383 settings.map file found in the top-level directory of your ASP.NET application.
1384 Both files are read by System.Web on application startup, if they are found at the
1385 above locations. If you don't want the mapping to be performed you can set this
1386 variable in your environment before starting the application and no action will
1389 \fBMONO_MESSAGING_PROVIDER\fR
1390 Mono supports a plugin model for its implementation of System.Messaging making
1391 it possible to support a variety of messaging implementations (e.g. AMQP, ActiveMQ).
1392 To specify which messaging implementation is to be used the evironement variable
1393 needs to be set to the full class name for the provider. E.g. to use the RabbitMQ based
1394 AMQP implementation the variable should be set to:
1397 Mono.Messaging.RabbitMQ.RabbitMQMessagingProvider,Mono.Messaging.RabbitMQ
1398 .SH ENVIRONMENT VARIABLES FOR DEBUGGING
1400 \fBMONO_ASPNET_NODELETE\fR
1401 If set to any value, temporary source files generated by ASP.NET support
1402 classes will not be removed. They will be kept in the user's temporary
1405 \fBMONO_LOG_LEVEL\fR
1406 The logging level, possible values are `error', `critical', `warning',
1407 `message', `info' and `debug'. See the DEBUGGING section for more
1411 Controls the domain of the Mono runtime that logging will apply to.
1412 If set, the log mask is changed to the set value. Possible values are
1413 "asm" (assembly loader), "type", "dll" (native library loader), "gc"
1414 (garbage collector), "cfg" (config file loader), "aot" (precompiler) and "all".
1415 The default value is "all". Changing the mask value allows you to display only
1416 messages for a certain component. You can use multiple masks by comma
1417 separating them. For example to see config file messages and assembly loader
1418 messages set you mask to "asm,cfg".
1421 Used for runtime tracing of method calls. The format of the comma separated
1430 disabled Trace output off upon start.
1433 You can toggle trace output on/off sending a SIGUSR2 signal to the program.
1435 \fBMONO_TRACE_LISTENER\fR
1436 If set, enables the System.Diagnostics.DefaultTraceListener, which will
1437 print the output of the System.Diagnostics Trace and Debug classes.
1438 It can be set to a filename, and to Console.Out or Console.Error to display
1439 output to standard output or standard error, respectively. If it's set to
1440 Console.Out or Console.Error you can append an optional prefix that will
1441 be used when writing messages like this: Console.Error:MyProgramName.
1442 See the System.Diagnostics.DefaultTraceListener documentation for more
1445 \fBMONO_XEXCEPTIONS\fR
1446 This throws an exception when a X11 error is encountered; by default a
1447 message is displayed but execution continues
1450 This is used in the System.Windows.Forms implementation when running
1451 with the X11 backend. This is used to debug problems in Windows.Forms
1452 as it forces all of the commands send to X11 server to be done
1453 synchronously. The default mode of operation is asynchronous which
1454 makes it hard to isolate the root of certain problems.
1456 \fBMONO_GENERIC_SHARING\fR
1457 This environment variable controls the kind of generic sharing used.
1458 This variable is used by internal JIT developers and should not be
1459 changed in production. Do not use it.
1461 The variable controls which classes will have generic code sharing
1464 Permissible values are:
1468 All generated code can be shared.
1471 Only the classes in System.Collections.Generic will have its code
1472 shared (this is the default value).
1475 Only code in corlib will have its code shared.
1478 No generic code sharing will be performed.
1481 Generic code sharing by default only applies to collections. The
1482 Mono JIT by default turns this on.
1485 When the the MONO_XDEBUG env var is set, debugging info for JITted
1486 code is emitted into a shared library, loadable into gdb. This enables,
1487 for example, to see managed frame names on gdb backtraces.
1489 \fBMONO_VERBOSE_METHOD\fR
1490 Enables the maximum JIT verbosity for the specified method. This is
1491 very helpfull to diagnose a miscompilation problems of a specific
1494 If you want to use Valgrind, you will find the file `mono.supp'
1495 useful, it contains the suppressions for the GC which trigger
1496 incorrect warnings. Use it like this:
1498 valgrind --suppressions=mono.supp mono ...
1501 On some platforms, Mono can expose a set of DTrace probes (also known
1502 as user-land statically defined, USDT Probes).
1504 They are defined in the file `mono.d'.
1506 .B ves-init-begin, ves-init-end
1508 Begin and end of runtime initialization.
1510 .B method-compile-begin, method-compile-end
1512 Begin and end of method compilation.
1513 The probe arguments are class name, method name and signature,
1514 and in case of method-compile-end success or failure of compilation.
1518 Begin and end of Garbage Collection.
1520 To verify the availability of the probes, run:
1522 dtrace -P mono'$target' -l -c mono
1525 On Unix assemblies are loaded from the installation lib directory. If you set
1526 `prefix' to /usr, the assemblies will be located in /usr/lib. On
1527 Windows, the assemblies are loaded from the directory where mono and
1530 .B ~/.mono/aot-cache
1532 The directory for the ahead-of-time compiler demand creation
1533 assemblies are located.
1535 .B /etc/mono/config, ~/.mono/config
1537 Mono runtime configuration file. See the mono-config(5) manual page
1538 for more information.
1540 .B ~/.config/.mono/certs, /usr/share/.mono/certs
1542 Contains Mono certificate stores for users / machine. See the certmgr(1)
1543 manual page for more information on managing certificate stores and
1544 the mozroots(1) page for information on how to import the Mozilla root
1545 certificates into the Mono certificate store.
1547 .B ~/.mono/assemblies/ASSEMBLY/ASSEMBLY.config
1549 Files in this directory allow a user to customize the configuration
1550 for a given system assembly, the format is the one described in the
1551 mono-config(5) page.
1553 .B ~/.config/.mono/keypairs, /usr/share/.mono/keypairs
1555 Contains Mono cryptographic keypairs for users / machine. They can be
1556 accessed by using a CspParameters object with DSACryptoServiceProvider
1557 and RSACryptoServiceProvider classes.
1559 .B ~/.config/.isolatedstorage, ~/.local/share/.isolatedstorage, /usr/share/.isolatedstorage
1561 Contains Mono isolated storage for non-roaming users, roaming users and
1562 local machine. Isolated storage can be accessed using the classes from
1563 the System.IO.IsolatedStorage namespace.
1565 .B <assembly>.config
1567 Configuration information for individual assemblies is loaded by the
1568 runtime from side-by-side files with the .config files, see the
1569 http://www.mono-project.com/Config for more information.
1571 .B Web.config, web.config
1573 ASP.NET applications are configured through these files, the
1574 configuration is done on a per-directory basis. For more information
1575 on this subject see the http://www.mono-project.com/Config_system.web
1578 Mailing lists are listed at the
1579 http://www.mono-project.com/Mailing_Lists
1581 http://www.mono-project.com
1584 certmgr(1), csharp(1), mcs(1), mdb(1), monocov(1), monodis(1),
1585 mono-config(5), mozroots(1), pdb2mdb(1), xsp(1), mod_mono(8).
1587 For more information on AOT:
1588 http://www.mono-project.com/AOT
1590 For ASP.NET-related documentation, see the xsp(1) manual page