# Mono Internals

This section documents some of the internal APIs used inside Mono that developers extending or altering Mono might want to use.

## Strings

### Other Encodings

These routines are used when coping with strings that come from Mono's environment, and might be encoded in one or more of the external encodings.

For example, some file systems might historically contain a mix of file names with both old and new encodings, typically UTF8 for new files, and the old files would be encoded in an 8 bit character set (ISO-8859-1 for example).

These routines try a number of encodings, those specified in the `MONO_ENCODINGS` environment variable and return unicode strings that can be used internally.

See the mono(1) man page for more details.
`mono_unicode_from_external`
Syntax
gunichar2* mono_unicode_from_external (const gchar *in, gsize *bytes)

Parameters

in | pointers to the buffer.
bytes | number of bytes in the string.

Description

Tries to turn a `NULL`-terminated string into UTF16.

First, see if it's valid UTF8, in which case just turn it directly into UTF16. Next, run through the colon-separated encodings in MONO_EXTERNAL_ENCODINGS and do an iconv conversion on each, returning the first successful conversion to UTF16. If no conversion succeeds, return `NULL`.

Callers must free the returned string if not `NULL`. bytes holds the number of bytes in the returned string, not including the terminator.
`mono_unicode_to_external`
Syntax
gchar*mono_unicode_to_external (const gunichar2 *uni)

Parameters

uni | an UTF16 string to conver to an external representation.

Description

Turns `NULL`-terminated UTF16 into either UTF8, or the first working item in MONO_EXTERNAL_ENCODINGS if set. If no conversions work, then UTF8 is returned.

Callers must free the returned string.
`mono_utf8_from_external`
Syntax
gchar*mono_utf8_from_external (const gchar *in)

Parameters

in | pointer to the string buffer.

Description

Tries to turn a `NULL`-terminated string into UTF8.

First, see if it's valid UTF8, in which case there's nothing more to be done. Next, run through the colon-separated encodings in MONO_EXTERNAL_ENCODINGS and do an iconv conversion on each, returning the first successful conversion to utf8. If no conversion succeeds, return `NULL`.

Callers must free the returned string if not `NULL`.

This function is identical to mono_unicode_from_external, apart from returning utf8 not utf16; it's handy in a few places to work in utf8.

## Marshalling functions

`mono_marshal_alloc`
Syntax
mono_marshal_alloc

`mono_marshal_asany`
Syntax
mono_marshal_asany

`mono_marshal_free_array`
Syntax
mono_marshal_free_array

`mono_marshal_free_asany`
Syntax
mono_marshal_free_asany

`mono_marshal_free`
Syntax
mono_marshal_free

`mono_marshal_get_castclass`
Syntax
mono_marshal_get_castclass

`mono_marshal_get_delegate_begin_invoke`
Syntax
mono_marshal_get_delegate_begin_invoke

`mono_marshal_get_delegate_end_invoke`
Syntax
mono_marshal_get_delegate_end_invoke

`mono_marshal_get_delegate_invoke`
Syntax
mono_marshal_get_delegate_invoke

`mono_marshal_get_icall_wrapper`
Syntax
mono_marshal_get_icall_wrapper

`mono_marshal_get_isinst`
Syntax
mono_marshal_get_isinst

`mono_marshal_get_ldfld_remote_wrapper`
Syntax
mono_marshal_get_ldfld_remote_wrapper

`mono_marshal_get_ldfld_wrapper`
Syntax
mono_marshal_get_ldfld_wrapper

`mono_marshal_get_managed_wrapper`
Syntax
mono_marshal_get_managed_wrapper

`mono_marshal_get_native_wrapper`
Syntax
MonoMethod* mono_marshal_get_native_wrapper (MonoMethod *method, gboolean check_exceptions, gboolean aot)

Parameters

method | The MonoMethod to wrap.
check_exceptions | Whenever to check for pending exceptions

Description

generates IL code for the pinvoke wrapper (the generated method calls the unmanaged code in piinfo->addr)
`mono_marshal_get_proxy_cancast`
Syntax
mono_marshal_get_proxy_cancast

`mono_marshal_get_ptr_to_struct`
Syntax
MonoMethod* mono_marshal_get_ptr_to_struct (MonoClass *klass)

Parameters

klass |

Description

generates IL code for PtrToStructure (IntPtr src, object structure)
`mono_marshal_get_remoting_invoke_for_target`
Syntax
mono_marshal_get_remoting_invoke_for_target

`mono_marshal_get_remoting_invoke`
Syntax
mono_marshal_get_remoting_invoke

`mono_marshal_get_remoting_invoke_with_check`
Syntax
mono_marshal_get_remoting_invoke_with_check

`mono_marshal_get_runtime_invoke`
Syntax
mono_marshal_get_runtime_invoke

`mono_marshal_get_stelemref`
Syntax
mono_marshal_get_stelemref

`mono_marshal_get_stfld_remote_wrapper`
Syntax
mono_marshal_get_stfld_remote_wrapper

`mono_marshal_get_stfld_wrapper`
Syntax
mono_marshal_get_stfld_wrapper

`mono_marshal_get_struct_to_ptr`
Syntax
MonoMethod* mono_marshal_get_struct_to_ptr (MonoClass *klass)

Parameters

klass |

Description

generates IL code for StructureToPtr (object structure, IntPtr ptr, bool fDeleteOld)
`mono_marshal_get_synchronized_wrapper`
Syntax
mono_marshal_get_synchronized_wrapper

`mono_marshal_get_unbox_wrapper`
Syntax
mono_marshal_get_unbox_wrapper

`mono_marshal_get_xappdomain_invoke`
Syntax
mono_marshal_get_xappdomain_invoke

`mono_marshal_load_type_info`
Syntax
MonoMarshalType* mono_marshal_load_type_info (MonoClass* klass)

Description

Initialize klass->marshal_info using information from metadata. This function can recursively call itself, and the caller is responsible to avoid that by calling mono_marshal_is_loading_type_info () beforehand.

LOCKING: Acquires the loader lock.
`mono_marshal_method_from_wrapper`
Syntax
mono_marshal_method_from_wrapper

`mono_marshal_realloc`
Syntax
mono_marshal_realloc

`mono_marshal_set_last_error`
Syntax
void mono_marshal_set_last_error (void)

Description

This function is invoked to set the last error value from a P/Invoke call which has SetLastError set.
`mono_marshal_type_size`
Syntax
mono_marshal_type_size

## Metadata Loading Errors

The routines in this section are used to cope with errors during metadata loading. Errors in metadata handling can happen for many reason, and these include (this is not an exhaustive list).

- An assembly referenced is missing.
- Fields referenced are missing.
- Methods referenced are missing.

The `mono_loader_set_*` routines are invoked during metadata loading to flag that an error has happened. The class loading errros are flagged in a per-thread basis.

In various spots in the runtime the `mono_loader_get_last_error` routine is called to check if there was a problem, and then errors are propagated upwards on the stack until we reach a point where an exception can be raised and no runtime locks are held.

The `mono_loader_error_prepare_exception` takes a `MonoLoaderError` structure (the value returned from `mono_loader_get_last_error`), turns that into an exception and clears the error condition from the current thread.
`mono_loader_set_error_field_load`
Syntax
mono_loader_set_error_field_load

`mono_loader_set_error_method_load`
Syntax
mono_loader_set_error_method_load

`mono_loader_set_error_type_load`
Syntax
mono_loader_set_error_type_load

`mono_loader_get_last_error`
Syntax
mono_loader_get_last_error

`mono_loader_clear_error`
Syntax
mono_loader_clear_error

`mono_loader_error_prepare_exception`
Syntax
mono_loader_error_prepare_exception

## Metadata Loader Locking: Internals

The locking functions here are used by code in class.c and metadata.c to lock access to the shared hashtables inside the MonoImage.
`mono_loader_lock`
Syntax
void mono_loader_lock (void)

Description

See docs/thread-safety.txt for the locking strategy.
`mono_loader_unlock`
Syntax
mono_loader_unlock

## Garbage Collector Internal Interface

The internal interface of the Mono GC is the interface used between the runtime engine and the garbage collector.
`mono_gc_disable`
Syntax
mono_gc_disable

`mono_gc_enable`
Syntax
mono_gc_enable

`mono_gc_start_world`
Syntax
mono_gc_start_world

`mono_gc_stop_world`
Syntax
mono_gc_stop_world

`mono_gc_alloc_fixed`
Syntax
mono_gc_alloc_fixed

`mono_gc_free_fixed`
Syntax
mono_gc_free_fixed

`mono_gc_make_descr_from_bitmap`
Syntax
mono_gc_make_descr_from_bitmap

`mono_gc_base_init`
Syntax
mono_gc_base_init

`mono_gc_invoke_finalizers`
Syntax
mono_gc_invoke_finalizers

`mono_gc_is_gc_thread`
Syntax
mono_gc_is_gc_thread

`mono_gc_pending_finalizers`
Syntax
mono_gc_pending_finalizers

`mono_gc_register_thread`
Syntax
mono_gc_register_thread