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 .B mono-sgen [options] file [arguments...]
17 \fImono\fP is a runtime implementation of the ECMA Common Language
18 Infrastructure. This can be used to run ECMA and .NET applications.
20 The runtime contains a native code generator that transforms the
21 Common Intermediate Language into native code.
23 The code generator can operate in two modes: just in time compilation
24 (JIT) or ahead of time compilation (AOT). Since code can be
25 dynamically loaded, the runtime environment and the JIT are always
26 present, even if code is compiled ahead of time.
28 The runtime loads the specified
35 is an ECMA assembly. They typically have a .exe or .dll extension.
37 The runtime provides a number of configuration options for running
38 applications, for developing and debugging, and for testing and
39 debugging the runtime itself.
41 The \fImono\fP command uses the Boehm conservative garbage collector
42 while the \fImono-sgen\fP command uses a moving and generational
45 On Unix-based systems, Mono provides a mechanism to emulate the
46 Windows-style file access, this includes providing a case insensitive
47 view of the file system, directory separator mapping (from \\ to /) and
48 stripping the drive letters.
50 This functionality is enabled by setting the
52 environment variable to one of
57 See the description for
59 in the environment variables section for more details.
61 The following options are available:
63 \fB--aot\fR, \fB--aot[=options]\fR
64 This option is used to precompile the CIL code in the specified
65 assembly to native code. The generated code is stored in a file with
66 the extension .so. This file will be automatically picked up by the
67 runtime when the assembly is executed.
69 Ahead-of-Time compilation is most useful if you use it in combination
70 with the -O=all,-shared flag which enables all of the optimizations in
71 the code generator to be performed. Some of those optimizations are
72 not practical for Just-in-Time compilation since they might be very
75 Unlike the .NET Framework, Ahead-of-Time compilation will not generate
76 domain independent code: it generates the same code that the
77 Just-in-Time compiler would produce. Since most applications use a
78 single domain, this is fine. If you want to optimize the generated
79 code for use in multi-domain applications, consider using the
82 This pre-compiles the methods, but the original assembly is still
83 required to execute as this one contains the metadata and exception
84 information which is not available on the generated file. When
85 precompiling code, you might want to compile with all optimizations
86 (-O=all). Pre-compiled code is position independent code.
88 Pre compilation is just a mechanism to reduce startup time, increase
89 code sharing across multiple mono processes and avoid just-in-time
90 compilation program startup costs. The original assembly must still
91 be present, as the metadata is contained there.
93 AOT code typically can not be moved from one computer to another
94 (CPU-specific optimizations that are detected at runtime) so you
95 should not try to move the pre-generated assemblies or package the
96 pre-generated assemblies for deployment.
98 A few options are available as a parameter to the
100 command line option. The options are separated by commas, and more
101 than one can be specified:
105 .I bind-to-runtime-version
107 If specified, forces the generated AOT files to be bound to the
108 runtime version of the compiling Mono. This will prevent the AOT
109 files from being consumed by a different Mono runtime.
111 This is currently an experimental feature as it is not complete.
112 This instructs Mono to precompile code that has historically not been
113 precompiled with AOT.
115 .I outfile=[filename]
116 Instructs the AOT compiler to save the output to the specified file.
119 Instructs the AOT compiler to emit debug symbol information.
121 .I save-temps,keep-temps
122 Instructs the AOT compiler to keep temporary files.
125 This is an experimental option for the AOT compiler to use multiple threads
126 when compiling the methods.
129 Instructs the AOT compiler to not output any debugging information.
131 .I ntrampolines=[number]
132 When compiling in full aot mode, the method trampolines must be precreated
133 in the AOT image. You can add additional method trampolines with this argument.
136 .I nrgctx-trampolines=[number]
137 When compiling in full aot mode, the generic sharing trampolines must be precreated
138 in the AOT image. You can add additional method trampolines with this argument.
141 .I nimt-trampolines=[number]
142 When compiling in full aot mode, the IMT trampolines must be precreated
143 in the AOT image. You can add additional method trampolines with this argument.
146 .I print-skipped-methods
147 If the AOT compiler cannot compile a method for any reason, enabling this flag
148 will output the skipped methods to the console.
151 The AOT compiler will emit a (ELF only) library initializer to automatically
152 register the aot compiled module with the runtime. This is only useful in static
156 Instructs the AOT compiler to output assembly code instead of an object file.
159 This instructs the compiler to generate sequence point checks that
160 allow Mono's soft debugger to debug applications even on systems where
161 it is not possible to set breakpoints or to single step (certain
162 hardware configurations like the cell phones and video gaming
166 Create an ELF object file (.o) which can be statically linked into an executable
167 when embedding the mono runtime. When this option is used, the object file needs to
168 be registered with the embedded runtime using the mono_aot_register_module function
169 which takes as its argument the mono_aot_module_<ASSEMBLY NAME>_info global symbol
170 from the object file:
173 extern void *mono_aot_module_hello_info;
175 mono_aot_register_module (mono_aot_module_hello_info);
180 For more information about AOT, see: http://www.mono-project.com/AOT
183 \fB--attach=[options]\fR
184 Currently the only option supported by this command line argument is
185 \fBdisable\fR which disables the attach functionality.
187 \fB--config filename\fR
188 Load the specified configuration file instead of the default one(s).
189 The default files are /etc/mono/config and ~/.mono/config or the file
190 specified in the MONO_CONFIG environment variable, if set. See the
191 mono-config(5) man page for details on the format of this file.
193 \fB--debugger-agent=[options]\fR
194 This instructs the Mono runtime to
195 start a debugging agent inside the Mono runtime and connect it to a
196 client user interface will control the Mono process.
197 This option is typically used by IDEs, like the MonoDevelop IDE.
200 configuration is specified using one of more of the following options:
204 .I transport=transport_name
206 This is used to specify the transport that the debugger will use to
207 communicate. It must be specified and currently requires this to
212 Use this option to specify the IP address where your debugger client is
217 Specifies the diagnostics log level for
221 Used to specify the file where the log will be stored, it defaults to
227 Configures the virtual machine to be better suited for desktop
228 applications. Currently this sets the GC system to avoid expanding
229 the heap as much as possible at the expense of slowing down garbage
233 This is an experimental flag that instructs the Mono runtime to not
234 generate any code at runtime and depend exclusively on the code
235 generated from using mono --aot=full previously. This is useful for
236 platforms that do not permit dynamic code generation.
238 Notice that this feature will abort execution at runtime if a codepath
239 in your program, or Mono's class libraries attempts to generate code
240 dynamically. You should test your software upfront and make sure that
241 you do not use any dynamic features.
243 \fB--gc=boehm\fR, \fB--gc=sgen\fR
244 Selects the Garbage Collector engine for Mono to use, Boehm or SGen.
245 Currently this merely ensures that you are running either the
246 \fImono\fR or \fImono-sgen\fR commands. This flag can be set in the
247 \fBMONO_ENV_OPTIONS\fR environment variable to force all of your child
248 processes to use one particular kind of GC with the Mono runtime.
250 \fB--help\fR, \fB-h\fR
251 Displays usage instructions.
254 If the Mono runtime has been compiled with LLVM support (not available
255 in all configurations), Mono will use the LLVM optimization and code
256 generation engine to JIT or AOT compile.
258 For more information, consult: http://www.mono-project.com/Mono_LLVM
261 When using a Mono that has been compiled with LLVM support, it forces
262 Mono to fallback to its JIT engine and not use the LLVM backend.
264 \fB--optimize=MODE\fR, \fB-O=MODE\fR
265 MODE is a comma separated list of optimizations. They also allow
266 optimizations to be turned off by prefixing the optimization name with
269 In general, Mono has been tuned to use the default set of flags,
270 before using these flags for a deployment setting, you might want to
271 actually measure the benefits of using them.
273 The following optimizations are implemented:
275 all Turn on all optimizations
276 peephole Peephole postpass
277 branch Branch optimizations
278 inline Inline method calls
279 cfold Constant folding
280 consprop Constant propagation
281 copyprop Copy propagation
282 deadce Dead code elimination
283 linears Linear scan global reg allocation
284 cmov Conditional moves [arch-dependency]
285 shared Emit per-domain code
286 sched Instruction scheduling
287 intrins Intrinsic method implementations
288 tailc Tail recursion and tail calls
289 loop Loop related optimizations
290 fcmov Fast x86 FP compares [arch-dependency]
291 leaf Leaf procedures optimizations
292 aot Usage of Ahead Of Time compiled code
293 precomp Precompile all methods before executing Main
294 abcrem Array bound checks removal
295 ssapre SSA based Partial Redundancy Elimination
296 sse2 SSE2 instructions on x86 [arch-dependency]
297 gshared Enable generic code sharing.
300 For example, to enable all the optimization but dead code
301 elimination and inlining, you can use:
303 -O=all,-deadce,-inline
306 The flags that are flagged with [arch-dependency] indicate that the
307 given option if used in combination with Ahead of Time compilation
308 (--aot flag) would produce pre-compiled code that will depend on the
309 current CPU and might not be safely moved to another computer.
311 \fB--runtime=VERSION\fR
312 Mono supports different runtime versions. The version used depends on the program
313 that is being run or on its configuration file (named program.exe.config). This option
314 can be used to override such autodetection, by forcing a different runtime version
315 to be used. Note that this should only be used to select a later compatible runtime
316 version than the one the program was compiled against. A typical usage is for
317 running a 1.1 program on a 2.0 version:
319 mono --runtime=v2.0.50727 program.exe
322 \fB--security\fR, \fB--security=mode\fR
323 Activate the security manager, a currently experimental feature in
324 Mono and it is OFF by default. The new code verifier can be enabled
325 with this option as well.
329 Using security without parameters is equivalent as calling it with the
332 The following modes are supported:
335 This allows mono to support declarative security attributes,
336 e.g. execution of Code Access Security (CAS) or non-CAS demands.
339 Enables the core-clr security system, typically used for
340 Moonlight/Silverlight applications. It provides a much simpler
341 security system than CAS, see http://www.mono-project.com/Moonlight
342 for more details and links to the descriptions of this new system.
345 Enables the new verifier and performs basic verification for code
346 validity. In this mode, unsafe code and P/Invoke are allowed. This
347 mode provides a better safety guarantee but it is still possible
348 for managed code to crash Mono.
351 Enables the new verifier and performs full verification of the code
352 being executed. It only allows verifiable code to be executed.
353 Unsafe code is not allowed but P/Invoke is. This mode should
354 not allow managed code to crash mono. The verification is not as
355 strict as ECMA 335 standard in order to stay compatible with the MS
358 The security system acts on user code: code contained in mscorlib or
359 the global assembly cache is always trusted.
364 Configures the virtual machine to be better suited for server
365 operations (currently, a no-op).
368 Verifies mscorlib and assemblies in the global
369 assembly cache for valid IL, and all user code for IL
372 This is different from \fB--security\fR's verifiable
373 or validil in that these options only check user code and skip
374 mscorlib and assemblies located on the global assembly cache.
376 \fB-V\fR, \fB--version\fR
377 Prints JIT version information (system configuration, release number
378 and branch names if available).
381 .SH DEVELOPMENT OPTIONS
382 The following options are used to help when developing a JITed application.
384 \fB--debug\fR, \fB--debug=OPTIONS\fR
385 Turns on the debugging mode in the runtime. If an assembly was
386 compiled with debugging information, it will produce line number
387 information for stack traces.
391 The optional OPTIONS argument is a comma separated list of debugging
392 options. These options are turned off by default since they generate
393 much larger and slower code at runtime.
395 The following options are supported:
398 Produces a detailed error when throwing a InvalidCastException. This
399 option needs to be enabled as this generates more verbose code at
403 Disable some JIT optimizations which are usually only disabled when
404 running inside the debugger. This can be helpful if you want to attach
405 to the running process with mdb.
408 Generate and register debugging information with gdb. This is only supported on some
409 platforms, and only when using gdb 7.0 or later.
413 \fB--profile[=profiler[:profiler_args]]\fR
414 Turns on profiling. For more information about profiling applications
415 and code coverage see the sections "PROFILING" and "CODE COVERAGE"
418 This option can be used multiple times, each time will load an
419 additional profiler. This allows developers to use modules that
420 extend the JIT through the Mono profiling interface.
422 \fB--trace[=expression]\fR
423 Shows method names as they are invoked. By default all methods are
426 The trace can be customized to include or exclude methods, classes or
427 assemblies. A trace expression is a comma separated list of targets,
428 each target can be prefixed with a minus sign to turn off a particular
429 target. The words `program', `all' and `disabled' have special
430 meaning. `program' refers to the main program being executed, and
431 `all' means all the method calls.
433 The `disabled' option is used to start up with tracing disabled. It
434 can be enabled at a later point in time in the program by sending the
435 SIGUSR2 signal to the runtime.
437 Assemblies are specified by their name, for example, to trace all
438 calls in the System assembly, use:
441 mono --trace=System app.exe
444 Classes are specified with the T: prefix. For example, to trace all
445 calls to the System.String class, use:
448 mono --trace=T:System.String app.exe
451 And individual methods are referenced with the M: prefix, and the
452 standard method notation:
455 mono --trace=M:System.Console:WriteLine app.exe
458 Exceptions can also be traced, it will cause a stack trace to be
459 printed every time an exception of the specified type is thrown.
460 The exception type can be specified with or without the namespace,
461 and to trace all exceptions, specify 'all' as the type name.
464 mono --trace=E:System.Exception app.exe
467 As previously noted, various rules can be specified at once:
470 mono --trace=T:System.String,T:System.Random app.exe
473 You can exclude pieces, the next example traces calls to
474 System.String except for the System.String:Concat method.
477 mono --trace=T:System.String,-M:System.String:Concat
480 Finally, namespaces can be specified using the N: prefix:
483 mono --trace=N:System.Xml
487 \fB--no-x86-stack-align\fR
488 Don't align stack frames on the x86 architecture. By default, Mono
489 aligns stack frames to 16 bytes on x86, so that local floating point
490 and SIMD variables can be properly aligned. This option turns off the
491 alignment, which usually saves one intruction per call, but might
492 result in significantly lower floating point and SIMD performance.
495 Generate a JIT method map in a /tmp/perf-PID.map file. This file is then
496 used, for example, by the perf tool included in recent Linux kernels.
497 Each line in the file has:
500 HEXADDR HEXSIZE methodname
503 Currently this option is only supported on Linux.
504 .SH JIT MAINTAINER OPTIONS
505 The maintainer options are only used by those developing the runtime
506 itself, and not typically of interest to runtime users or developers.
509 Inserts a breakpoint before the method whose name is `method'
510 (namespace.class:methodname). Use `Main' as method name to insert a
511 breakpoint on the application's main method.
514 Inserts a breakpoint on exceptions. This allows you to debug your
515 application with a native debugger when an exception is thrown.
518 This compiles a method (namespace.name:methodname), this is used for
519 testing the compiler performance or to examine the output of the code
523 Compiles all the methods in an assembly. This is used to test the
524 compiler performance or to examine the output of the code generator
526 \fB--graph=TYPE METHOD\fR
527 This generates a postscript file with a graph with the details about
528 the specified method (namespace.name:methodname). This requires `dot'
529 and ghostview to be installed (it expects Ghostview to be called
532 The following graphs are available:
534 cfg Control Flow Graph (CFG)
536 code CFG showing code
537 ssa CFG showing code after SSA translation
538 optcode CFG showing code after IR optimizations
541 Some graphs will only be available if certain optimizations are turned
545 Instruct the runtime on the number of times that the method specified
546 by --compile (or all the methods if --compileall is used) to be
547 compiled. This is used for testing the code generator performance.
550 Displays information about the work done by the runtime during the
551 execution of an application.
553 \fB--wapi=hps|semdel\fR
554 Perform maintenance of the process shared data.
556 semdel will delete the global semaphore.
558 hps will list the currently used handles.
560 \fB-v\fR, \fB--verbose\fR
561 Increases the verbosity level, each time it is listed, increases the
562 verbosity level to include more information (including, for example,
563 a disassembly of the native code produced, code selector info etc.).
565 The Mono runtime allows external processes to attach to a running
566 process and load assemblies into the running program. To attach to
567 the process, a special protocol is implemented in the Mono.Management
570 With this support it is possible to load assemblies that have an entry
571 point (they are created with -target:exe or -target:winexe) to be
572 loaded and executed in the Mono process.
574 The code is loaded into the root domain, and it starts execution on
575 the special runtime attach thread. The attached program should
576 create its own threads and return after invocation.
578 This support allows for example debugging applications by having the
579 csharp shell attach to running processes.
581 The mono runtime includes a profiler that can be used to explore
582 various performance related problems in your application. The
583 profiler is activated by passing the --profile command line argument
584 to the Mono runtime, the format is:
587 --profile[=profiler[:profiler_args]]
590 Mono has a built-in profiler called 'default' (and is also the default
591 if no arguments are specified), but developers can write custom
592 profilers, see the section "CUSTOM PROFILERS" for more details.
596 is not specified, the default profiler is used.
600 is a profiler-specific string of options for the profiler itself.
602 The default profiler accepts the following options 'alloc' to profile
603 memory consumption by the application; 'time' to profile the time
604 spent on each routine; 'jit' to collect time spent JIT-compiling methods
605 and 'stat' to perform sample statistical profiling.
606 If no options are provided the default is 'alloc,time,jit'.
609 profile data is printed to stdout: to change this, use the 'file=filename'
610 option to output the data to filename.
615 mono --profile program.exe
619 That will run the program with the default profiler and will do time
620 and allocation profiling.
624 mono --profile=default:stat,alloc,file=prof.out program.exe
627 Will do sample statistical profiling and allocation profiling on
628 program.exe. The profile data is put in prof.out.
630 Note that the statistical profiler has a very low overhead and should
631 be the preferred profiler to use (for better output use the full path
632 to the mono binary when running and make sure you have installed the
633 addr2line utility that comes from the binutils package).
638 is a general purpose profiler that can track many different kinds of
639 events and logs those into a file as the program executes. This is
640 different than previous profilers in Mono that kept the information in
641 memory and rendered a summary of the results when the program shut
644 Using the logging profiler means that useful information can be
645 gathered for long-running applications, applications that terminate
646 abormally (crashes, segfaults, complicated tear down processes) or
647 when no data about the shutdown is required.
649 The data collected by the running threads is kept independent of each
650 other to minimize the runtime overhead and the information dumped into
651 the log at regular intervals.
653 A sample use is very simple:
655 $ mono --profile=logging program.exe
657 $ mprof-decoder program.mprof
660 In the above example the logging profiler is used in its default mode
661 that merely records GC statistics for the execution of program.exe.
662 The profiling data collected is stored in the file program.mprof. The
663 mprof-decoder tool is then used to analyze the data.
665 You can instruct the logging profiler to record different one or more
666 sets of events. These are the modes supported:
668 .I Statistical Profiling (stat)
669 the program instruction pointer is periodically sampled to determine
670 where the program is spending most of its time. Statistical
671 profiling has a very low impact on a running application and it is
672 very useful to get a general picture of where time is being spent on a
675 If call chains are requested, for each sample the profiler gets a
676 partial stack trace (limited by the specified depth) so that
677 caller-callee information is available.
680 each method enter and exit is logged with a timestamp; further processing of
681 the data can show the methods that took the longer to execute, with complete
682 accounting for callers and callees. However, this way of profiling is rather
683 intrusive and slows down the application significantly.
686 each allocation is logged.
688 .I Allocation summary:
689 shows, for each collection, a summary of the heap contents broken down by
690 class (for each class the number of allocated and released objects is
691 given, together with their aggregated size in bytes).
693 .I Heap snapshot mode:
694 dumps the whole heap contents at every collection (or at user specified
695 collections). It is also possible to request a collection and snapshot dump
698 Moreover, other events can be logged and analyzed, like jit time for each
699 method, load and unload for assemblies, modules and and individual classes,
700 and appdomain and thread creation and destruction.
702 This profiler is activated passing the \fB--profile=logging\fR option to
703 the mono runtime, and is controlled attaching further options, like
704 \fB--profile=logging:statistical\fR for doing statistical profiling (multiple
705 options are separated by commas).
707 As a quick primer, here are a few examples of the most common usage modes:
709 To perform statistical profiling:
712 mono --profile=logging:stat program.exe
715 To perform statistical profiling, inspecting call chains up to depth 8:
718 mono --profile=logging:stat=8 program.exe
721 To profile allocations (by default the call stack will be analized for
722 each allocation, producing detailed caller method attribution infornation):
725 mono --profile=logging:allocations program.exe
728 To profile garbage collection activity at a high level (collection time and objects freed
729 at each collection for each class are reported, but heap snapshots are not saved to disk):
732 mono --profile=logging:allocations-summary program.exe
735 To perform heap profiling taking heap snapshots:
738 mono --profile=logging:heap=all program.exe
741 To write the resulting data to a different file:
744 mono --profile=logging:output=mydata.mprof program.exe
747 Then you would need to invoke the decoder \fImprof-decoder(1)\fR
748 on the output file to see the profiling results, or to examine heap
749 snapshots and allocations in detail \fImprof-heap-viewer(1)\fR.
751 The operating modes described above are the default ones, and are sufficient
754 To further customize the profiler behavior there are more options, described
757 These options can be individually enabled and disabled prefixing them
758 with an (optional) '+' character or a '-' character. For instance,
759 the "allocations" option by default records also the full call stack
760 at each allocation. If only the caller is wanted, one should use
761 "allocations,-save-allocation-stack", or to disable call tracking
762 completely (making the profiler less intrusive)
763 "allocations,-save-allocation-caller,-save-allocation-stack". In
764 practice the "allocation" option by default behaves like
765 "allocations,save-allocation-caller,save-allocation-stack", but the
766 user can tune this to his needs.
768 These are all the available options, organized by category:
770 \fBExecution profiling modes\fR
774 \fIstatistical\fR, \fIstat\fR or \fIs\fR
775 Performs statistical profiling. This is a lightweight profiling
776 mechanism and it has a much lower overhead than the \fIenter-leave\fR
777 profiling as it works by sampling where the program is spending its
778 time by using a timer.
779 If specified with \fIs=<number>\fR, also inspect call chains up to level
782 \fIenter-leave\fR, \fIcalls\fR or \fIc\fR
783 Measure the time spent inside each method call, this is done by
784 logging the time when a method enters and when the method leaves.
785 This can be a time consuming operation.
788 Collect information about time spent by the JIT engine compiling
793 \fBAllocation profiling modes\fR
797 \fIallocations\fR, \fIalloc\fR or \fIa\fR
798 Collect information about each allocation (object class and size).
799 By default this also implies "+save-allocation-caller" and
800 "+save-allocation-stack".
802 \fIsave-allocation-caller\fR, \fIsac\fR
803 Save the direct caller of each allocation. The profiler filters out wrapper
804 methods, and also recognizes if the allocation has been performed by the
805 runtime while jitting a method.
807 \fIsave-allocation-stack\fR, \fIsas\fR
808 Save the full managed execution stack at each allocation.
809 While the "sac" option saves the direct caller, this one records the whole
811 Note that in the call stack the wrapper methods are not filtered out.
812 Anyway the "sac" and "sas" options can be combined, and the decoder will
813 attribute the allocation to the correct method even if the wrapper is at the
814 top of the stack trace.
816 \fIallocations-summary\fR or \fIas\fR
817 At each collection dump a summary
818 of the heap contents (for each class, the number and collective size of all
819 live and freed heap objects). This very lightweight compared to full heap
822 \fIunreachable\fR, \fIfree\fR or \fIf\fR
823 Performs a lightweight profile of the garbage collector. On each
824 collection performed by the GC, the list of unreachable objects is
825 recorded, and for each object the class and size is provided. This
826 information can be used to compute the heap size broken down by class
827 (combined with "a" can give the same information of "as", but the log
828 file contains info about each individual object, while in "as" the
829 processing is done directly at runtime and the log file contains only
830 the summarized data broken down by class).
833 Measure the time spent in each collection, and also trace heap resizes.
835 \fIheap-shot[=ARG]\fR, \fIheap[=ARG]\fR or \fIh[=ARH]\fR
836 Performs full heap profiling. In this case on each
837 collection a full heap snapshot is recorded to disk.
838 Inside the snapshots, each object reference is still represented so
839 that it's possible to investigate who is responsible for keeping objects
842 If the value of ARG is
844 a heap snapshot is taken at each collection.
846 If the value is an integer
848 a snapshot will be taken at the first
850 collections (like setting
854 If no additional argument is given to the heap option, the only way to take
855 heap snapshots is to requeste them using the runtime socket based command
856 interface described below (see "Profiler activity control").
858 Heap profiling also enables full allocation profiling (with call
859 stacks), and each allocation can be related to its corresponding
860 object in the snapshots, enabling investigations like "find all
861 objects of a given class allocated by a given method and still live at
862 a given collection, and then find all objects referencing them".
864 This kind of heap snapshot analysis is performed using the mprof-heap-viewer(1)
867 The number of heap snapshots taken (and the moment in which they are taken)
868 can be further customized with the following options:
870 \fIgc-dumps=N\fR, \fIgc-d=N\fR, \fIgcd=N\fR
871 states the number of snapshots that must be dumped (since the application
872 starts). Zero means no dumps at all, -1 means dump at all collections.
874 These options exist because it can happen that the user wants to investigate
875 what happens during collections but without forcing a collection using the
876 command interface, because forcing a collection alters the program behavior.
877 Of course it is possible to simply take a snapshot at every collection, but
878 in some workloads this is could not be feasible (too much data).
879 So we have this "garbage collection dumps" counter to control how many
884 \fBProfiler activity control\fR
888 \fIoutput=FILE\fR, \fIout=FILE\fR or \fIo=FILE\fR
889 Use this option to provide the output file name for the profile log.
890 If this option is not specified, it will default to "<program-name>.mprof".
892 \fIoutput-suffix=SUFFIX\fR, \fIsuffix=SUFFIX\fR or \fIos=SUFFIX\fR: makes
893 the output file name equals to "<program-name>-SUFFIX.mprof".
895 \fIstart-enabled\fR or \fIse\fR: start with the profiler active
896 (which is the default).
898 \fIstart-disabled\fR or \fIsd\fR: start with the profiler inactive.
900 \fIforce-accurate-timer\fR (or \fIfac\fR): the profiler by default uses
901 rtdsc to acquire timestamps for frequent events, but this can be imprecise;
902 using this option you force the use of "gettimeofday" at every event, which
903 is more accurate but much slower.
905 \fIcommand-port=port\fR or \fIcp=port\fR (where port is an integer between
907 Choose a TCP port where the profiler will listen for user commands.
908 The protocol is ASCII based and line oriented (one line per command), and the
909 profiler answers with one line containing either "OK" or "ERROR" to each
912 The user can telnet to this port and give commands manually, or a GUI can
913 use this facility to control the profiler at runtime.
915 The available commands are:
917 \fIenable\fR: Enables the profiler.
919 \fIdisable\fR: Disables the profiler.
921 \fIheap-snapshot\fR: Takes a heap snapshot now (forces a full garbage collection).
923 \fIheap-snapshot-counter=arg\fR: Set the counter of the next heap snapshots
924 that must be taken, where arg can be "all" (take a snapshot at every
925 collection), "none" (do not take snapshots), or an integer "n" (take a heap
926 snapshot for the next "n" collections).
930 \fBInternal buffer sizes\fR
934 \fIper-thread-buffer-size=N\fR, \fItbs=N\fR
935 Use to specify the number of events that a thread buffer
936 can hold. When the thread buffer is full, a log block is
939 This defaults to tbs=10000.
941 \fIstatistical-thread-buffer-size=N\fR, \fIsbs=N\fR
942 The number of statistical samples that
943 are held in memory before they are dumped to disk (the system does
944 double-buffering and the statistical samples are written by a helper
945 thread, so the statistical profiler never stops and is able to profile
946 the profiler itself).
948 This defaults to sbs=10000.
950 \fIwrite-buffer-size\fR, \fIwbs\fR
951 Specifies the size in bytes of the internal write buffers.
953 This defaults to wbs=1024.
957 In its current state, this profiler can also perform heap analysis
958 like the HeapShot profiler, but there is no UI to process this
961 Another known issue is that if the timer is not strictly monotonic (like
962 rtdsc), differences between times can underflow (they are handled as
963 unsigned integers) and weird numbers can show up in the logs.
965 Finally, it can happen that when exceptions are thrown the profiler temporarily
966 loses track of the execution stack and misattributes the caller for a few
967 allocations (and method execution time).
969 The output file contains compressed events, to process the data you should
970 use tools like the "Mono.Profiler" tool provided on the Mono SVN
973 More explanations are provided here: "http://www.mono-project.com/LoggingProfiler".
974 .SH EXTERNAL PROFILERS
975 There are a number of external profilers that have been developed for
976 Mono, we will update this section to contain the profilers.
978 The heap Shot profiler can track all live objects, and references to
979 these objects, and includes a GUI tool, this is our recommended
981 To install you must download the profiler
984 svn co svn://anonsvn.mono-project.com/source/trunk/heap-shot
991 See the included documentation for details on using it.
993 The Live Type profiler shows at every GC iteration all of the live
994 objects of a given type. To install you must download the profiler
997 svn co svn://anonsvn.mono-project.com/source/trunk/heap-prof
1004 To use the profiler, execute:
1006 mono --profile=desc-heap program.exe
1009 The output of this profiler looks like this:
1011 Checkpoint at 102 for heap-resize
1012 System.MonoType : 708
1013 System.Threading.Thread : 352
1014 System.String : 3230
1015 System.String[] : 104
1016 Gnome.ModuleInfo : 112
1017 System.Object[] : 160
1018 System.Collections.Hashtable : 96
1019 System.Int32[] : 212
1020 System.Collections.Hashtable+Slot[] : 296
1021 System.Globalization.CultureInfo : 108
1022 System.Globalization.NumberFormatInfo : 144
1025 The first line describes the iteration number for the GC, in this case
1028 Then on each line the type is displayed as well as the number of bytes
1029 that are being consumed by live instances of this object.
1031 The AOT profiler is used to feed back information to the AOT compiler
1032 about how to order code based on the access patterns for pages. To
1035 mono --profile=aot program.exe
1037 The output of this profile can be fed back into Mono's AOT compiler to
1038 order the functions on the disk to produce precompiled images that
1039 have methods in sequential pages.
1040 .SH CUSTOM PROFILERS
1041 Mono provides a mechanism for loading other profiling modules which in
1042 the form of shared libraries. These profiling modules can hook up to
1043 various parts of the Mono runtime to gather information about the code
1046 To use a third party profiler you must pass the name of the profiler
1050 mono --profile=custom program.exe
1054 In the above sample Mono will load the user defined profiler from the
1055 shared library `mono-profiler-custom.so'. This profiler module must
1056 be on your dynamic linker library path.
1058 A list of other third party profilers is available from Mono's web
1059 site (www.mono-project.com/Performance_Tips)
1061 Custom profiles are written as shared libraries. The shared library
1062 must be called `mono-profiler-NAME.so' where `NAME' is the name of
1065 For a sample of how to write your own custom profiler look in the
1066 Mono source tree for in the samples/profiler.c.
1068 Mono ships with a code coverage module. This module is activated by
1069 using the Mono --profile=cov option. The format is:
1070 \fB--profile=cov[:assembly-name[/namespace]] test-suite.exe\fR
1072 By default code coverage will default to all the assemblies loaded,
1073 you can limit this by specifying the assembly name, for example to
1074 perform code coverage in the routines of your program use, for example
1075 the following command line limits the code coverage to routines in the
1079 mono --profile=cov:demo demo.exe
1085 does not include the extension.
1087 You can further restrict the code coverage output by specifying a
1091 mono --profile=cov:demo/My.Utilities demo.exe
1095 Which will only perform code coverage in the given assembly and
1098 Typical output looks like this:
1101 Not covered: Class:.ctor ()
1102 Not covered: Class:A ()
1103 Not covered: Driver:.ctor ()
1104 Not covered: Driver:method ()
1105 Partial coverage: Driver:Main ()
1110 The offsets displayed are IL offsets.
1112 A more powerful coverage tool is available in the module `monocov'.
1113 See the monocov(1) man page for details.
1115 To debug managed applications, you can use the
1117 command, a command line debugger.
1119 It is possible to obtain a stack trace of all the active threads in
1120 Mono by sending the QUIT signal to Mono, you can do this from the
1121 command line, like this:
1127 Where pid is the Process ID of the Mono process you want to examine.
1128 The process will continue running afterwards, but its state is not
1132 this is a last-resort mechanism for debugging applications and should
1133 not be used to monitor or probe a production application. The
1134 integrity of the runtime after sending this signal is not guaranteed
1135 and the application might crash or terminate at any given point
1138 The \fB--debug=casts\fR option can be used to get more detailed
1139 information for Invalid Cast operations, it will provide information
1140 about the types involved.
1142 You can use the MONO_LOG_LEVEL and MONO_LOG_MASK environment variables
1143 to get verbose debugging output about the execution of your
1144 application within Mono.
1148 environment variable if set, the logging level is changed to the set
1149 value. Possible values are "error", "critical", "warning", "message",
1150 "info", "debug". The default value is "error". Messages with a logging
1151 level greater then or equal to the log level will be printed to
1154 Use "info" to track the dynamic loading of assemblies.
1159 environment variable to limit the extent of the messages you get:
1160 If set, the log mask is changed to the set value. Possible values are
1161 "asm" (assembly loader), "type", "dll" (native library loader), "gc"
1162 (garbage collector), "cfg" (config file loader), "aot" (precompiler),
1163 "security" (e.g. Moonlight CoreCLR support) and "all".
1164 The default value is "all". Changing the mask value allows you to display only
1165 messages for a certain component. You can use multiple masks by comma
1166 separating them. For example to see config file messages and assembly loader
1167 messages set you mask to "asm,cfg".
1169 The following is a common use to track down problems with P/Invoke:
1172 $ MONO_LOG_LEVEL="debug" MONO_LOG_MASK="dll" mono glue.exe
1177 Mono's XML serialization engine by default will use a reflection-based
1178 approach to serialize which might be slow for continuous processing
1179 (web service applications). The serialization engine will determine
1180 when a class must use a hand-tuned serializer based on a few
1181 parameters and if needed it will produce a customized C# serializer
1182 for your types at runtime. This customized serializer then gets
1183 dynamically loaded into your application.
1185 You can control this with the MONO_XMLSERIALIZER_THS environment
1188 The possible values are
1190 to disable the use of a C# customized
1191 serializer, or an integer that is the minimum number of uses before
1192 the runtime will produce a custom serializer (0 will produce a
1193 custom serializer on the first access, 50 will produce a serializer on
1194 the 50th use). Mono will fallback to an interpreted serializer if the
1195 serializer generation somehow fails. This behavior can be disabled
1196 by setting the option
1198 (for example: MONO_XMLSERIALIZER_THS=0,nofallback).
1199 .SH ENVIRONMENT VARIABLES
1202 Turns off the garbage collection in Mono. This should be only used
1203 for debugging purposes
1206 When Mono is compiled with LLVM support, this instructs the runtime to
1207 stop using LLVM after the specified number of methods are JITed.
1208 This is a tool used in diagnostics to help isolate problems in the
1209 code generation backend. For example \fBLLVM_COUNT=10\fR would only
1210 compile 10 methods with LLVM and then switch to the Mono JIT engine.
1211 \fBLLVM_COUNT=0\fR would disable the LLVM engine altogether.
1213 \fBMONO_AOT_CACHE\fR
1214 If set, this variable will instruct Mono to ahead-of-time compile new
1215 assemblies on demand and store the result into a cache in
1218 \fBMONO_ASPNET_INHIBIT_SETTINGSMAP\fR
1219 Mono contains a feature which allows modifying settings in the .config files shipped
1220 with Mono by using config section mappers. The mappers and the mapping rules are
1221 defined in the $prefix/etc/mono/2.0/settings.map file and, optionally, in the
1222 settings.map file found in the top-level directory of your ASP.NET application.
1223 Both files are read by System.Web on application startup, if they are found at the
1224 above locations. If you don't want the mapping to be performed you can set this
1225 variable in your environment before starting the application and no action will
1229 If set, this variable overrides the default system configuration directory
1230 ($PREFIX/etc). It's used to locate machine.config file.
1233 Sets the style of COM interop. If the value of this variable is "MS"
1234 Mono will use string marhsalling routines from the liboleaut32 for the
1235 BSTR type library, any other values will use the mono-builtin BSTR
1239 If set, this variable overrides the default runtime configuration file
1240 ($PREFIX/etc/mono/config). The --config command line options overrides the
1241 environment variable.
1244 Override the automatic cpu detection mechanism. Currently used only on arm.
1245 The format of the value is as follows:
1251 where V is the architecture number 4, 5, 6, 7 and the options can be currently be
1255 MONO_CPU_ARCH="armv4 thumb" mono ...
1259 \fBMONO_DISABLE_AIO\fR
1260 If set, tells mono NOT to attempt using native asynchronous I/O services. In
1261 that case, a default select/poll implementation is used. Currently only epoll()
1264 \fBMONO_DISABLE_MANAGED_COLLATION\fR
1265 If this environment variable is `yes', the runtime uses unmanaged
1266 collation (which actually means no culture-sensitive collation). It
1267 internally disables managed collation functionality invoked via the
1268 members of System.Globalization.CompareInfo class. Collation is
1271 \fBMONO_DISABLE_SHM\fR
1272 Unix only: If set, disables the shared memory files used for
1273 cross-process handles: process have only private handles. This means
1274 that process and thread handles are not available to other processes,
1275 and named mutexes, named events and named semaphores are not visible
1278 This is can also be enabled by default by passing the
1279 "--disable-shared-handles" option to configure.
1281 This is the default from mono 2.8 onwards.
1283 \fBMONO_EGD_SOCKET\fR
1284 For platforms that do not otherwise have a way of obtaining random bytes
1285 this can be set to the name of a file system socket on which an egd or
1286 prngd daemon is listening.
1288 \fBMONO_ENABLE_SHM\fR
1289 Unix only: Enable support for cross-process handles. Cross-process
1290 handles are used to expose process handles, thread handles, named
1291 mutexes, named events and named semaphores across Unix processes.
1293 \fBMONO_ENV_OPTIONS\fR
1294 This environment variable allows you to pass command line arguments to
1295 a Mono process through the environment. This is useful for example
1296 to force all of your Mono processes to use LLVM or SGEN without having
1297 to modify any launch scripts.
1299 \fBMONO_EVENTLOG_TYPE\fR
1300 Sets the type of event log provider to use (for System.Diagnostics.EventLog).
1302 Possible values are:
1307 Persists event logs and entries to the local file system.
1309 The directory in which to persist the event logs, event sources and entries
1310 can be specified as part of the value.
1312 If the path is not explicitly set, it defaults to "/var/lib/mono/eventlog"
1313 on unix and "%APPDATA%\mono\eventlog" on Windows.
1318 Uses the native win32 API to write events and registers event logs and
1319 event sources in the registry. This is only available on Windows.
1321 On Unix, the directory permission for individual event log and event source
1322 directories is set to 777 (with +t bit) allowing everyone to read and write
1323 event log entries while only allowing entries to be deleted by the user(s)
1328 Silently discards any events.
1331 The default is "null" on Unix (and versions of Windows before NT), and
1332 "win32" on Windows NT (and higher).
1335 \fBMONO_EXTERNAL_ENCODINGS\fR
1336 If set, contains a colon-separated list of text encodings to try when
1337 turning externally-generated text (e.g. command-line arguments or
1338 filenames) into Unicode. The encoding names come from the list
1339 provided by iconv, and the special case "default_locale" which refers
1340 to the current locale's default encoding.
1342 When reading externally-generated text strings UTF-8 is tried first,
1343 and then this list is tried in order with the first successful
1344 conversion ending the search. When writing external text (e.g. new
1345 filenames or arguments to new processes) the first item in this list
1346 is used, or UTF-8 if the environment variable is not set.
1348 The problem with using MONO_EXTERNAL_ENCODINGS to process your
1349 files is that it results in a problem: although its possible to get
1350 the right file name it is not necessarily possible to open the file.
1351 In general if you have problems with encodings in your filenames you
1352 should use the "convmv" program.
1354 \fBMONO_GC_PARAMS\fR
1355 When using Mono with the SGen garbage collector this variable controls
1356 several parameters of the collector. The variable's value is a comma
1357 separated list of words.
1361 \fBnursery-size=\fIsize\fR
1362 Sets the size of the nursery. The size is specified in bytes and must
1363 be a power of two. The suffixes `k', `m' and `g' can be used to
1364 specify kilo-, mega- and gigabytes, respectively. The nursery is the
1365 first generation (of two). A larger nursery will usually speed up the
1366 program but will obviously use more memory. The default nursery size
1369 \fBmajor=\fIcollector\fR
1370 Specifies which major collector to use. Options are `marksweep' for
1371 the Mark&Sweep collector, `marksweep-par' for parallel Mark&Sweep,
1372 `marksweep-fixed' for Mark&Sweep with a fixed heap,
1373 `marksweep-fixed-par' for parallel Mark&Sweep with a fixed heap and
1374 `copying' for the copying collector. The Mark&Sweep collector is the
1377 \fBmajor-heap-size=\fIsize\fR
1378 Sets the size of the major heap (not including the large object space)
1379 for the fixed-heap Mark&Sweep collector (i.e. `marksweep-fixed' and
1380 `marksweep-fixed-par'). The size is in bytes, with optional suffixes
1381 `k', `m' and `g' to specify kilo-, mega- and gigabytes, respectively.
1382 The default is 512 megabytes.
1384 \fBwbarrier=\fIwbarrier\fR
1385 Specifies which write barrier to use. Options are `cardtable' and
1386 `remset'. The card table barrier is faster but less precise, and only
1387 supported for the Mark&Sweep major collector on 32 bit platforms. The
1388 default is `cardtable' if it is supported, otherwise `remset'. The cardtable
1389 write barrier is faster and has a more stable and usually smaller
1390 memory footprint. If the program causes too much pinning during
1391 thread scan, it might be faster to enable remset.
1396 When using Mono with the SGen garbage collector this environment
1397 variable can be used to turn on various debugging features of the
1398 collector. The value of this variable is a comma separated list of
1404 Sets the debug level to the specified number.
1406 \fBcollect-before-allocs\fR
1408 \fBcheck-at-minor-collections\fR
1409 This performs a consistency check on minor collections and also clears
1410 the nursery at collection time, instead of the default, when buffers
1411 are allocated (clear-at-gc). The consistency check ensures that
1412 there are no major to minor references that are not on the remembered
1415 \fBxdomain-checks\fR
1416 Performs a check to make sure that no references are left to an
1420 This clears the nursery at GC time instead of doing it when the thread
1421 local allocation buffer (TLAB) is created. The default is to clear
1422 the nursery at TLAB creation time.
1424 \fBconservative-stack-mark\fR
1425 Forces the GC to scan the stack conservatively, even if precise
1426 scanning is available.
1428 \fBcheck-scan-starts\fR
1429 If set, does a plausibility check on the scan_starts before and after each collection
1431 \fBheap-dump=\fIfile\fR
1432 Dumps the heap contents to the specified file. To visualize the
1433 information, use the mono-heapviz tool.
1435 \fBbinary-protocol=\fIfile\fR
1436 Outputs the debugging output to the specified file. For this to
1437 work, Mono needs to be compiled with the BINARY_PROTOCOL define on
1438 sgen-gc.c. You can then use this command to explore the output
1440 sgen-grep-binprot 0x1234 0x5678 < file
1445 \fBMONO_GAC_PREFIX\fR
1446 Provides a prefix the runtime uses to look for Global Assembly Caches.
1447 Directories are separated by the platform path separator (colons on
1448 unix). MONO_GAC_PREFIX should point to the top directory of a prefixed
1449 install. Or to the directory provided in the gacutil /gacdir command. Example:
1450 .B /home/username/.mono:/usr/local/mono/
1453 Enables some filename rewriting support to assist badly-written
1454 applications that hard-code Windows paths. Set to a colon-separated
1455 list of "drive" to strip drive letters, or "case" to do
1456 case-insensitive file matching in every directory in a path. "all"
1457 enables all rewriting methods. (Backslashes are always mapped to
1458 slashes if this variable is set to a valid option).
1461 For example, this would work from the shell:
1464 MONO_IOMAP=drive:case
1468 If you are using mod_mono to host your web applications, you can use
1471 directive instead, like this:
1474 MonoIOMAP <appalias> all
1477 See mod_mono(8) for more details.
1479 Additionally. Mono includes a profiler module which allows one to track what
1480 adjustements to file paths IOMAP code needs to do. The tracking code reports
1481 the managed location (full stack trace) from which the IOMAP-ed call was made and,
1482 on process exit, the locations where all the IOMAP-ed strings were created in
1483 managed code. The latter report is only approximate as it is not always possible
1484 to estimate the actual location where the string was created. The code uses simple
1485 heuristics - it analyzes stack trace leading back to the string allocation location
1486 and ignores all the managed code which lives in assemblies installed in GAC as well as in the
1487 class libraries shipped with Mono (since they are assumed to be free of case-sensitivity
1488 issues). It then reports the first location in the user's code - in most cases this will be
1489 the place where the string is allocated or very close to the location. The reporting code
1490 is implemented as a custom profiler module (see the "PROFILING" section) and can be loaded
1491 in the following way:
1496 mono --profile=iomap yourapplication.exe
1499 Note, however, that Mono currently supports only one profiler module
1503 When Mono is using the LLVM code generation backend you can use this
1504 environment variable to pass code generation options to the LLVM
1507 \fBMONO_MANAGED_WATCHER\fR
1508 If set to "disabled", System.IO.FileSystemWatcher will use a file watcher
1509 implementation which silently ignores all the watching requests.
1510 If set to any other value, System.IO.FileSystemWatcher will use the default
1511 managed implementation (slow). If unset, mono will try to use inotify, FAM,
1512 Gamin, kevent under Unix systems and native API calls on Windows, falling
1513 back to the managed implementation on error.
1515 \fBMONO_MESSAGING_PROVIDER\fR
1516 Mono supports a plugin model for its implementation of System.Messaging making
1517 it possible to support a variety of messaging implementations (e.g. AMQP, ActiveMQ).
1518 To specify which messaging implementation is to be used the evironement variable
1519 needs to be set to the full class name for the provider. E.g. to use the RabbitMQ based
1520 AMQP implementation the variable should be set to:
1523 Mono.Messaging.RabbitMQ.RabbitMQMessagingProvider,Mono.Messaging.RabbitMQ
1526 If set causes the mono process to be bound to a single processor. This may be
1527 useful when debugging or working around race conditions.
1530 Disable inlining of thread local accesses. Try setting this if you get a segfault
1531 early on in the execution of mono.
1534 Provides a search path to the runtime where to look for library
1535 files. This is a tool convenient for debugging applications, but
1536 should not be used by deployed applications as it breaks the assembly
1537 loader in subtle ways.
1539 Directories are separated by the platform path separator (colons on unix). Example:
1540 .B /home/username/lib:/usr/local/mono/lib
1542 Alternative solutions to MONO_PATH include: installing libraries into
1543 the Global Assembly Cache (see gacutil(1)) or having the dependent
1544 libraries side-by-side with the main executable.
1546 For a complete description of recommended practices for application
1548 http://www.mono-project.com/Guidelines:Application_Deployment
1551 Experimental RTC support in the statistical profiler: if the user has
1552 the permission, more accurate statistics are gathered. The MONO_RTC
1553 value must be restricted to what the Linux rtc allows: power of two
1554 from 64 to 8192 Hz. To enable higher frequencies like 4096 Hz, run as root:
1557 echo 4096 > /proc/sys/dev/rtc/max-user-freq
1564 MONO_RTC=4096 mono --profiler=default:stat program.exe
1568 \fBMONO_SHARED_DIR\fR
1569 If set its the directory where the ".wapi" handle state is stored.
1570 This is the directory where the Windows I/O Emulation layer stores its
1571 shared state data (files, events, mutexes, pipes). By default Mono
1572 will store the ".wapi" directory in the users's home directory.
1574 \fBMONO_SHARED_HOSTNAME\fR
1575 Uses the string value of this variable as a replacement for the host name when
1576 creating file names in the ".wapi" directory. This helps if the host name of
1577 your machine is likely to be changed when a mono application is running or if
1578 you have a .wapi directory shared among several different computers.
1580 Mono typically uses the hostname to create the files that are used to
1581 share state across multiple Mono processes. This is done to support
1582 home directories that might be shared over the network.
1584 \fBMONO_STRICT_IO_EMULATION\fR
1585 If set, extra checks are made during IO operations. Currently, this
1586 includes only advisory locks around file writes.
1589 The name of the theme to be used by Windows.Forms. Available themes today
1590 include "clearlooks", "nice" and "win32".
1592 The default is "win32".
1594 \fBMONO_TLS_SESSION_CACHE_TIMEOUT\fR
1595 The time, in seconds, that the SSL/TLS session cache will keep it's entry to
1596 avoid a new negotiation between the client and a server. Negotiation are very
1597 CPU intensive so an application-specific custom value may prove useful for
1598 small embedded systems.
1600 The default is 180 seconds.
1602 \fBMONO_THREADS_PER_CPU\fR
1603 The maximum number of threads in the general threadpool will be
1604 20 + (MONO_THREADS_PER_CPU * number of CPUs). The default value for this
1607 \fBMONO_XMLSERIALIZER_THS\fR
1608 Controls the threshold for the XmlSerializer to produce a custom
1609 serializer for a given class instead of using the Reflection-based
1610 interpreter. The possible values are `no' to disable the use of a
1611 custom serializer or a number to indicate when the XmlSerializer
1612 should start serializing. The default value is 50, which means that
1613 the a custom serializer will be produced on the 50th use.
1615 \fBMONO_X509_REVOCATION_MODE\fR
1616 Sets the revocation mode used when validating a X509 certificate chain (https,
1617 ftps, smtps...). The default is 'nocheck', which performs no revocation check
1618 at all. The other possible values are 'offline', which performs CRL check (not
1619 implemented yet) and 'online' which uses OCSP and CRL to verify the revocation
1620 status (not implemented yet).
1621 .SH ENVIRONMENT VARIABLES FOR DEBUGGING
1623 \fBMONO_ASPNET_NODELETE\fR
1624 If set to any value, temporary source files generated by ASP.NET support
1625 classes will not be removed. They will be kept in the user's temporary
1629 If set, enables some features of the runtime useful for debugging.
1630 This variable should contain a comma separated list of debugging options.
1631 Currently, the following options are supported:
1635 \fBbreak-on-unverified\fR
1636 If this variable is set, when the Mono VM runs into a verification
1637 problem, instead of throwing an exception it will break into the
1638 debugger. This is useful when debugging verifier problems
1641 This option can be used to get more detailed information from
1642 InvalidCast exceptions, it will provide information about the types
1645 \fBcollect-pagefault-stats\fR
1646 Collects information about pagefaults. This is used internally to
1647 track the number of page faults produced to load metadata. To display
1648 this information you must use this option with "--stats" command line
1651 \fBdont-free-domains\fR
1652 This is an Optimization for multi-AppDomain applications (most
1653 commonly ASP.NET applications). Due to internal limitations Mono,
1654 Mono by default does not use typed allocations on multi-appDomain
1655 applications as they could leak memory when a domain is unloaded.
1657 Although this is a fine default, for applications that use more than
1658 on AppDomain heavily (for example, ASP.NET applications) it is worth
1659 trading off the small leaks for the increased performance
1660 (additionally, since ASP.NET applications are not likely going to
1661 unload the application domains on production systems, it is worth
1662 using this feature).
1665 Captures the interrupt signal (Control-C) and displays a stack trace
1666 when pressed. Useful to find out where the program is executing at a
1667 given point. This only displays the stack trace of a single thread.
1669 \fBkeep-delegates\fR
1670 This option will leak delegate trampolines that are no longer
1671 referenced as to present the user with more information about a
1672 delegate misuse. Basically a delegate instance might be created,
1673 passed to unmanaged code, and no references kept in managed code,
1674 which will garbage collect the code. With this option it is possible
1675 to track down the source of the problems.
1677 \fBreverse-pinvoke-exceptions
1678 This option will cause mono to abort with a descriptive message when
1679 during stack unwinding after an exception it reaches a native stack
1680 frame. This happens when a managed delegate is passed to native code,
1681 and the managed delegate throws an exception. Mono will normally try
1682 to unwind the stack to the first (managed) exception handler, and it
1683 will skip any native stack frames in the process. This leads to
1684 undefined behaviour (since mono doesn't know how to process native
1685 frames), leaks, and possibly crashes too.
1687 \fBno-gdb-backtrace\fR
1688 This option will disable the GDB backtrace emitted by the runtime
1689 after a SIGSEGV or SIGABRT in unmanaged code.
1691 \fBsuspend-on-sigsegv\fR
1693 This option will suspend the program when a native SIGSEGV is received.
1694 This is useful for debugging crashes which do not happen under gdb,
1695 since a live process contains more information than a core file.
1699 \fBMONO_LOG_LEVEL\fR
1700 The logging level, possible values are `error', `critical', `warning',
1701 `message', `info' and `debug'. See the DEBUGGING section for more
1705 Controls the domain of the Mono runtime that logging will apply to.
1706 If set, the log mask is changed to the set value. Possible values are
1707 "asm" (assembly loader), "type", "dll" (native library loader), "gc"
1708 (garbage collector), "cfg" (config file loader), "aot" (precompiler),
1709 "security" (e.g. Moonlight CoreCLR support) and "all".
1710 The default value is "all". Changing the mask value allows you to display only
1711 messages for a certain component. You can use multiple masks by comma
1712 separating them. For example to see config file messages and assembly loader
1713 messages set you mask to "asm,cfg".
1716 Used for runtime tracing of method calls. The format of the comma separated
1725 disabled Trace output off upon start.
1728 You can toggle trace output on/off sending a SIGUSR2 signal to the program.
1730 \fBMONO_TRACE_LISTENER\fR
1731 If set, enables the System.Diagnostics.DefaultTraceListener, which will
1732 print the output of the System.Diagnostics Trace and Debug classes.
1733 It can be set to a filename, and to Console.Out or Console.Error to display
1734 output to standard output or standard error, respectively. If it's set to
1735 Console.Out or Console.Error you can append an optional prefix that will
1736 be used when writing messages like this: Console.Error:MyProgramName.
1737 See the System.Diagnostics.DefaultTraceListener documentation for more
1740 \fBMONO_XEXCEPTIONS\fR
1741 This throws an exception when a X11 error is encountered; by default a
1742 message is displayed but execution continues
1744 \fBMONO_XMLSERIALIZER_DEBUG\fR
1745 Set this value to 1 to prevent the serializer from removing the
1746 temporary files that are created for fast serialization; This might
1747 be useful when debugging.
1750 This is used in the System.Windows.Forms implementation when running
1751 with the X11 backend. This is used to debug problems in Windows.Forms
1752 as it forces all of the commands send to X11 server to be done
1753 synchronously. The default mode of operation is asynchronous which
1754 makes it hard to isolate the root of certain problems.
1756 \fBMONO_GENERIC_SHARING\fR
1757 This environment variable controls the kind of generic sharing used.
1758 This variable is used by internal JIT developers and should not be
1759 changed in production. Do not use it.
1761 The variable controls which classes will have generic code sharing
1764 Permissible values are:
1768 All generated code can be shared.
1771 Only the classes in System.Collections.Generic will have its code
1772 shared (this is the default value).
1775 Only code in corlib will have its code shared.
1778 No generic code sharing will be performed.
1781 Generic code sharing by default only applies to collections. The
1782 Mono JIT by default turns this on.
1785 When the the MONO_XDEBUG env var is set, debugging info for JITted
1786 code is emitted into a shared library, loadable into gdb. This enables,
1787 for example, to see managed frame names on gdb backtraces.
1789 \fBMONO_VERBOSE_METHOD\fR
1790 Enables the maximum JIT verbosity for the specified method. This is
1791 very helpfull to diagnose a miscompilation problems of a specific
1794 If you want to use Valgrind, you will find the file `mono.supp'
1795 useful, it contains the suppressions for the GC which trigger
1796 incorrect warnings. Use it like this:
1798 valgrind --suppressions=mono.supp mono ...
1801 On some platforms, Mono can expose a set of DTrace probes (also known
1802 as user-land statically defined, USDT Probes).
1804 They are defined in the file `mono.d'.
1806 .B ves-init-begin, ves-init-end
1808 Begin and end of runtime initialization.
1810 .B method-compile-begin, method-compile-end
1812 Begin and end of method compilation.
1813 The probe arguments are class name, method name and signature,
1814 and in case of method-compile-end success or failure of compilation.
1818 Begin and end of Garbage Collection.
1820 To verify the availability of the probes, run:
1822 dtrace -P mono'$target' -l -c mono
1825 Mono's Ping implementation for detecting network reachability can
1826 create the ICMP packets itself without requiring the system ping
1827 command to do the work. If you want to enable this on Linux for
1828 non-root users, you need to give the Mono binary special permissions.
1830 As root, run this command:
1832 # setcap cap_net_raw=+ep /usr/bin/mono
1835 On Unix assemblies are loaded from the installation lib directory. If you set
1836 `prefix' to /usr, the assemblies will be located in /usr/lib. On
1837 Windows, the assemblies are loaded from the directory where mono and
1840 .B ~/.mono/aot-cache
1842 The directory for the ahead-of-time compiler demand creation
1843 assemblies are located.
1845 .B /etc/mono/config, ~/.mono/config
1847 Mono runtime configuration file. See the mono-config(5) manual page
1848 for more information.
1850 .B ~/.config/.mono/certs, /usr/share/.mono/certs
1852 Contains Mono certificate stores for users / machine. See the certmgr(1)
1853 manual page for more information on managing certificate stores and
1854 the mozroots(1) page for information on how to import the Mozilla root
1855 certificates into the Mono certificate store.
1857 .B ~/.mono/assemblies/ASSEMBLY/ASSEMBLY.config
1859 Files in this directory allow a user to customize the configuration
1860 for a given system assembly, the format is the one described in the
1861 mono-config(5) page.
1863 .B ~/.config/.mono/keypairs, /usr/share/.mono/keypairs
1865 Contains Mono cryptographic keypairs for users / machine. They can be
1866 accessed by using a CspParameters object with DSACryptoServiceProvider
1867 and RSACryptoServiceProvider classes.
1869 .B ~/.config/.isolatedstorage, ~/.local/share/.isolatedstorage, /usr/share/.isolatedstorage
1871 Contains Mono isolated storage for non-roaming users, roaming users and
1872 local machine. Isolated storage can be accessed using the classes from
1873 the System.IO.IsolatedStorage namespace.
1875 .B <assembly>.config
1877 Configuration information for individual assemblies is loaded by the
1878 runtime from side-by-side files with the .config files, see the
1879 http://www.mono-project.com/Config for more information.
1881 .B Web.config, web.config
1883 ASP.NET applications are configured through these files, the
1884 configuration is done on a per-directory basis. For more information
1885 on this subject see the http://www.mono-project.com/Config_system.web
1888 Mailing lists are listed at the
1889 http://www.mono-project.com/Mailing_Lists
1891 http://www.mono-project.com
1894 certmgr(1), csharp(1), mcs(1), mdb(1), monocov(1), monodis(1),
1895 mono-config(5), mozroots(1), pdb2mdb(1), xsp(1), mod_mono(8).
1897 For more information on AOT:
1898 http://www.mono-project.com/AOT
1900 For ASP.NET-related documentation, see the xsp(1) manual page