.SH SYNOPSIS
.PP
.B mono [options] file [arguments...]
+.PP
+.B mono-sgen [options] file [arguments...]
.SH DESCRIPTION
\fImono\fP is a runtime implementation of the ECMA Common Language
Infrastructure. This can be used to run ECMA and .NET applications.
The runtime provides a number of configuration options for running
applications, for developing and debugging, and for testing and
debugging the runtime itself.
+.PP
+The \fImono\fP command uses the Boehm conservative garbage collector
+while the \fImono-sgen\fP command uses a moving and generational
+garbage collector.
.SH PORTABILITY
On Unix-based systems, Mono provides a mechanism to emulate the
Windows-style file access, this includes providing a case insensitive
Currently the only option supported by this command line argument is
\fBdisable\fR which disables the attach functionality.
.TP
-\fB--full-aot\fR
-This is an experimental flag that instructs the Mono runtime to not
-generate any code at runtime and depend exclusively on the code
-generated from using mono --aot=full previously. This is useful for
-platforms that do not permit dynamic code generation.
-.Sp
-Notice that this feature will abort execution at runtime if a codepath
-in your program, or Mono's class libraries attempts to generate code
-dynamically. You should test your software upfront and make sure that
-you do not use any dynamic features.
-.TP
\fB--config filename\fR
Load the specified configuration file instead of the default one(s).
The default files are /etc/mono/config and ~/.mono/config or the file
.Sp
Used to specify the file where the log will be stored, it defaults to
standard output.
+.TP
+.I server=[y/n]
+Defaults to no, with the default option Mono will actively connect to the
+host/port configured with the \fBaddress\fR option. If you set it to 'y', it
+instructs the Mono runtime to start debugging in server mode, where Mono
+actively waits for the debugger front end to connect to the Mono process.
+Mono will print out to stdout the IP address and port where it is listening.
.ne
.RE
.TP
the heap as much as possible at the expense of slowing down garbage
collection a bit.
.TP
+\fB--full-aot\fR
+This is an experimental flag that instructs the Mono runtime to not
+generate any code at runtime and depend exclusively on the code
+generated from using mono --aot=full previously. This is useful for
+platforms that do not permit dynamic code generation.
+.Sp
+Notice that this feature will abort execution at runtime if a codepath
+in your program, or Mono's class libraries attempts to generate code
+dynamically. You should test your software upfront and make sure that
+you do not use any dynamic features.
+.TP
+\fB--gc=boehm\fR, \fB--gc=sgen\fR
+Selects the Garbage Collector engine for Mono to use, Boehm or SGen.
+Currently this merely ensures that you are running either the
+\fImono\fR or \fImono-sgen\fR commands. This flag can be set in the
+\fBMONO_ENV_OPTIONS\fR environment variable to force all of your child
+processes to use one particular kind of GC with the Mono runtime.
+.TP
\fB--help\fR, \fB-h\fR
Displays usage instructions.
.TP
+\fB--llvm\fR
+If the Mono runtime has been compiled with LLVM support (not available
+in all configurations), Mono will use the LLVM optimization and code
+generation engine to JIT or AOT compile.
+.Sp
+For more information, consult: http://www.mono-project.com/Mono_LLVM
+.TP
+\fB--nollvm\fR
+When using a Mono that has been compiled with LLVM support, it forces
+Mono to fallback to its JIT engine and not use the LLVM backend.
+.TP
\fB--optimize=MODE\fR, \fB-O=MODE\fR
MODE is a comma separated list of optimizations. They also allow
optimizations to be turned off by prefixing the optimization name with
and code coverage see the sections "PROFILING" and "CODE COVERAGE"
below.
.TP
+This option can be used multiple times, each time will load an
+additional profiler. This allows developers to use modules that
+extend the JIT through the Mono profiling interface.
+.TP
\fB--trace[=expression]\fR
Shows method names as they are invoked. By default all methods are
traced.
mono --trace=M:System.Console:WriteLine app.exe
+.fi
+Exceptions can also be traced, it will cause a stack trace to be
+printed every time an exception of the specified type is thrown.
+The exception type can be specified with or without the namespace,
+and to trace all exceptions, specify 'all' as the type name.
+.nf
+
+ mono --trace=E:System.Exception app.exe
+
.fi
As previously noted, various rules can be specified at once:
.nf
environment variable to limit the extent of the messages you get:
If set, the log mask is changed to the set value. Possible values are
"asm" (assembly loader), "type", "dll" (native library loader), "gc"
-(garbage collector), "cfg" (config file loader), "aot" (precompiler) and "all".
+(garbage collector), "cfg" (config file loader), "aot" (precompiler),
+"security" (e.g. Moonlight CoreCLR support) and "all".
The default value is "all". Changing the mask value allows you to display only
messages for a certain component. You can use multiple masks by comma
separating them. For example to see config file messages and assembly loader
assemblies on demand and store the result into a cache in
~/.mono/aot-cache.
.TP
+\fBMONO_ASPNET_INHIBIT_SETTINGSMAP\fR
+Mono contains a feature which allows modifying settings in the .config files shipped
+with Mono by using config section mappers. The mappers and the mapping rules are
+defined in the $prefix/etc/mono/2.0/settings.map file and, optionally, in the
+settings.map file found in the top-level directory of your ASP.NET application.
+Both files are read by System.Web on application startup, if they are found at the
+above locations. If you don't want the mapping to be performed you can set this
+variable in your environment before starting the application and no action will
+be taken.
+.TP
\fBMONO_CFG_DIR\fR
If set, this variable overrides the default system configuration directory
($PREFIX/etc). It's used to locate machine.config file.
($PREFIX/etc/mono/config). The --config command line options overrides the
environment variable.
.TP
-\fBMONO_DEBUG\fR
-If set, enables some features of the runtime useful for debugging.
-This variable should contain a comma separated list of debugging options.
-Currently, the following options are supported:
-.RS
-.ne 8
-.TP
-\fBbreak-on-unverified\fR
-If this variable is set, when the Mono VM runs into a verification
-problem, instead of throwing an exception it will break into the
-debugger. This is useful when debugging verifier problems
-.TP
-\fBcollect-pagefault-stats\fR
-Collects information about pagefaults. This is used internally to
-track the number of page faults produced to load metadata. To display
-this information you must use this option with "--stats" command line
-option.
-.TP
-\fBdont-free-domains\fR
-This is an Optimization for multi-AppDomain applications (most
-commonly ASP.NET applications). Due to internal limitations Mono,
-Mono by default does not use typed allocations on multi-appDomain
-applications as they could leak memory when a domain is unloaded.
-.Sp
-Although this is a fine default, for applications that use more than
-on AppDomain heavily (for example, ASP.NET applications) it is worth
-trading off the small leaks for the increased performance
-(additionally, since ASP.NET applications are not likely going to
-unload the application domains on production systems, it is worth
-using this feature).
-.TP
-\fBhandle-sigint\fR
-Captures the interrupt signal (Control-C) and displays a stack trace
-when pressed. Useful to find out where the program is executing at a
-given point. This only displays the stack trace of a single thread.
-.TP
-\fBkeep-delegates\fR
-This option will leak delegate trampolines that are no longer
-referenced as to present the user with more information about a
-delegate misuse. Basically a delegate instance might be created,
-passed to unmanaged code, and no references kept in managed code,
-which will garbage collect the code. With this option it is possible
-to track down the source of the problems.
-.TP
-\fBno-gdb-backtrace\fR
-This option will disable the GDB backtrace emitted by the runtime
-after a SIGSEGV or SIGABRT in unmanaged code.
-.TP
-\fBsuspend-on-sigsegv\fR
+\fBMONO_CPU_ARCH\fR
+Override the automatic cpu detection mechanism. Currently used only on arm.
+The format of the value is as follows:
+.nf
-This option will suspend the program when a native SIGSEGV is received.
-This is useful for debugging crashes which do not happen under gdb,
-since a live process contains more information than a core file.
-.ne
-.RE
+ "armvV [thumb]"
+
+.fi
+where V is the architecture number 4, 5, 6, 7 and the options can be currently be
+"thunb". Example:
+.nf
+
+ MONO_CPU_ARCH="armv4 thumb" mono ...
+
+.fi
.TP
\fBMONO_DISABLE_AIO\fR
If set, tells mono NOT to attempt using native asynchronous I/O services. In
members of System.Globalization.CompareInfo class. Collation is
enabled by default.
.TP
+\fBMONO_DISABLE_SHM\fR
+Unix only: If set, disables the shared memory files used for
+cross-process handles: process have only private handles. This means
+that process and thread handles are not available to other processes,
+and named mutexes, named events and named semaphores are not visible
+between processes.
+.Sp
+This is can also be enabled by default by passing the
+"--disable-shared-handles" option to configure.
+.Sp
+This is the default from mono 2.8 onwards.
+.TP
\fBMONO_EGD_SOCKET\fR
For platforms that do not otherwise have a way of obtaining random bytes
this can be set to the name of a file system socket on which an egd or
prngd daemon is listening.
.TP
+\fBMONO_ENABLE_SHM\fR
+Unix only: Enable support for cross-process handles. Cross-process
+handles are used to expose process handles, thread handles, named
+mutexes, named events and named semaphores across Unix processes.
+.TP
+\fBMONO_ENV_OPTIONS\fR
+This environment variable allows you to pass command line arguments to
+a Mono process through the environment. This is useful for example
+to force all of your Mono processes to use LLVM or SGEN without having
+to modify any launch scripts.
+.TP
\fBMONO_EVENTLOG_TYPE\fR
Sets the type of event log provider to use (for System.Diagnostics.EventLog).
.Sp
In general if you have problems with encodings in your filenames you
should use the "convmv" program.
.TP
+\fBMONO_GC_PARAMS\fR
+When using Mono with the SGen garbage collector this variable controls
+several parameters of the collector. The variable's value is a comma
+separated list of words.
+.RS
+.ne 8
+.TP
+\fBnursery-size=\fIsize\fR
+Sets the size of the nursery. The size is specified in bytes and must
+be a power of two. The suffixes `k', `m' and `g' can be used to
+specify kilo-, mega- and gigabytes, respectively. The nursery is the
+first generation (of two). A larger nursery will usually speed up the
+program but will obviously use more memory. The default nursery size
+4 MB.
+.TP
+\fBmajor=\fIcollector\fR
+Specifies which major collector to use. Options are `marksweep' for
+the Mark&Sweep collector, `marksweep-par' for parallel Mark&Sweep,
+`marksweep-fixed' for Mark&Sweep with a fixed heap,
+`marksweep-fixed-par' for parallel Mark&Sweep with a fixed heap and
+`copying' for the copying collector. The Mark&Sweep collector is the
+default.
+.TP
+\fBmajor-heap-size=\fIsize\fR
+Sets the size of the major heap (not including the large object space)
+for the fixed-heap Mark&Sweep collector (i.e. `marksweep-fixed' and
+`marksweep-fixed-par'). The size is in bytes, with optional suffixes
+`k', `m' and `g' to specify kilo-, mega- and gigabytes, respectively.
+The default is 512 megabytes.
+.TP
+\fBwbarrier=\fIwbarrier\fR
+Specifies which write barrier to use. Options are `cardtable' and
+`remset'. The card table barrier is faster but less precise, and only
+supported for the Mark&Sweep major collector on 32 bit platforms. The
+default is `cardtable' if it is supported, otherwise `remset'. The cardtable
+write barrier is faster and has a more stable and usually smaller
+memory footprint. If the program causes too much pinning during
+thread scan, it might be faster to enable remset.
+.ne
+.RE
+.TP
+\fBMONO_GC_DEBUG\fR
+When using Mono with the SGen garbage collector this environment
+variable can be used to turn on various debugging features of the
+collector. The value of this variable is a comma separated list of
+words.
+.RS
+.ne 8
+.TP
+\fInumber\fR
+Sets the debug level to the specified number.
+.TP
+\fBcollect-before-allocs\fR
+.TP
+\fBcheck-at-minor-collections\fR
+This performs a consistency check on minor collections and also clears
+the nursery at collection time, instead of the default, when buffers
+are allocated (clear-at-gc). The consistency check ensures that
+there are no major to minor references that are not on the remembered
+sets.
+.TP
+\fBxdomain-checks\fR
+Performs a check to make sure that no references are left to an
+unloaded AppDomain.
+.TP
+\fBclear-at-gc\fR
+This clears the nursery at GC time instead of doing it when the thread
+local allocation buffer (TLAB) is created. The default is to clear
+the nursery at TLAB creation time.
+.TP
+\fBconservative-stack-mark\fR
+Forces the GC to scan the stack conservatively, even if precise
+scanning is available.
+.TP
+\fBcheck-scan-starts\fR
+If set, does a plausibility check on the scan_starts before and after each collection
+.TP
+\fBheap-dump=\fIfile\fR
+Dumps the heap contents to the specified file. To visualize the
+information, use the mono-heapviz tool.
+.TP
+\fBbinary-protocol=\fIfile\fR
+Outputs the debugging output to the specified file. For this to
+work, Mono needs to be compiled with the BINARY_PROTOCOL define on
+sgen-gc.c. You can then use this command to explore the output
+.nf
+ sgen-grep-binprot 0x1234 0x5678 < file
+.fi
+.ne
+.RE
+.TP
\fBMONO_GAC_PREFIX\fR
Provides a prefix the runtime uses to look for Global Assembly Caches.
Directories are separated by the platform path separator (colons on
mono --profile=iomap yourapplication.exe
.fi
-Note, however, that Mono currently supports only one profiler module at a time.
+Note, however, that Mono currently supports only one profiler module
+at a time.
+.TP
+\fBMONO_LLVM\fR
+When Mono is using the LLVM code generation backend you can use this
+environment variable to pass code generation options to the LLVM
+compiler.
.TP
\fBMONO_MANAGED_WATCHER\fR
If set to "disabled", System.IO.FileSystemWatcher will use a file watcher
Gamin, kevent under Unix systems and native API calls on Windows, falling
back to the managed implementation on error.
.TP
+\fBMONO_MESSAGING_PROVIDER\fR
+Mono supports a plugin model for its implementation of System.Messaging making
+it possible to support a variety of messaging implementations (e.g. AMQP, ActiveMQ).
+To specify which messaging implementation is to be used the evironement variable
+needs to be set to the full class name for the provider. E.g. to use the RabbitMQ based
+AMQP implementation the variable should be set to:
+
+.nf
+Mono.Messaging.RabbitMQ.RabbitMQMessagingProvider,Mono.Messaging.RabbitMQ
+.TP
\fBMONO_NO_SMP\fR
If set causes the mono process to be bound to a single processor. This may be
useful when debugging or working around race conditions.
.TP
+\fBMONO_NO_TLS\fR
+Disable inlining of thread local accesses. Try setting this if you get a segfault
+early on in the execution of mono.
+.TP
\fBMONO_PATH\fR
Provides a search path to the runtime where to look for library
files. This is a tool convenient for debugging applications, but
MONO_RTC=4096 mono --profiler=default:stat program.exe
-.fi
-.TP
-\fBMONO_NO_TLS\fR
-Disable inlining of thread local accesses. Try setting this if you get a segfault
-early on in the execution of mono.
-.TP
-\fBMONO_CPU_ARCH\fR
-Override the automatic cpu detection mechanism. Currently used only on arm.
-The format of the value is as follows:
-.nf
-
- "armvV [thumb]"
-
-.fi
-where V is the architecture number 4, 5, 6, 7 and the options can be currently be
-"thunb". Example:
-.nf
-
- MONO_CPU_ARCH="armv4 thumb" mono ...
-
.fi
.TP
\fBMONO_SHARED_DIR\fR
If set, extra checks are made during IO operations. Currently, this
includes only advisory locks around file writes.
.TP
-\fBMONO_DISABLE_SHM\fR
-If set, disables the shared memory files used for cross-process
-handles: process have only private handles. This means that process
-and thread handles are not available to other processes, and named
-mutexes, named events and named semaphores are not visible between
-processes.
-.Sp
-This is can also be enabled by default by passing the
-"--disable-shared-handles" option to configure.
-.TP
\fBMONO_THEME\fR
The name of the theme to be used by Windows.Forms. Available themes today
include "clearlooks", "nice" and "win32".
should start serializing. The default value is 50, which means that
the a custom serializer will be produced on the 50th use.
.TP
-\fBMONO_XMLSERIALIZER_DEBUG\fR
-Set this value to 1 to prevent the serializer from removing the
-temporary files that are created for fast serialization; This might
-be useful when debugging.
-.TP
-\fBMONO_ASPNET_INHIBIT_SETTINGSMAP\fR
-Mono contains a feature which allows modifying settings in the .config files shipped
-with Mono by using config section mappers. The mappers and the mapping rules are
-defined in the $prefix/etc/mono/2.0/settings.map file and, optionally, in the
-settings.map file found in the top-level directory of your ASP.NET application.
-Both files are read by System.Web on application startup, if they are found at the
-above locations. If you don't want the mapping to be performed you can set this
-variable in your environment before starting the application and no action will
-be taken.
-.TP
-\fBMONO_MESSAGING_PROVIDER\fR
-Mono supports a plugin model for its implementation of System.Messaging making
-it possible to support a variety of messaging implementations (e.g. AMQP, ActiveMQ).
-To specify which messaging implementation is to be used the evironement variable
-needs to be set to the full class name for the provider. E.g. to use the RabbitMQ based
-AMQP implementation the variable should be set to:
-
-.nf
-Mono.Messaging.RabbitMQ.RabbitMQMessagingProvider,Mono.Messaging.RabbitMQ
+\fBMONO_X509_REVOCATION_MODE\fR
+Sets the revocation mode used when validating a X509 certificate chain (https,
+ftps, smtps...). The default is 'nocheck', which performs no revocation check
+at all. The other possible values are 'offline', which performs CRL check (not
+implemented yet) and 'online' which uses OCSP and CRL to verify the revocation
+status (not implemented yet).
.SH ENVIRONMENT VARIABLES FOR DEBUGGING
.TP
\fBMONO_ASPNET_NODELETE\fR
classes will not be removed. They will be kept in the user's temporary
directory.
.TP
+\fBMONO_DEBUG\fR
+If set, enables some features of the runtime useful for debugging.
+This variable should contain a comma separated list of debugging options.
+Currently, the following options are supported:
+.RS
+.ne 8
+.TP
+\fBbreak-on-unverified\fR
+If this variable is set, when the Mono VM runs into a verification
+problem, instead of throwing an exception it will break into the
+debugger. This is useful when debugging verifier problems
+.TP
+\fBcasts\fR
+This option can be used to get more detailed information from
+InvalidCast exceptions, it will provide information about the types
+involved.
+.TP
+\fBcollect-pagefault-stats\fR
+Collects information about pagefaults. This is used internally to
+track the number of page faults produced to load metadata. To display
+this information you must use this option with "--stats" command line
+option.
+.TP
+\fBdont-free-domains\fR
+This is an Optimization for multi-AppDomain applications (most
+commonly ASP.NET applications). Due to internal limitations Mono,
+Mono by default does not use typed allocations on multi-appDomain
+applications as they could leak memory when a domain is unloaded.
+.Sp
+Although this is a fine default, for applications that use more than
+on AppDomain heavily (for example, ASP.NET applications) it is worth
+trading off the small leaks for the increased performance
+(additionally, since ASP.NET applications are not likely going to
+unload the application domains on production systems, it is worth
+using this feature).
+.TP
+\fBhandle-sigint\fR
+Captures the interrupt signal (Control-C) and displays a stack trace
+when pressed. Useful to find out where the program is executing at a
+given point. This only displays the stack trace of a single thread.
+.TP
+\fBkeep-delegates\fR
+This option will leak delegate trampolines that are no longer
+referenced as to present the user with more information about a
+delegate misuse. Basically a delegate instance might be created,
+passed to unmanaged code, and no references kept in managed code,
+which will garbage collect the code. With this option it is possible
+to track down the source of the problems.
+.TP
+\fBreverse-pinvoke-exceptions
+This option will cause mono to abort with a descriptive message when
+during stack unwinding after an exception it reaches a native stack
+frame. This happens when a managed delegate is passed to native code,
+and the managed delegate throws an exception. Mono will normally try
+to unwind the stack to the first (managed) exception handler, and it
+will skip any native stack frames in the process. This leads to
+undefined behaviour (since mono doesn't know how to process native
+frames), leaks, and possibly crashes too.
+.TP
+\fBno-gdb-backtrace\fR
+This option will disable the GDB backtrace emitted by the runtime
+after a SIGSEGV or SIGABRT in unmanaged code.
+.TP
+\fBsuspend-on-sigsegv\fR
+
+This option will suspend the program when a native SIGSEGV is received.
+This is useful for debugging crashes which do not happen under gdb,
+since a live process contains more information than a core file.
+.ne
+.RE
+.TP
\fBMONO_LOG_LEVEL\fR
The logging level, possible values are `error', `critical', `warning',
`message', `info' and `debug'. See the DEBUGGING section for more
Controls the domain of the Mono runtime that logging will apply to.
If set, the log mask is changed to the set value. Possible values are
"asm" (assembly loader), "type", "dll" (native library loader), "gc"
-(garbage collector), "cfg" (config file loader), "aot" (precompiler) and "all".
+(garbage collector), "cfg" (config file loader), "aot" (precompiler),
+"security" (e.g. Moonlight CoreCLR support) and "all".
The default value is "all". Changing the mask value allows you to display only
messages for a certain component. You can use multiple masks by comma
separating them. For example to see config file messages and assembly loader
This throws an exception when a X11 error is encountered; by default a
message is displayed but execution continues
.TP
+\fBMONO_XMLSERIALIZER_DEBUG\fR
+Set this value to 1 to prevent the serializer from removing the
+temporary files that are created for fast serialization; This might
+be useful when debugging.
+.TP
\fBMONO_XSYNC\fR
This is used in the System.Windows.Forms implementation when running
with the X11 backend. This is used to debug problems in Windows.Forms
projects / mono.git / blobdiff