2010-04-08 Zoltan Varga <vargaz@gmail.com>
[mono/afaerber.git] / man / mono.1
blob45cc52c7743bd268e168162b2cce115a21b3dd5b
1 .\" 
2 .\" mono manual page.
3 .\" Copyright 2003 Ximian, Inc. 
4 .\" Copyright 2004-2009 Novell, Inc. 
5 .\" Author:
6 .\"   Miguel de Icaza (miguel@gnu.org)
7 .\"
8 .TH Mono "Mono 2.5"
9 .SH NAME
10 mono \- Mono's ECMA-CLI native code generator (Just-in-Time and Ahead-of-Time)
11 .SH SYNOPSIS
12 .PP
13 .B mono [options] file [arguments...]
14 .SH DESCRIPTION
15 \fImono\fP is a runtime implementation of the ECMA Common Language
16 Infrastructure.  This can be used to run ECMA and .NET applications.
17 .PP
18 The runtime contains a native code generator that transforms the
19 Common Intermediate Language into native code.
20 .PP
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.
25 .PP
26 The runtime loads the specified
27 .I file
28 and optionally passes
29 the
30 .I arguments
31 to it.  The 
32 .I file
33 is an ECMA assembly.  They typically have a .exe or .dll extension.
34 .PP
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.
38 .SH PORTABILITY
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.
43 .PP
44 This functionality is enabled by setting the 
45 .B MONO_IOMAP 
46 environment variable to one of 
47 .B all, drive
48 and 
49 .B case.
50 .PP
51 See the description for 
52 .B MONO_IOMAP
53 in the environment variables section for more details.
54 .SH RUNTIME OPTIONS
55 The following options are available:
56 .TP
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.  
62 .Sp 
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
67 time consuming.
68 .Sp
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
74 -O=shared flag.
75 .Sp
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.
81 .Sp
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.
86 .Sp
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.    
91 .Sp
92 A few options are available as a parameter to the 
93 .B --aot 
94 command line option.   The options are separated by commas, and more
95 than one can be specified:
96 .RS
97 .ne 8
98 .TP
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.
104 .I full
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.   
109 .I outfile=[filename]
110 Instructs the AOT compiler to save the output to the specified file.
112 .I write-symbols
113 Instructs the AOT compiler to emit debug symbol information.
115 .I save-temps,keep-temps
116 Instructs the AOT compiler to keep temporary files.
118 .I threads=[number]
119 This is an experimental option for the AOT compiler to use multiple threads
120 when compiling the methods.
122 .I nodebug
123 Instructs the AOT compiler to not output any debugging information.
125 .I ntrampolines=[number]
126 When compiling in full aot mode, the method trampolines must be precreated
127 in the AOT image.  You can add additional method trampolines with this argument.
128 Defaults to 1024.
130 .I nrgctx-trampolines=[number]
131 When compiling in full aot mode, the generic sharing trampolines must be precreated
132 in the AOT image.  You can add additional method trampolines with this argument.
133 Defaults to 1024.
135 .I nimt-trampolines=[number]
136 When compiling in full aot mode, the IMT trampolines must be precreated
137 in the AOT image.  You can add additional method trampolines with this argument.
138 Defaults to 128.
140 .I print-skipped-methods
141 If the AOT compiler cannot compile a method for any reason, enabling this flag
142 will output the skipped methods to the console.
144 .I autoreg
145 The AOT compiler will emit a (ELF only) library initializer to automatically
146 register the aot compiled module with the runtime.  This is only useful in static
147 mode
149 .I asmonly
150 Instructs the AOT compiler to output assembly code instead of an object file.
152 .I soft-debug
153 This instructs the compiler to generate sequence point checks that
154 allow Mono's soft debugger to debug applications even on systems where
155 it is not possible to set breakpoints or to single step (certain
156 hardware configurations like the cell phones and video gaming
157 consoles). 
159 .I static
160 Create an ELF object file (.o) which can be statically linked into an executable
161 when embedding the mono runtime. When this option is used, the object file needs to
162 be registered with the embedded runtime using the mono_aot_register_module function
163 which takes as its argument the mono_aot_module_<ASSEMBLY NAME>_info global symbol 
164 from the object file:
167 extern void *mono_aot_module_hello_info;
169 mono_aot_register_module (mono_aot_module_hello_info);
174 For more information about AOT, see: http://www.mono-project.com/AOT
177 \fB--attach=[options]\fR
178 Currently the only option supported by this command line argument is
179 \fBdisable\fR which disables the attach functionality.
181 \fB--full-aot\fR
182 This is an experimental flag that instructs the Mono runtime to not
183 generate any code at runtime and depend exclusively on the code
184 generated from using mono --aot=full previously.   This is useful for
185 platforms that do not permit dynamic code generation.
187 Notice that this feature will abort execution at runtime if a codepath
188 in your program, or Mono's class libraries attempts to generate code
189 dynamically.  You should test your software upfront and make sure that
190 you do not use any dynamic features.
192 \fB--config filename\fR
193 Load the specified configuration file instead of the default one(s).
194 The default files are /etc/mono/config and ~/.mono/config or the file
195 specified in the MONO_CONFIG environment variable, if set.  See the
196 mono-config(5) man page for details on the format of this file.
198 \fB--debugger-agent=[options]\fR 
199 This instructs the Mono runtime to
200 start a debugging agent inside the Mono runtime and connect it to a
201 client user interface will control the Mono process.
202 This option is typically used by IDEs, like the MonoDevelop IDE.
205 configuration is specified using one of more of the following options:
207 .ne 8
209 .I transport=transport_name
211 This is used to specify the transport that the debugger will use to
212 communicate.   It must be specified and currently requires this to
213 be 'dt_socket'. 
215 .I address=host:port
217 Use this option to specify the IP address where your debugger client is
218 listening to.
220 .I loglevel=LEVEL
222 Specifies the diagnostics log level for 
224 .I logfile=filename
226 Used to specify the file where the log will be stored, it defaults to
227 standard output.
231 \fB--desktop\fR
232 Configures the virtual machine to be better suited for desktop
233 applications.  Currently this sets the GC system to avoid expanding
234 the heap as much as possible at the expense of slowing down garbage
235 collection a bit.
237 \fB--help\fR, \fB-h\fR
238 Displays usage instructions.
240 \fB--optimize=MODE\fR, \fB-O=MODE\fR
241 MODE is a comma separated list of optimizations.  They also allow
242 optimizations to be turned off by prefixing the optimization name with
243 a minus sign.
245 In general, Mono has been tuned to use the default set of flags,
246 before using these flags for a deployment setting, you might want to
247 actually measure the benefits of using them.    
249 The following optimizations are implemented:
251              all        Turn on all optimizations
252              peephole   Peephole postpass
253              branch     Branch optimizations
254              inline     Inline method calls
255              cfold      Constant folding
256              consprop   Constant propagation
257              copyprop   Copy propagation
258              deadce     Dead code elimination
259              linears    Linear scan global reg allocation
260              cmov       Conditional moves [arch-dependency]
261              shared     Emit per-domain code
262              sched      Instruction scheduling
263              intrins    Intrinsic method implementations
264              tailc      Tail recursion and tail calls
265              loop       Loop related optimizations
266              fcmov      Fast x86 FP compares [arch-dependency]
267              leaf       Leaf procedures optimizations
268              aot        Usage of Ahead Of Time compiled code
269              precomp    Precompile all methods before executing Main
270              abcrem     Array bound checks removal
271              ssapre     SSA based Partial Redundancy Elimination
272              sse2       SSE2 instructions on x86 [arch-dependency]
273              gshared    Enable generic code sharing.
276 For example, to enable all the optimization but dead code
277 elimination and inlining, you can use:
279         -O=all,-deadce,-inline
282 The flags that are flagged with [arch-dependency] indicate that the
283 given option if used in combination with Ahead of Time compilation
284 (--aot flag) would produce pre-compiled code that will depend on the
285 current CPU and might not be safely moved to another computer. 
287 \fB--runtime=VERSION\fR
288 Mono supports different runtime versions. The version used depends on the program
289 that is being run or on its configuration file (named program.exe.config). This option
290 can be used to override such autodetection, by forcing a different runtime version
291 to be used. Note that this should only be used to select a later compatible runtime
292 version than the one the program was compiled against. A typical usage is for
293 running a 1.1 program on a 2.0 version:
295          mono --runtime=v2.0.50727 program.exe
298 \fB--security\fR, \fB--security=mode\fR
299 Activate the security manager, a currently experimental feature in
300 Mono and it is OFF by default. The new code verifier can be enabled
301 with this option as well.
303 .ne 8
305 Using security without parameters is equivalent as calling it with the
306 "cas" parameter.  
308 The following modes are supported:
310 .I cas
311 This allows mono to support declarative security attributes,
312 e.g. execution of Code Access Security (CAS) or non-CAS demands.
313 .TP 
314 .I core-clr
315 Enables the core-clr security system, typically used for
316 Moonlight/Silverlight applications.  It provides a much simpler
317 security system than CAS, see http://www.mono-project.com/Moonlight
318 for more details and links to the descriptions of this new system. 
320 .I validil
321 Enables the new verifier and performs basic verification for code
322 validity.  In this mode, unsafe code and P/Invoke are allowed. This
323 mode provides a better safety guarantee but it is still possible
324 for managed code to crash Mono. 
326 .I verifiable
327 Enables the new verifier and performs full verification of the code
328 being executed.  It only allows verifiable code to be executed.
329 Unsafe code is not allowed but P/Invoke is.  This mode should
330 not allow managed code to crash mono.  The verification is not as
331 strict as ECMA 335 standard in order to stay compatible with the MS
332 runtime.
334 The security system acts on user code: code contained in mscorlib or
335 the global assembly cache is always trusted.
339 \fB--server\fR
340 Configures the virtual machine to be better suited for server
341 operations (currently, a no-op).
343 \fB--verify-all\fR 
344 Verifies mscorlib and assemblies in the global
345 assembly cache for valid IL, and all user code for IL
346 verifiability. 
348 This is different from \fB--security\fR's verifiable
349 or validil in that these options only check user code and skip
350 mscorlib and assemblies located on the global assembly cache.
352 \fB-V\fR, \fB--version\fR
353 Prints JIT version information (system configuration, release number
354 and branch names if available). 
357 .SH DEVELOPMENT OPTIONS
358 The following options are used to help when developing a JITed application.
360 \fB--debug\fR, \fB--debug=OPTIONS\fR
361 Turns on the debugging mode in the runtime.  If an assembly was
362 compiled with debugging information, it will produce line number
363 information for stack traces. 
365 .ne 8
367 The optional OPTIONS argument is a comma separated list of debugging
368 options.  These options are turned off by default since they generate
369 much larger and slower code at runtime.
371 The following options are supported:
373 .I casts
374 Produces a detailed error when throwing a InvalidCastException.   This
375 option needs to be enabled as this generates more verbose code at
376 execution time. 
378 .I mdb-optimizations
379 Disable some JIT optimizations which are usually only disabled when
380 running inside the debugger.  This can be helpful if you want to attach
381 to the running process with mdb.
383 .I gdb
384 Generate and register debugging information with gdb. This is only supported on some
385 platforms, and only when using gdb 7.0 or later.
389 \fB--profile[=profiler[:profiler_args]]\fR
390 Turns on profiling.  For more information about profiling applications
391 and code coverage see the sections "PROFILING" and "CODE COVERAGE"
392 below. 
394 \fB--trace[=expression]\fR
395 Shows method names as they are invoked.  By default all methods are
396 traced. 
398 The trace can be customized to include or exclude methods, classes or
399 assemblies.  A trace expression is a comma separated list of targets,
400 each target can be prefixed with a minus sign to turn off a particular
401 target.  The words `program', `all' and `disabled' have special
402 meaning.  `program' refers to the main program being executed, and
403 `all' means all the method calls.
405 The `disabled' option is used to start up with tracing disabled.  It
406 can be enabled at a later point in time in the program by sending the
407 SIGUSR2 signal to the runtime.
409 Assemblies are specified by their name, for example, to trace all
410 calls in the System assembly, use:
413         mono --trace=System app.exe
416 Classes are specified with the T: prefix.  For example, to trace all
417 calls to the System.String class, use:
420         mono --trace=T:System.String app.exe
423 And individual methods are referenced with the M: prefix, and the
424 standard method notation:
427         mono --trace=M:System.Console:WriteLine app.exe
430 Exceptions can also be traced, it will cause a stack trace to be
431 printed every time an exception of the specified type is thrown.
432 The exception type can be specified with or without the namespace,
433 and to trace all exceptions, specify 'all' as the type name.
436         mono --trace=E:System.Exception app.exe
439 As previously noted, various rules can be specified at once:
442         mono --trace=T:System.String,T:System.Random app.exe
445 You can exclude pieces, the next example traces calls to
446 System.String except for the System.String:Concat method.
449         mono --trace=T:System.String,-M:System.String:Concat
452 Finally, namespaces can be specified using the N: prefix:
455         mono --trace=N:System.Xml
459 \fB--no-x86-stack-align\fR
460 Don't align stack frames on the x86 architecture.  By default, Mono
461 aligns stack frames to 16 bytes on x86, so that local floating point
462 and SIMD variables can be properly aligned.  This option turns off the
463 alignment, which usually saves one intruction per call, but might
464 result in significantly lower floating point and SIMD performance.
466 \fB--jitmap\fR
467 Generate a JIT method map in a /tmp/perf-PID.map file. This file is then
468 used, for example, by the perf tool included in recent Linux kernels.
469 Each line in the file has:
472         HEXADDR HEXSIZE methodname
475 Currently this option is only supported on Linux.
476 .SH JIT MAINTAINER OPTIONS
477 The maintainer options are only used by those developing the runtime
478 itself, and not typically of interest to runtime users or developers.
480 \fB--break method\fR
481 Inserts a breakpoint before the method whose name is `method'
482 (namespace.class:methodname).  Use `Main' as method name to insert a
483 breakpoint on the application's main method.
485 \fB--breakonex\fR
486 Inserts a breakpoint on exceptions.  This allows you to debug your
487 application with a native debugger when an exception is thrown.
489 \fB--compile name\fR
490 This compiles a method (namespace.name:methodname), this is used for
491 testing the compiler performance or to examine the output of the code
492 generator. 
494 \fB--compileall\fR
495 Compiles all the methods in an assembly.  This is used to test the
496 compiler performance or to examine the output of the code generator
497 .TP 
498 \fB--graph=TYPE METHOD\fR
499 This generates a postscript file with a graph with the details about
500 the specified method (namespace.name:methodname).  This requires `dot'
501 and ghostview to be installed (it expects Ghostview to be called
502 "gv"). 
504 The following graphs are available:
506           cfg        Control Flow Graph (CFG)
507           dtree      Dominator Tree
508           code       CFG showing code
509           ssa        CFG showing code after SSA translation
510           optcode    CFG showing code after IR optimizations
513 Some graphs will only be available if certain optimizations are turned
516 \fB--ncompile\fR
517 Instruct the runtime on the number of times that the method specified
518 by --compile (or all the methods if --compileall is used) to be
519 compiled.  This is used for testing the code generator performance. 
520 .TP 
521 \fB--stats\fR
522 Displays information about the work done by the runtime during the
523 execution of an application. 
525 \fB--wapi=hps|semdel\fR
526 Perform maintenance of the process shared data.
528 semdel will delete the global semaphore.
530 hps will list the currently used handles.
532 \fB-v\fR, \fB--verbose\fR
533 Increases the verbosity level, each time it is listed, increases the
534 verbosity level to include more information (including, for example, 
535 a disassembly of the native code produced, code selector info etc.).
536 .SH ATTACH SUPPORT
537 The Mono runtime allows external processes to attach to a running
538 process and load assemblies into the running program.   To attach to
539 the process, a special protocol is implemented in the Mono.Management
540 assembly. 
542 With this support it is possible to load assemblies that have an entry
543 point (they are created with -target:exe or -target:winexe) to be
544 loaded and executed in the Mono process.
546 The code is loaded into the root domain, and it starts execution on
547 the special runtime attach thread.    The attached program should
548 create its own threads and return after invocation.
550 This support allows for example debugging applications by having the
551 csharp shell attach to running processes.
552 .SH PROFILING
553 The mono runtime includes a profiler that can be used to explore
554 various performance related problems in your application.  The
555 profiler is activated by passing the --profile command line argument
556 to the Mono runtime, the format is:
559         --profile[=profiler[:profiler_args]]
562 Mono has a built-in profiler called 'default' (and is also the default
563 if no arguments are specified), but developers can write custom
564 profilers, see the section "CUSTOM PROFILERS" for more details.
566 If a 
567 .I profiler 
568 is not specified, the default profiler is used.
570 The 
571 .I profiler_args 
572 is a profiler-specific string of options for the profiler itself.
574 The default profiler accepts the following options 'alloc' to profile
575 memory consumption by the application; 'time' to profile the time
576 spent on each routine; 'jit' to collect time spent JIT-compiling methods
577 and 'stat' to perform sample statistical profiling.
578 If no options are provided the default is 'alloc,time,jit'. 
580 By default the
581 profile data is printed to stdout: to change this, use the 'file=filename'
582 option to output the data to filename.
584 For example:
587         mono --profile program.exe
591 That will run the program with the default profiler and will do time
592 and allocation profiling.
596         mono --profile=default:stat,alloc,file=prof.out program.exe
599 Will do  sample statistical profiling and allocation profiling on
600 program.exe. The profile data is put in prof.out.
602 Note that the statistical profiler has a very low overhead and should
603 be the preferred profiler to use (for better output use the full path
604 to the mono binary when running and make sure you have installed the
605 addr2line utility that comes from the binutils package).
606 .SH LOGGING PROFILER
609 .I logging profiler
610 is a general purpose profiler that can track many different kinds of
611 events and logs those into a file as the program executes.   This is
612 different than previous profilers in Mono that kept the information in
613 memory and rendered a summary of the results when the program shut
614 down.
616 Using the logging profiler means that useful information can be
617 gathered for long-running applications, applications that terminate
618 abormally (crashes, segfaults, complicated tear down processes) or
619 when no data about the shutdown is required.
621 The data collected by the running threads is kept independent of each
622 other to minimize the runtime overhead and the information dumped into
623 the log at regular intervals. 
625 A sample use is very simple:
627         $ mono --profile=logging program.exe
629         $ mprof-decoder program.mprof
632 In the above example the logging profiler is used in its default mode
633 that merely records GC statistics for the execution of program.exe.
634 The profiling data collected is stored in the file program.mprof.  The
635 mprof-decoder tool is then used to analyze the data.
637 You can instruct the logging profiler to record different one or more
638 sets of events.   These are the modes supported:
640 .I Statistical Profiling (stat)
641 the program instruction pointer is periodically sampled to determine
642 where the program is spending most of its time.   Statistical
643 profiling has a very low impact on a running application and it is
644 very useful to get a general picture of where time is being spent on a
645 program.   
646 .IP 
647 If call chains are requested, for each sample the profiler gets a
648 partial stack trace (limited by the specified depth) so that
649 caller-callee information is available.
651 .I Instrumenting:
652 each method enter and exit is logged with a timestamp; further processing of
653 the data can show the methods that took the longer to execute, with complete
654 accounting for callers and callees. However, this way of profiling is rather
655 intrusive and slows down the application significantly.
657 .I Allocation:
658 each allocation is logged.
660 .I Allocation summary:
661 shows, for each collection, a summary of the heap contents broken down by
662 class (for each class the number of allocated and released objects is
663 given, together with their aggregated size in bytes).
665 .I Heap snapshot mode:
666 dumps the whole heap contents at every collection (or at user specified
667 collections). It is also possible to request a collection and snapshot dump
668 with a signal.
670 Moreover, other events can be logged and analyzed, like jit time for each
671 method, load and unload for assemblies, modules and and individual classes,
672 and appdomain and thread creation and destruction.
674 This profiler is activated passing the \fB--profile=logging\fR option to
675 the mono runtime, and is controlled attaching further options, like
676 \fB--profile=logging:statistical\fR for doing statistical profiling (multiple
677 options are separated by commas).
679 As a quick primer, here are a few examples of the most common usage modes:
681 To perform statistical profiling:
684         mono --profile=logging:stat program.exe
687 To perform statistical profiling, inspecting call chains up to depth 8:
690         mono --profile=logging:stat=8 program.exe
693 To profile allocations (by default the call stack will be analized for
694 each allocation, producing detailed caller method attribution infornation):
697         mono --profile=logging:allocations program.exe
700 To profile garbage collection activity at a high level (collection time and objects freed
701 at each collection for each class are reported, but heap snapshots are not saved to disk):
704         mono --profile=logging:allocations-summary program.exe
707 To perform heap profiling taking heap snapshots:
710         mono --profile=logging:heap=all program.exe
713 To write the resulting data to a different file:
716         mono --profile=logging:output=mydata.mprof program.exe
719 Then you would need to invoke the decoder \fImprof-decoder(1)\fR
720 on the output file to see the profiling results, or to examine heap
721 snapshots and allocations in detail \fImprof-heap-viewer(1)\fR.
723 The operating modes described above are the default ones, and are sufficient
724 to use the profiler.
726 To further customize the profiler behavior there are more options, described
727 below.
729 These options can be individually enabled and disabled prefixing them
730 with an (optional) '+' character or a '-' character.  For instance,
731 the "allocations" option by default records also the full call stack
732 at each allocation.  If only the caller is wanted, one should use
733 "allocations,-save-allocation-stack", or to disable call tracking
734 completely (making the profiler less intrusive)
735 "allocations,-save-allocation-caller,-save-allocation-stack".  In
736 practice the "allocation" option by default behaves like
737 "allocations,save-allocation-caller,save-allocation-stack", but the
738 user can tune this to his needs.
740 These are all the available options, organized by category:
742 \fBExecution profiling modes\fR
744 .ne 8
746 \fIstatistical\fR, \fIstat\fR or \fIs\fR
747 Performs statistical profiling.   This is a lightweight profiling
748 mechanism and it has a much lower overhead than the \fIenter-leave\fR
749 profiling as it works by sampling where the program is spending its
750 time by using a timer.
751 If specified with \fIs=<number>\fR, also inspect call chains up to level
752 <number>.
754 \fIenter-leave\fR, \fIcalls\fR or \fIc\fR
755 Measure the time spent inside each method call, this is done by
756 logging the time when a method enters and when the method leaves.
757 This can be a time consuming operation. 
759 \fIjit\fR, \fIj\fR
760 Collect information about time spent by the JIT engine compiling
761 methods. 
765 \fBAllocation profiling modes\fR
767 .ne 8
769 \fIallocations\fR, \fIalloc\fR or \fIa\fR
770 Collect information about each allocation (object class and size).
771 By default this also implies "+save-allocation-caller" and
772 "+save-allocation-stack".
774 \fIsave-allocation-caller\fR, \fIsac\fR
775 Save the direct caller of each allocation. The profiler filters out wrapper
776 methods, and also recognizes if the allocation has been performed by the
777 runtime while jitting a method.
779 \fIsave-allocation-stack\fR, \fIsas\fR
780 Save the full managed execution stack at each allocation.
781 While the "sac" option saves the direct caller, this one records the whole
782 stack trace.
783 Note that in the call stack the wrapper methods are not filtered out.
784 Anyway the "sac" and "sas" options can be combined, and the decoder will
785 attribute the allocation to the correct method even if the wrapper is at the
786 top of the stack trace.
788 \fIallocations-summary\fR or \fIas\fR
789 At each collection dump a summary
790 of the heap contents (for each class, the number and collective size of all
791 live and freed heap objects). This very lightweight compared to full heap
792 snapshots.
794 \fIunreachable\fR, \fIfree\fR or \fIf\fR
795 Performs a lightweight profile of the garbage collector.  On each
796 collection performed by the GC, the list of unreachable objects is
797 recorded, and for each object the class and size is provided.  This
798 information can be used to compute the heap size broken down by class
799 (combined with "a" can give the same information of "as", but the log
800 file contains info about each individual object, while in "as" the
801 processing is done directly at runtime and the log file contains only
802 the summarized data broken down by class).
804 \fIgc\fR or \fIg\fR
805 Measure the time spent in each collection, and also trace heap resizes.
807 \fIheap-shot[=ARG]\fR, \fIheap[=ARG]\fR or \fIh[=ARH]\fR
808 Performs full heap profiling.   In this case on each
809 collection a full heap snapshot is recorded to disk.
810 Inside the snapshots, each object reference is still represented so
811 that it's possible to investigate who is responsible for keeping objects
812 alive.
814 If the value of ARG is 
815 .B all, 
816 a heap snapshot is taken at each collection.  
818 If the value is an integer
819 .B n,
820 a snapshot will be taken at the first
821 .B n
822 collections (like setting
823 .B gcd=n
826 If no additional argument is given to the heap option, the only way to take
827 heap snapshots is to requeste them using the runtime socket based command
828 interface described below (see "Profiler activity control").
830 Heap profiling also enables full allocation profiling (with call
831 stacks), and each allocation can be related to its corresponding
832 object in the snapshots, enabling investigations like "find all
833 objects of a given class allocated by a given method and still live at
834 a given collection, and then find all objects referencing them".
836 This kind of heap snapshot analysis is performed using the mprof-heap-viewer(1)
837 application.
839 The number of heap snapshots taken (and the moment in which they are taken)
840 can be further customized with the following options: 
842 \fIgc-dumps=N\fR, \fIgc-d=N\fR, \fIgcd=N\fR
843 states the number of snapshots that must be dumped (since the application
844 starts).  Zero means no dumps at all, -1 means dump at all collections.
846 These options exist because it can happen that the user wants to investigate
847 what happens during collections but without forcing a collection using the
848 command interface, because forcing a collection alters the program behavior.
849 Of course it is possible to simply take a snapshot at every collection, but
850 in some workloads this is could not be feasible (too much data).
851 So we have this "garbage collection dumps" counter to control how many
852 snapshots to take.
856 \fBProfiler activity control\fR
858 .ne 8
860 \fIoutput=FILE\fR, \fIout=FILE\fR or \fIo=FILE\fR
861 Use this option to provide the output file name for the profile log.
862 If this option is not specified, it will default to "<program-name>.mprof".
864 \fIoutput-suffix=SUFFIX\fR, \fIsuffix=SUFFIX\fR or \fIos=SUFFIX\fR: makes
865 the output file name equals to "<program-name>-SUFFIX.mprof".
867 \fIstart-enabled\fR or \fIse\fR: start with the profiler active
868 (which is the default).
870 \fIstart-disabled\fR or \fIsd\fR: start with the profiler inactive.
872 \fIforce-accurate-timer\fR (or \fIfac\fR): the profiler by default uses
873 rtdsc to acquire timestamps for frequent events, but this can be imprecise;
874 using this option you force the use of "gettimeofday" at every event, which
875 is more accurate but much slower.
877 \fIcommand-port=port\fR or \fIcp=port\fR (where port is an integer between
878 1024 nd 65535):
879 Choose a TCP port where the profiler will listen for user commands.
880 The protocol is ASCII based and line oriented (one line per command), and the
881 profiler answers with one line containing either "OK" or "ERROR" to each
882 received command.
884 The user can telnet to this port and give commands manually, or a GUI can
885 use this facility to control the profiler at runtime.
887 The available commands are:
889 \fIenable\fR: Enables the profiler.
891 \fIdisable\fR: Disables the profiler.
893 \fIheap-snapshot\fR: Takes a heap snapshot now (forces a full garbage collection).
895 \fIheap-snapshot-counter=arg\fR: Set the counter of the next heap snapshots
896 that must be taken, where arg can be "all" (take a snapshot at every
897 collection), "none" (do not take snapshots), or an integer "n" (take a heap
898 snapshot for the next "n" collections).
902 \fBInternal buffer sizes\fR
904 .ne 8
906 \fIper-thread-buffer-size=N\fR, \fItbs=N\fR
907 Use to specify the number of events that a thread buffer
908 can hold.   When the thread buffer is full, a log block is
909 written to disk.
911 This defaults to tbs=10000.
913 \fIstatistical-thread-buffer-size=N\fR, \fIsbs=N\fR
914 The number of statistical samples that
915 are held in memory before they are dumped to disk (the system does
916 double-buffering and the statistical samples are written by a helper
917 thread, so the statistical profiler never stops and is able to profile
918 the profiler itself).  
920 This defaults to sbs=10000.
922 \fIwrite-buffer-size\fR, \fIwbs\fR
923 Specifies the size in bytes of the internal write buffers.
925 This defaults to wbs=1024.
929 In its current state, this profiler can also perform heap analysis
930 like the HeapShot profiler, but there is no UI to process this
931 information. 
933 Another known issue is that if the timer is not strictly monotonic (like
934 rtdsc), differences between times can underflow (they are handled as
935 unsigned integers) and weird numbers can show up in the logs.
937 Finally, it can happen that when exceptions are thrown the profiler temporarily
938 loses track of the execution stack and misattributes the caller for a few
939 allocations (and method execution time).
941 The output file contains compressed events, to process the data you should
942 use tools like the "Mono.Profiler" tool provided on the Mono SVN
943 repository.  
945 More explanations are provided here: "http://www.mono-project.com/LoggingProfiler".
946 .SH EXTERNAL PROFILERS
947 There are a number of external profilers that have been developed for
948 Mono, we will update this section to contain the profilers.
950 The heap Shot profiler can track all live objects, and references to
951 these objects, and includes a GUI tool, this is our recommended
952 profiler.
953 To install you must download the profiler
954 from Mono's SVN:
956         svn co svn://anonsvn.mono-project.com/source/trunk/heap-shot
957         cd heap-shot
958         ./autogen
959         make
960         make install
963 See the included documentation for details on using it.
965 The Live Type profiler shows at every GC iteration all of the live
966 objects of a given type.   To install you must download the profiler
967 from Mono's SVN:
969         svn co svn://anonsvn.mono-project.com/source/trunk/heap-prof
970         cd heap-prof
971         ./autogen
972         make
973         make install
976 To use the profiler, execute:
978         mono --profile=desc-heap program.exe
981 The output of this profiler looks like this:
983         Checkpoint at 102 for heap-resize
984            System.MonoType : 708
985            System.Threading.Thread : 352
986            System.String : 3230
987            System.String[] : 104
988            Gnome.ModuleInfo : 112
989            System.Object[] : 160
990            System.Collections.Hashtable : 96
991            System.Int32[] : 212
992            System.Collections.Hashtable+Slot[] : 296
993            System.Globalization.CultureInfo : 108
994            System.Globalization.NumberFormatInfo : 144
997 The first line describes the iteration number for the GC, in this case
998 checkpoint 102.
1000 Then on each line the type is displayed as well as the number of bytes
1001 that are being consumed by live instances of this object.
1002 .PP 
1003 The AOT profiler is used to feed back information to the AOT compiler
1004 about how to order code based on the access patterns for pages.  To
1005 use it, use:
1007         mono --profile=aot program.exe
1009 The output of this profile can be fed back into Mono's AOT compiler to
1010 order the functions on the disk to produce precompiled images that
1011 have methods in sequential pages.
1012 .SH CUSTOM PROFILERS
1013 Mono provides a mechanism for loading other profiling modules which in
1014 the form of shared libraries.  These profiling modules can hook up to
1015 various parts of the Mono runtime to gather information about the code
1016 being executed.
1018 To use a third party profiler you must pass the name of the profiler
1019 to Mono, like this:
1022         mono --profile=custom program.exe
1026 In the above sample Mono will load the user defined profiler from the
1027 shared library `mono-profiler-custom.so'.  This profiler module must
1028 be on your dynamic linker library path.
1029 .PP 
1030 A list of other third party profilers is available from Mono's web
1031 site (www.mono-project.com/Performance_Tips)
1033 Custom profiles are written as shared libraries.  The shared library
1034 must be called `mono-profiler-NAME.so' where `NAME' is the name of
1035 your profiler.
1037 For a sample of how to write your own custom profiler look in the
1038 Mono source tree for in the samples/profiler.c.
1039 .SH CODE COVERAGE
1040 Mono ships with a code coverage module.  This module is activated by
1041 using the Mono --profile=cov option.  The format is:
1042 \fB--profile=cov[:assembly-name[/namespace]] test-suite.exe\fR
1044 By default code coverage will default to all the assemblies loaded,
1045 you can limit this by specifying the assembly name, for example to
1046 perform code coverage in the routines of your program use, for example
1047 the following command line limits the code coverage to routines in the
1048 "demo" assembly:
1051         mono --profile=cov:demo demo.exe
1055 Notice that the 
1056 .I assembly-name
1057 does not include the extension.
1059 You can further restrict the code coverage output by specifying a
1060 namespace:
1063         mono --profile=cov:demo/My.Utilities demo.exe
1067 Which will only perform code coverage in the given assembly and
1068 namespace.  
1070 Typical output looks like this:
1073         Not covered: Class:.ctor ()
1074         Not covered: Class:A ()
1075         Not covered: Driver:.ctor ()
1076         Not covered: Driver:method ()
1077         Partial coverage: Driver:Main ()
1078                 offset 0x000a
1082 The offsets displayed are IL offsets.
1084 A more powerful coverage tool is available in the module `monocov'.
1085 See the monocov(1) man page for details.
1086 .SH DEBUGGING AIDS
1087 To debug managed applications, you can use the 
1088 .B mdb
1089 command, a command line debugger.  
1091 It is possible to obtain a stack trace of all the active threads in
1092 Mono by sending the QUIT signal to Mono, you can do this from the
1093 command line, like this:
1096         kill -QUIT pid
1099 Where pid is the Process ID of the Mono process you want to examine.
1100 The process will continue running afterwards, but its state is not
1101 guaranteed.
1103 .B Important:
1104 this is a last-resort mechanism for debugging applications and should
1105 not be used to monitor or probe a production application.  The
1106 integrity of the runtime after sending this signal is not guaranteed
1107 and the application might crash or terminate at any given point
1108 afterwards.   
1110 The \fB--debug=casts\fR option can be used to get more detailed
1111 information for Invalid Cast operations, it will provide information
1112 about the types involved.   
1114 You can use the MONO_LOG_LEVEL and MONO_LOG_MASK environment variables
1115 to get verbose debugging output about the execution of your
1116 application within Mono.
1118 The 
1119 .I MONO_LOG_LEVEL
1120 environment variable if set, the logging level is changed to the set
1121 value. Possible values are "error", "critical", "warning", "message",
1122 "info", "debug". The default value is "error". Messages with a logging
1123 level greater then or equal to the log level will be printed to
1124 stdout/stderr.
1126 Use "info" to track the dynamic loading of assemblies.
1129 Use the 
1130 .I MONO_LOG_MASK
1131 environment variable to limit the extent of the messages you get: 
1132 If set, the log mask is changed to the set value. Possible values are
1133 "asm" (assembly loader), "type", "dll" (native library loader), "gc"
1134 (garbage collector), "cfg" (config file loader), "aot" (precompiler),
1135 "security" (e.g. Moonlight CoreCLR support) and "all". 
1136 The default value is "all". Changing the mask value allows you to display only 
1137 messages for a certain component. You can use multiple masks by comma 
1138 separating them. For example to see config file messages and assembly loader
1139 messages set you mask to "asm,cfg".
1141 The following is a common use to track down problems with P/Invoke:
1144         $ MONO_LOG_LEVEL="debug" MONO_LOG_MASK="dll" mono glue.exe
1148 .SH SERIALIZATION
1149 Mono's XML serialization engine by default will use a reflection-based
1150 approach to serialize which might be slow for continuous processing
1151 (web service applications).  The serialization engine will determine
1152 when a class must use a hand-tuned serializer based on a few
1153 parameters and if needed it will produce a customized C# serializer
1154 for your types at runtime.  This customized serializer then gets
1155 dynamically loaded into your application.
1157 You can control this with the MONO_XMLSERIALIZER_THS environment
1158 variable.
1160 The possible values are 
1161 .B `no' 
1162 to disable the use of a C# customized
1163 serializer, or an integer that is the minimum number of uses before
1164 the runtime will produce a custom serializer (0 will produce a
1165 custom serializer on the first access, 50 will produce a serializer on
1166 the 50th use). Mono will fallback to an interpreted serializer if the
1167 serializer generation somehow fails. This behavior can be disabled
1168 by setting the option
1169 .B `nofallback'
1170 (for example: MONO_XMLSERIALIZER_THS=0,nofallback).
1171 .SH ENVIRONMENT VARIABLES
1173 \fBGC_DONT_GC\fR
1174 Turns off the garbage collection in Mono.  This should be only used
1175 for debugging purposes
1177 \fBLVM_COUNT\fR
1178 When Mono is compiled with LLVM support, this instructs the runtime to
1179 stop using LLVM after the specified number of methods are JITed.
1180 This is a tool used in diagnostics to help isolate problems in the
1181 code generation backend.   For example \fBLLVM_COUNT=10\fR would only
1182 compile 10 methods with LLVM and then switch to the Mono JIT engine.
1183 \fBLLVM_COUNT=0\fR would disable the LLVM engine altogether.
1185 \fBMONO_AOT_CACHE\fR
1186 If set, this variable will instruct Mono to ahead-of-time compile new
1187 assemblies on demand and store the result into a cache in
1188 ~/.mono/aot-cache. 
1190 \fBMONO_CFG_DIR\fR
1191 If set, this variable overrides the default system configuration directory
1192 ($PREFIX/etc). It's used to locate machine.config file.
1194 \fBMONO_COM\fR
1195 Sets the style of COM interop.  If the value of this variable is "MS"
1196 Mono will use string marhsalling routines from the liboleaut32 for the
1197 BSTR type library, any other values will use the mono-builtin BSTR
1198 string marshalling.
1200 \fBMONO_CONFIG\fR
1201 If set, this variable overrides the default runtime configuration file
1202 ($PREFIX/etc/mono/config). The --config command line options overrides the
1203 environment variable.
1205 \fBMONO_DEBUG\fR
1206 If set, enables some features of the runtime useful for debugging.
1207 This variable should contain a comma separated list of debugging options.
1208 Currently, the following options are supported:
1210 .ne 8
1212 \fBbreak-on-unverified\fR
1213 If this variable is set, when the Mono VM runs into a verification
1214 problem, instead of throwing an exception it will break into the
1215 debugger.  This is useful when debugging verifier problems
1217 \fBcollect-pagefault-stats\fR
1218 Collects information about pagefaults.   This is used internally to
1219 track the number of page faults produced to load metadata.  To display
1220 this information you must use this option with "--stats" command line
1221 option.
1223 \fBdont-free-domains\fR
1224 This is an Optimization for multi-AppDomain applications (most
1225 commonly ASP.NET applications).  Due to internal limitations Mono,
1226 Mono by default does not use typed allocations on multi-appDomain
1227 applications as they could leak memory when a domain is unloaded. 
1229 Although this is a fine default, for applications that use more than
1230 on AppDomain heavily (for example, ASP.NET applications) it is worth
1231 trading off the small leaks for the increased performance
1232 (additionally, since ASP.NET applications are not likely going to
1233 unload the application domains on production systems, it is worth
1234 using this feature). 
1236 \fBhandle-sigint\fR
1237 Captures the interrupt signal (Control-C) and displays a stack trace
1238 when pressed.  Useful to find out where the program is executing at a
1239 given point.  This only displays the stack trace of a single thread. 
1241 \fBkeep-delegates\fR
1242 This option will leak delegate trampolines that are no longer
1243 referenced as to present the user with more information about a
1244 delegate misuse.  Basically a delegate instance might be created,
1245 passed to unmanaged code, and no references kept in managed code,
1246 which will garbage collect the code.  With this option it is possible
1247 to track down the source of the problems. 
1249 \fBno-gdb-backtrace\fR
1250 This option will disable the GDB backtrace emitted by the runtime
1251 after a SIGSEGV or SIGABRT in unmanaged code.
1253 \fBsuspend-on-sigsegv\fR
1255 This option will suspend the program when a native SIGSEGV is received.
1256 This is useful for debugging crashes which do not happen under gdb,
1257 since a live process contains more information than a core file.
1261 \fBMONO_DISABLE_AIO\fR
1262 If set, tells mono NOT to attempt using native asynchronous I/O services. In
1263 that case, a default select/poll implementation is used. Currently only epoll()
1264 is supported.
1266 \fBMONO_DISABLE_MANAGED_COLLATION\fR
1267 If this environment variable is `yes', the runtime uses unmanaged
1268 collation (which actually means no culture-sensitive collation). It
1269 internally disables managed collation functionality invoked via the
1270 members of System.Globalization.CompareInfo class. Collation is
1271 enabled by default.
1273 \fBMONO_EGD_SOCKET\fR
1274 For platforms that do not otherwise have a way of obtaining random bytes
1275 this can be set to the name of a file system socket on which an egd or
1276 prngd daemon is listening.
1278 \fBMONO_EVENTLOG_TYPE\fR
1279 Sets the type of event log provider to use (for System.Diagnostics.EventLog).
1281 Possible values are:
1284 .I "local[:path]"
1286 Persists event logs and entries to the local file system.
1288 The directory in which to persist the event logs, event sources and entries
1289 can be specified as part of the value.
1291 If the path is not explicitly set, it defaults to "/var/lib/mono/eventlog"
1292 on unix and "%APPDATA%\mono\eventlog" on Windows.
1294 .I "win32"
1296 .B 
1297 Uses the native win32 API to write events and registers event logs and
1298 event sources in the registry.   This is only available on Windows. 
1300 On Unix, the directory permission for individual event log and event source
1301 directories is set to 777 (with +t bit) allowing everyone to read and write
1302 event log entries while only allowing entries to be deleted by the user(s)
1303 that created them.
1305 .I "null"
1307 Silently discards any events.
1310 The default is "null" on Unix (and versions of Windows before NT), and 
1311 "win32" on Windows NT (and higher).
1314 \fBMONO_EXTERNAL_ENCODINGS\fR
1315 If set, contains a colon-separated list of text encodings to try when
1316 turning externally-generated text (e.g. command-line arguments or
1317 filenames) into Unicode.  The encoding names come from the list
1318 provided by iconv, and the special case "default_locale" which refers
1319 to the current locale's default encoding.
1321 When reading externally-generated text strings UTF-8 is tried first,
1322 and then this list is tried in order with the first successful
1323 conversion ending the search.  When writing external text (e.g. new
1324 filenames or arguments to new processes) the first item in this list
1325 is used, or UTF-8 if the environment variable is not set.
1327 The problem with using MONO_EXTERNAL_ENCODINGS to process your
1328 files is that it results in a problem: although its possible to get
1329 the right file name it is not necessarily possible to open the file.
1330 In general if you have problems with encodings in your filenames you
1331 should use the "convmv" program.
1333 \fBMONO_GAC_PREFIX\fR
1334 Provides a prefix the runtime uses to look for Global Assembly Caches.
1335 Directories are separated by the platform path separator (colons on
1336 unix). MONO_GAC_PREFIX should point to the top directory of a prefixed
1337 install. Or to the directory provided in the gacutil /gacdir command. Example:
1338 .B /home/username/.mono:/usr/local/mono/
1340 \fBMONO_IOMAP\fR
1341 Enables some filename rewriting support to assist badly-written
1342 applications that hard-code Windows paths.  Set to a colon-separated
1343 list of "drive" to strip drive letters, or "case" to do
1344 case-insensitive file matching in every directory in a path.  "all"
1345 enables all rewriting methods.  (Backslashes are always mapped to
1346 slashes if this variable is set to a valid option).
1349 For example, this would work from the shell:
1352         MONO_IOMAP=drive:case
1353         export MONO_IOMAP
1356 If you are using mod_mono to host your web applications, you can use
1357 the 
1358 .B MonoIOMAP
1359 directive instead, like this:
1362         MonoIOMAP <appalias> all
1365 See mod_mono(8) for more details.
1367 Additionally. Mono includes a profiler module which allows one to track what
1368 adjustements to file paths IOMAP code needs to do. The tracking code reports
1369 the managed location (full stack trace) from which the IOMAP-ed call was made and,
1370 on process exit, the locations where all the IOMAP-ed strings were created in
1371 managed code. The latter report is only approximate as it is not always possible
1372 to estimate the actual location where the string was created. The code uses simple
1373 heuristics - it analyzes stack trace leading back to the string allocation location
1374 and ignores all the managed code which lives in assemblies installed in GAC as well as in the
1375 class libraries shipped with Mono (since they are assumed to be free of case-sensitivity
1376 issues). It then reports the first location in the user's code - in most cases this will be
1377 the place where the string is allocated or very close to the location. The reporting code
1378 is implemented as a custom profiler module (see the "PROFILING" section) and can be loaded
1379 in the following way:
1384         mono --profile=iomap yourapplication.exe
1387 Note, however, that Mono currently supports only one profiler module at a time.
1389 \fBMONO_MANAGED_WATCHER\fR
1390 If set to "disabled", System.IO.FileSystemWatcher will use a file watcher 
1391 implementation which silently ignores all the watching requests.
1392 If set to any other value, System.IO.FileSystemWatcher will use the default
1393 managed implementation (slow). If unset, mono will try to use inotify, FAM, 
1394 Gamin, kevent under Unix systems and native API calls on Windows, falling 
1395 back to the managed implementation on error.
1397 \fBMONO_NO_SMP\fR
1398 If set causes the mono process to be bound to a single processor. This may be
1399 useful when debugging or working around race conditions.
1401 \fBMONO_PATH\fR
1402 Provides a search path to the runtime where to look for library
1403 files.   This is a tool convenient for debugging applications, but
1404 should not be used by deployed applications as it breaks the assembly
1405 loader in subtle ways. 
1407 Directories are separated by the platform path separator (colons on unix). Example:
1408 .B /home/username/lib:/usr/local/mono/lib
1410 Alternative solutions to MONO_PATH include: installing libraries into
1411 the Global Assembly Cache (see gacutil(1)) or having the dependent
1412 libraries side-by-side with the main executable.
1414 For a complete description of recommended practices for application
1415 deployment, see
1416 http://www.mono-project.com/Guidelines:Application_Deployment
1418 \fBMONO_RTC\fR
1419 Experimental RTC support in the statistical profiler: if the user has
1420 the permission, more accurate statistics are gathered.  The MONO_RTC
1421 value must be restricted to what the Linux rtc allows: power of two
1422 from 64 to 8192 Hz. To enable higher frequencies like 4096 Hz, run as root:
1425         echo 4096 > /proc/sys/dev/rtc/max-user-freq
1429 For example:
1432         MONO_RTC=4096 mono --profiler=default:stat program.exe
1436 \fBMONO_NO_TLS\fR
1437 Disable inlining of thread local accesses. Try setting this if you get a segfault
1438 early on in the execution of mono.
1440 \fBMONO_CPU_ARCH\fR
1441 Override the automatic cpu detection mechanism. Currently used only on arm.
1442 The format of the value is as follows:
1445         "armvV [thumb]"
1448 where V is the architecture number 4, 5, 6, 7 and the options can be currently be
1449 "thunb". Example:
1452         MONO_CPU_ARCH="armv4 thumb" mono ...
1455 .TP 
1456 \fBMONO_SHARED_DIR\fR
1457 If set its the directory where the ".wapi" handle state is stored.
1458 This is the directory where the Windows I/O Emulation layer stores its
1459 shared state data (files, events, mutexes, pipes).  By default Mono
1460 will store the ".wapi" directory in the users's home directory.
1461 .TP 
1462 \fBMONO_SHARED_HOSTNAME\fR
1463 Uses the string value of this variable as a replacement for the host name when
1464 creating file names in the ".wapi" directory. This helps if the host name of
1465 your machine is likely to be changed when a mono application is running or if
1466 you have a .wapi directory shared among several different computers.
1468 Mono typically uses the hostname to create the files that are used to
1469 share state across multiple Mono processes.  This is done to support
1470 home directories that might be shared over the network.
1472 \fBMONO_STRICT_IO_EMULATION\fR
1473 If set, extra checks are made during IO operations.  Currently, this
1474 includes only advisory locks around file writes.
1476 \fBMONO_DISABLE_SHM\fR
1477 If set, disables the shared memory files used for cross-process
1478 handles: process have only private handles.  This means that process
1479 and thread handles are not available to other processes, and named
1480 mutexes, named events and named semaphores are not visible between
1481 processes.
1483 This is can also be enabled by default by passing the
1484 "--disable-shared-handles" option to configure.
1486 This is the default from mono 2.8 onwards.
1488 \fBMONO_ENABLE_SHM\fR
1489 Enable support for cross-process handles.
1491 \fBMONO_THEME\fR
1492 The name of the theme to be used by Windows.Forms.   Available themes today
1493 include "clearlooks", "nice" and "win32".
1495 The default is "win32".  
1497 \fBMONO_TLS_SESSION_CACHE_TIMEOUT\fR
1498 The time, in seconds, that the SSL/TLS session cache will keep it's entry to
1499 avoid a new negotiation between the client and a server. Negotiation are very
1500 CPU intensive so an application-specific custom value may prove useful for 
1501 small embedded systems.
1503 The default is 180 seconds.
1505 \fBMONO_THREADS_PER_CPU\fR
1506 The maximum number of threads in the general threadpool will be
1507 20 + (MONO_THREADS_PER_CPU * number of CPUs). The default value for this
1508 variable is 10.
1510 \fBMONO_XMLSERIALIZER_THS\fR
1511 Controls the threshold for the XmlSerializer to produce a custom
1512 serializer for a given class instead of using the Reflection-based
1513 interpreter.  The possible values are `no' to disable the use of a
1514 custom serializer or a number to indicate when the XmlSerializer
1515 should start serializing.   The default value is 50, which means that
1516 the a custom serializer will be produced on the 50th use.
1518 \fBMONO_XMLSERIALIZER_DEBUG\fR
1519 Set this value to 1 to prevent the serializer from removing the
1520 temporary files that are created for fast serialization;  This might
1521 be useful when debugging.
1523 \fBMONO_ASPNET_INHIBIT_SETTINGSMAP\fR
1524 Mono contains a feature which allows modifying settings in the .config files shipped
1525 with Mono by using config section mappers. The mappers and the mapping rules are
1526 defined in the $prefix/etc/mono/2.0/settings.map file and, optionally, in the
1527 settings.map file found in the top-level directory of your ASP.NET application.
1528 Both files are read by System.Web on application startup, if they are found at the
1529 above locations. If you don't want the mapping to be performed you can set this
1530 variable in your environment before starting the application and no action will
1531 be taken.
1533 \fBMONO_MESSAGING_PROVIDER\fR
1534 Mono supports a plugin model for its implementation of System.Messaging making
1535 it possible to support a variety of messaging implementations (e.g. AMQP, ActiveMQ).
1536 To specify which messaging implementation is to be used the evironement variable
1537 needs to be set to the full class name for the provider.  E.g. to use the RabbitMQ based
1538 AMQP implementation the variable should be set to:
1541 Mono.Messaging.RabbitMQ.RabbitMQMessagingProvider,Mono.Messaging.RabbitMQ
1542 .SH ENVIRONMENT VARIABLES FOR DEBUGGING
1544 \fBMONO_ASPNET_NODELETE\fR
1545 If set to any value, temporary source files generated by ASP.NET support
1546 classes will not be removed. They will be kept in the user's temporary
1547 directory.
1549 \fBMONO_LOG_LEVEL\fR
1550 The logging level, possible values are `error', `critical', `warning',
1551 `message', `info' and `debug'.  See the DEBUGGING section for more
1552 details.
1554 \fBMONO_LOG_MASK\fR
1555 Controls the domain of the Mono runtime that logging will apply to. 
1556 If set, the log mask is changed to the set value. Possible values are
1557 "asm" (assembly loader), "type", "dll" (native library loader), "gc"
1558 (garbage collector), "cfg" (config file loader), "aot" (precompiler),
1559 "security" (e.g. Moonlight CoreCLR support) and "all". 
1560 The default value is "all". Changing the mask value allows you to display only 
1561 messages for a certain component. You can use multiple masks by comma 
1562 separating them. For example to see config file messages and assembly loader
1563 messages set you mask to "asm,cfg".
1565 \fBMONO_TRACE\fR
1566 Used for runtime tracing of method calls. The format of the comma separated
1567 trace options is:
1570         [-]M:method name
1571         [-]N:namespace
1572         [-]T:class name
1573         [-]all
1574         [-]program
1575         disabled                Trace output off upon start.
1578 You can toggle trace output on/off sending a SIGUSR2 signal to the program.
1580 \fBMONO_TRACE_LISTENER\fR
1581 If set, enables the System.Diagnostics.DefaultTraceListener, which will 
1582 print the output of the System.Diagnostics Trace and Debug classes.  
1583 It can be set to a filename, and to Console.Out or Console.Error to display
1584 output to standard output or standard error, respectively. If it's set to
1585 Console.Out or Console.Error you can append an optional prefix that will
1586 be used when writing messages like this: Console.Error:MyProgramName.
1587 See the System.Diagnostics.DefaultTraceListener documentation for more
1588 information.
1590 \fBMONO_XEXCEPTIONS\fR
1591 This throws an exception when a X11 error is encountered; by default a
1592 message is displayed but execution continues
1594 \fBMONO_XSYNC\fR
1595 This is used in the System.Windows.Forms implementation when running
1596 with the X11 backend.  This is used to debug problems in Windows.Forms
1597 as it forces all of the commands send to X11 server to be done
1598 synchronously.   The default mode of operation is asynchronous which
1599 makes it hard to isolate the root of certain problems.
1601 \fBMONO_GENERIC_SHARING\fR
1602 This environment variable controls the kind of generic sharing used.
1603 This variable is used by internal JIT developers and should not be
1604 changed in production.  Do not use it.
1606 The variable controls which classes will have generic code sharing
1607 enabled.
1609 Permissible values are:
1611 .TP 
1612 .I "all" 
1613 All generated code can be shared. 
1615 .I "collections" 
1616 Only the classes in System.Collections.Generic will have its code
1617 shared (this is the default value).
1619 .I "corlib"
1620 Only code in corlib will have its code shared.
1622 .I "none"
1623 No generic code sharing will be performed.
1626 Generic code sharing by default only applies to collections.   The
1627 Mono JIT by default turns this on.
1629 \fBMONO_XDEBUG\fR
1630 When the the MONO_XDEBUG env var is set, debugging info for JITted
1631 code is emitted into a shared library, loadable into gdb. This enables,
1632 for example, to see managed frame names on gdb backtraces.
1634 \fBMONO_VERBOSE_METHOD\fR
1635 Enables the maximum JIT verbosity for the specified method. This is
1636 very helpfull to diagnose a miscompilation problems of a specific
1637 method.
1638 .SH VALGRIND
1639 If you want to use Valgrind, you will find the file `mono.supp'
1640 useful, it contains the suppressions for the GC which trigger
1641 incorrect warnings.  Use it like this:
1643     valgrind --suppressions=mono.supp mono ...
1645 .SH DTRACE
1646 On some platforms, Mono can expose a set of DTrace probes (also known
1647 as user-land statically defined, USDT Probes).
1649 They are defined in the file `mono.d'.
1651 .B ves-init-begin, ves-init-end
1653 Begin and end of runtime initialization.
1655 .B method-compile-begin, method-compile-end
1657 Begin and end of method compilation.
1658 The probe arguments are class name, method name and signature,
1659 and in case of method-compile-end success or failure of compilation.
1661 .B gc-begin, gc-end
1663 Begin and end of Garbage Collection.
1665 To verify the availability of the probes, run:
1667     dtrace -P mono'$target' -l -c mono
1669 .SH PERMISSIONS
1670 Mono's Ping implementation for detecting network reachability can
1671 create the ICMP packets itself without requiring the system ping
1672 command to do the work.  If you want to enable this on Linux for
1673 non-root users, you need to give the Mono binary special permissions.
1675 As root, run this command:
1677    # setcap cap_net_raw=+ep /usr/bin/mono
1679 .SH FILES
1680 On Unix assemblies are loaded from the installation lib directory.  If you set
1681 `prefix' to /usr, the assemblies will be located in /usr/lib.  On
1682 Windows, the assemblies are loaded from the directory where mono and
1683 mint live.
1685 .B ~/.mono/aot-cache
1687 The directory for the ahead-of-time compiler demand creation
1688 assemblies are located. 
1690 .B /etc/mono/config, ~/.mono/config
1692 Mono runtime configuration file.  See the mono-config(5) manual page
1693 for more information.
1695 .B ~/.config/.mono/certs, /usr/share/.mono/certs
1697 Contains Mono certificate stores for users / machine. See the certmgr(1) 
1698 manual page for more information on managing certificate stores and
1699 the mozroots(1) page for information on how to import the Mozilla root
1700 certificates into the Mono certificate store. 
1702 .B ~/.mono/assemblies/ASSEMBLY/ASSEMBLY.config
1704 Files in this directory allow a user to customize the configuration
1705 for a given system assembly, the format is the one described in the
1706 mono-config(5) page. 
1708 .B ~/.config/.mono/keypairs, /usr/share/.mono/keypairs
1710 Contains Mono cryptographic keypairs for users / machine. They can be 
1711 accessed by using a CspParameters object with DSACryptoServiceProvider
1712 and RSACryptoServiceProvider classes.
1714 .B ~/.config/.isolatedstorage, ~/.local/share/.isolatedstorage, /usr/share/.isolatedstorage
1716 Contains Mono isolated storage for non-roaming users, roaming users and 
1717 local machine. Isolated storage can be accessed using the classes from 
1718 the System.IO.IsolatedStorage namespace.
1720 .B <assembly>.config
1722 Configuration information for individual assemblies is loaded by the
1723 runtime from side-by-side files with the .config files, see the
1724 http://www.mono-project.com/Config for more information.
1726 .B Web.config, web.config
1728 ASP.NET applications are configured through these files, the
1729 configuration is done on a per-directory basis.  For more information
1730 on this subject see the http://www.mono-project.com/Config_system.web
1731 page. 
1732 .SH MAILING LISTS
1733 Mailing lists are listed at the
1734 http://www.mono-project.com/Mailing_Lists
1735 .SH WEB SITE
1736 http://www.mono-project.com
1737 .SH SEE ALSO
1739 certmgr(1), csharp(1), mcs(1), mdb(1), monocov(1), monodis(1),
1740 mono-config(5), mozroots(1), pdb2mdb(1), xsp(1), mod_mono(8).
1742 For more information on AOT:
1743 http://www.mono-project.com/AOT
1745 For ASP.NET-related documentation, see the xsp(1) manual page