# CategoryMojoELF

The latest version of MojoELF can be found at:

https://github.com/icculus/mojoelf

MojoELF is an ELF binary loader that runs in your application, instead of
as part of the C runtime. Its most useful feature is that, unlike the
standard `dlopen()`, it can load an ELF file from a place other than the
filesystem. Notably, it can load one from a buffer in memory.

It can also be useful for overriding specific parts of the dependency
management process, such as loading a replacement library or quietly
replacing a function, etc.

To use MojoELF:

- Add mojoelf.c to your build. MojoELF is intended to be compiled directly
  into your project as a single C file, not built as an external shared
  library (but you could probably do that if you like).
- Compile with these #defines set as you please, or change the top of
  mojoelf.c:

```c
  #define MOJOELF_SUPPORT_DLERROR 0  // remove MOJOELF_dlerror() + lots of strings.
  #define MOJOELF_SUPPORT_DLOPEN_FILE 0 // remove MOJOELF_dlopen_file()
  #define MOJOELF_REDUCE_LIBC_DEPENDENCIES 0  // use less libc calls. Scary!
  #define NDEBUG 1  // Turns off assert, which removes libc dependencies.
```

- Your calling code should `#include mojoelf.h` - Put your ELF library in
  memory, and call [MOJOELF_dlopen_mem](MOJOELF_dlopen_mem)() with the
  address of the memory buffer, the size of the buffer, and (optionally),
  callbacks that handle symbol resolution (they can be NULL). Refer to the
  documentation on [MOJOELF_LoaderCallback](MOJOELF_LoaderCallback),
  [MOJOELF_ResolverCallback](MOJOELF_ResolverCallback), and
  [MOJOELF_UnloaderCallback](MOJOELF_UnloaderCallback) for details.
- If [MOJOELF_dlopen_mem](MOJOELF_dlopen_mem)() returns non-NULL, the
  library is ready to use. If it returns NULL, there was a problem
  ([MOJOELF_dlerror](MOJOELF_dlerror)() can give you a human-readable error
  message). On success, you can free your buffer; we don't need it after
  [MOJOELF_dlopen_mem](MOJOELF_dlopen_mem)() returns.
- [MOJOELF_dlopen_file](MOJOELF_dlopen_file)() does the same thing, but
  takes a filename instead of a memory buffer. Internally, it just loads
  the file into a malloc()'d buffer and calls
  [MOJOELF_dlopen_mem](MOJOELF_dlopen_mem)().
- To request entry points into the library, use
  [MOJOELF_dlsym](MOJOELF_dlsym)():

```c
typedef int (*my_fn_type)(int argument);
my_fn_type my_function = (my_fn_type) MOJOELF_dlsym(lib, "AwesomeFunc");
if (my_function == NULL) {
    printf("couldn't find AwesomeFunc!\n");
} else {
    printf("AwesomeFunc() returns %d\n", my_function(123));
}
```

- When you are done with a library, call `MOJOELF_dlclose()` to free any
  resources. All pointers returned by `MOJOELF_dlsym()` for this library
  are invalid after this call. - Other fun stuff: `MOJOELF_getentry()` gets
  you the entry point for the ELF file (which isn't useful on shared
  libraries, but is how you eventually get to main() in an executable).

Thread safety:

MojoELF provides no locking mechanisms, and has a piece of global state
that almost any function can set (the [MOJOELF_dlerror](MOJOELF_dlerror)()
state). As such, the app is responsible for providing a serialization
method if they plan to use MojoELF from multiple threads at once.

Other stuff:

Please see the file LICENSE.txt in the source's root directory for
licensing and redistribution rights.

<!-- END CATEGORY DOCUMENTATION -->

## Functions

<!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. -->
<!-- BEGIN CATEGORY LIST: CategoryMojoELF, CategoryAPIFunction -->
- [MOJOELF_dlclose](MOJOELF_dlclose)
- [MOJOELF_dlerror](MOJOELF_dlerror)
- [MOJOELF_dlopen_file](MOJOELF_dlopen_file)
- [MOJOELF_dlopen_mem](MOJOELF_dlopen_mem)
- [MOJOELF_dlsym](MOJOELF_dlsym)
- [MOJOELF_getentry](MOJOELF_getentry)
- [MOJOELF_getmmaprange](MOJOELF_getmmaprange)
<!-- END CATEGORY LIST -->

## Datatypes

<!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. -->
<!-- BEGIN CATEGORY LIST: CategoryMojoELF, CategoryAPIDatatype -->
- [MOJOELF_LoaderCallback](MOJOELF_LoaderCallback)
- [MOJOELF_ResolverCallback](MOJOELF_ResolverCallback)
- [MOJOELF_UnloaderCallback](MOJOELF_UnloaderCallback)
<!-- END CATEGORY LIST -->

## Structs

<!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. -->
<!-- BEGIN CATEGORY LIST: CategoryMojoELF, CategoryAPIStruct -->
- [MOJOELF_Callbacks](MOJOELF_Callbacks)
<!-- END CATEGORY LIST -->

## Enums

<!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. -->
<!-- BEGIN CATEGORY LIST: CategoryMojoELF, CategoryAPIEnum -->
- (none.)
<!-- END CATEGORY LIST -->

## Macros

<!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. -->
<!-- BEGIN CATEGORY LIST: CategoryMojoELF, CategoryAPIMacro -->
- [MOJOELF_CALL](MOJOELF_CALL)
- [MOJOELF_DECL](MOJOELF_DECL)
- [MOJOELF_MAJOR_VERSION](MOJOELF_MAJOR_VERSION)
- [MOJOELF_MICRO_VERSION](MOJOELF_MICRO_VERSION)
- [MOJOELF_MINOR_VERSION](MOJOELF_MINOR_VERSION)
<!-- END CATEGORY LIST -->

----
[CategoryAPICategory](CategoryAPICategory)