mono-api-exc.html

## Exception Handling

Mono's exception handling contains methods to create `MonoException*` objects that can be raised.

Alternatively, you can obtain an exception that you can raise from some of the most common exceptions in the .NET Runtime.

### Raising and Catching exceptions

If you plan on running your code in Mono's Cooperative mode for the Garbage Collector (for example, if you are using pure Bitcode code generation), it you should avoid raising an exception from any method that is not the entry point to the internal call.

It is recommended that if you need to raise an error condition from nested parts of your code, surface this error to the topmost method that is surfaced as an internal call and raise the exception there.
`mono_raise_exception`
Syntax
void mono_raise_exception (MonoException *ex)

Parameters

ex | exception object

Description
Signal the runtime that the exception ex has been raised in unmanaged code. DEPRECATED. DO NOT ADD NEW CALLERS FOR THIS FUNCTION.
`mono_unhandled_exception`
Syntax
void mono_unhandled_exception (MonoObject *exc)

Parameters

exc | exception thrown

Description
This is a VM internal routine.

We call this function when we detect an unhandled exception in the default domain.

It invokes the `UnhandledException` event in `AppDomain` or prints a warning to the console
`mono_print_unhandled_exception`
Syntax
void mono_print_unhandled_exception_internal (MonoObject *exc)

Parameters

exc | The exception

Description
Prints the unhandled exception.

### Exception Types: General API

`mono_exception_from_name_domain`
Syntax
MonoException* mono_exception_from_name_domain (MonoDomain *domain, MonoImage *image, const char* name_space, const char *name)

Parameters

domain | Domain where the return object will be created.
image | the Mono image where to look for the class
name_space | the namespace for the class
name | class name

Return value
the initialized exception instance.
Description

Creates an exception object of the given namespace/name class on the given domain.

`mono_exception_from_name`
Syntax
MonoException* mono_exception_from_name (MonoImage *image, const char *name_space, const char *name)

Parameters

image | the Mono image where to look for the class
name_space | the namespace for the class
name | class name

Return value
the initialized exception instance.
Description

Creates an exception of the given namespace/name class in the current domain.

`mono_exception_from_name_msg`
Syntax
MonoException* mono_exception_from_name_msg (MonoImage *image, const char *name_space, const char *name, const char *msg)

Parameters

image | the Mono image where to look for the class
name_space | the namespace for the class
name | class name
msg | the message to embed inside the exception

Return value
the initialized exception instance.
Description

Creates an exception and initializes its message field.

`mono_exception_from_name_two_strings`
Syntax
MonoException* mono_exception_from_name_two_strings (MonoImage *image, const char *name_space, const char *name, MonoString *a1_raw, MonoString *a2_raw)

Parameters

image | the Mono image where to look for the class
name_space | the namespace for the class
name | class name
a1 | first string argument to pass
a2 | second string argument to pass

Return value
the initialized exception instance.
Description

Creates an exception from a constructor that takes two string arguments.

### Obtaining Common Exceptions

There are a number of common exceptions that are used by the runtime, use the routines in this section to get a copy of those exceptions.
`mono_get_exception_appdomain_unloaded`
Syntax
MonoException* mono_get_exception_appdomain_unloaded (void)

Return value
a new instance of the `System.AppDomainUnloadedException`
`mono_get_exception_argument`
Syntax
MonoException* mono_get_exception_argument (const char *arg, const char *msg)

Parameters

arg | the name of the invalid argument.

Return value
a new instance of the `System.ArgumentException`
`mono_get_exception_argument_null`
Syntax
MonoException* mono_get_exception_argument_null (const char *arg)

Parameters

arg | the name of the argument that is null

Return value
a new instance of the `System.ArgumentNullException`
`mono_get_exception_argument_out_of_range`
Syntax
MonoException* mono_get_exception_argument_out_of_range (const char *arg)

Parameters

arg | the name of the out of range argument.

Return value
a new instance of the `System.ArgumentOutOfRangeException`
`mono_get_exception_arithmetic`
Syntax
MonoException* mono_get_exception_arithmetic (void)

Return value
a new instance of the `System.ArithmeticException`
`mono_get_exception_array_type_mismatch`
Syntax
MonoException* mono_get_exception_array_type_mismatch (void)

Return value
a new instance of the `System.ArrayTypeMismatchException`
`mono_get_exception_bad_image_format`
Syntax
MonoException* mono_get_exception_bad_image_format (const char *msg)

Parameters

msg | an informative message for the user.

Return value
a new instance of the `System.BadImageFormatException`
`mono_get_exception_cannot_unload_appdomain`
Syntax
MonoException* mono_get_exception_cannot_unload_appdomain (const char *msg)

Parameters

inner | the inner exception.

Return value
a new instance of the `System.CannotUnloadAppDomainException`
`mono_get_exception_class`
Syntax
MonoClass* mono_get_exception_class (void)

Return value
The `MonoClass*` for the `type`.
Description
Use this function to get the `MonoClass*` that the runtime is using for `System.Exception` .
`mono_get_exception_divide_by_zero`
Syntax
MonoException* mono_get_exception_divide_by_zero (void)

Return value
a new instance of the `System.DivideByZeroException`
`mono_get_exception_execution_engine`
Syntax
MonoException* mono_get_exception_execution_engine (const char *msg)

Parameters

msg | the message to pass to the user

Return value
a new instance of the `System.ExecutionEngineException`
`mono_get_exception_file_not_found2`
Syntax
MonoException* mono_get_exception_file_not_found2 (const char *msg, MonoString *fname_raw)

Parameters

msg | an informative message for the user.
fname | the name of the file not found.

Return value
a new instance of the `System.IO.FileNotFoundException`
`mono_get_exception_file_not_found`
Syntax
MonoException* mono_get_exception_file_not_found (MonoString *fname_raw)

Parameters

fname | the name of the file not found.

Return value
a new instance of the `System.IO.FileNotFoundException`
`mono_get_exception_index_out_of_range`
Syntax
MonoException* mono_get_exception_index_out_of_range ()

Return value
a new instance of the `System.IndexOutOfRangeException`
`mono_get_exception_invalid_cast`
Syntax
MonoException* mono_get_exception_invalid_cast ()

Return value
a new instance of the `System.InvalidCastException`
`mono_get_exception_io`
Syntax
MonoException* mono_get_exception_io (const char *msg)

Parameters

msg | the message to present to the user

Return value
a new instance of the `System.IO.IOException`
`mono_get_exception_missing_method`
Syntax
MonoException* mono_get_exception_missing_method (const char *class_name, const char *member_name)

Parameters

class_name | the class where the lookup was performed.
member_name | the name of the missing method.

Return value
a new instance of the `System.MissingMethodException`
`mono_get_exception_not_implemented`
Syntax
MonoException* mono_get_exception_not_implemented (const char *msg)

Parameters

msg | the message to pass to the user

Return value
a new instance of the `System.NotImplementedException`
`mono_get_exception_null_reference`
Syntax
MonoException* mono_get_exception_null_reference (void)

Return value
a new instance of the `System.NullReferenceException`
`mono_get_exception_overflow`
Syntax
MonoException* mono_get_exception_overflow (void)

Return value
a new instance of the `System.OverflowException`
`mono_get_exception_security`
Syntax
MonoException* mono_get_exception_security (void)

Return value
a new instance of the `System.Security.SecurityException`
`mono_get_exception_serialization`
Syntax
MonoException* mono_get_exception_serialization (const char *msg)

Parameters

msg | the message to pass to the user

Return value
a new instance of the `System.Runtime.Serialization.SerializationException`
`mono_get_exception_stack_overflow`
Syntax
MonoException* mono_get_exception_stack_overflow (void)

Return value
a new instance of the `System.StackOverflowException`
`mono_get_exception_synchronization_lock`
Syntax
MonoException* mono_get_exception_synchronization_lock (const char *msg)

Parameters

inner | the inner exception.

Return value
a new instance of the `System.SynchronizationLockException`
`mono_get_exception_thread_abort`
Syntax
MonoException* mono_get_exception_thread_abort (void)

Return value
a new instance of the `System.Threading.ThreadAbortException`
`mono_get_exception_thread_state`
Syntax
MonoException* mono_get_exception_thread_state (const char *msg)

Parameters

msg | the message to present to the user

Return value
a new instance of the `System.Threading.ThreadStateException`
`mono_get_exception_type_initialization`
Syntax
MonoException* mono_get_exception_type_initialization (const gchar *type_name, MonoException* inner_raw)

Parameters

type_name | the name of the type that failed to initialize.
inner | the inner exception.

Return value
a new instance of the `System.TypeInitializationException`
`mono_get_exception_type_load`
Syntax
MonoException* mono_get_exception_type_load (MonoString *class_name_raw, char *assembly_name)

Parameters

class_name | the name of the class that could not be loaded
assembly_name | the assembly where the class was looked up.

Return value
a new instance of the `System.TypeLoadException`
`mono_get_exception_invalid_operation`
Syntax
MonoException* mono_get_exception_invalid_operation (const char *msg)

Parameters

msg | the message to pass to the user

Return value
a new instance of the `System.InvalidOperationException`
`mono_get_exception_missing_field`
Syntax
MonoException* mono_get_exception_missing_field (const char *class_name, const char *member_name)

Parameters

class_name | the class where the lookup was performed
member_name | the name of the missing field.

Return value
a new instance of the `System.MissingFieldException`
`mono_get_exception_not_supported`
Syntax
MonoException* mono_get_exception_not_supported (const char *msg)

Parameters

msg | the message to pass to the user

Return value
a new instance of the `System.NotSupportedException`
`mono_get_exception_reflection_type_load`
Syntax
MonoException* mono_get_exception_reflection_type_load (MonoArray *types_raw, MonoArray *exceptions_raw)

Parameters

types | an array of types that were defined in the moduled loaded.
exceptions | an array of exceptions that were thrown during the type loading.

Return value
a new instance of the `System.Reflection.ReflectionTypeLoadException`
`mono_exception_from_token_two_strings`
Syntax
MonoException* mono_exception_from_token_two_strings (MonoImage *image, guint32 token, MonoString *arg1_raw, MonoString *arg2_raw)

Description

Same as mono_exception_from_name_two_strings, but lookup the exception class using IMAGE and TOKEN.
`mono_get_exception_bad_image_format2`
Syntax
MonoException* mono_get_exception_bad_image_format2 (const char *msg, MonoString *fname_raw)

Parameters

msg | an informative message for the user.
fname | The full name of the file with the invalid image.

Return value
a new instance of the `System.BadImageFormatException`
`mono_get_exception_field_access`
Syntax
MonoException* mono_get_exception_field_access (void)

Return value
a new instance of the `System.FieldAccessException`
`mono_get_exception_method_access`
Syntax
MonoException* mono_get_exception_method_access (void)

Return value
a new instance of the `System.MethodAccessException`
`mono_get_exception_out_of_memory`
Syntax
MonoException* mono_get_exception_out_of_memory (void)

Return value
a new instance of the `System.OutOfMemoryException`
`mono_get_exception_runtime_wrapped`
Syntax
MonoException* mono_get_exception_runtime_wrapped (MonoObject *wrapped_exception_raw)