dlfcn.h File Reference

Helpers to load dynamic libraries. More...

#include <stdio.h>
#include <stdint.h>

Macros
#define	DSL_SYMBOL_MAIN_BINARY   2
	If set, the symbol is in the main binary.
#define	DSL_SYMBOL_PUBLIC   1
	If not set, the symbol is private.
#define	DSL_SYMBOL_UNRESOLVED   4
	If set, the symbol must be resolved at runtime.
#define	RTLD_GLOBAL   0x04
	Make symbols available for other dynamic libraries. Not supported.
#define	RTLD_LAZY   0x01
	Perform lazy binding. Not supported.
#define	RTLD_LOCAL   0x08
	Make symbols only available to this dynamic libraries. Default setting.
#define	RTLD_NOW   0x02
	Load everything right away.

Functions
int	dlclose (void *handle)
	Frees all memory used by a dynamic library.
char *	dlerror (void)
	Returns a user-readable error string.
void *	dlmembase (void *handle)
	Returns a pointer to the base address of the code loaded with the library.
void *	dlopen (const char *file, int mode)
	Loads a dynamic library (in DSL format) into RAM.
void *	dlopen_FILE (FILE *f, int mode)
	Loads a dynamic library (in DSL format) into RAM from a FILE handle.
void *	dlsym (void *handle, const char *name)
	Returns a pointer to the requested symbol.
void	dsl_set_symbol_resolver (SymbolResolverFn fn)
	Set the symbol resolver callback function. Passing NULL is allowed, and disables symbol resolution. You may provide a callback to resolve (or override) symbol values of a DSL before relocation. This is the primary way to let DSLs call functions in each other.

Detailed Description

Helpers to load dynamic libraries.

The functions in this file allow the user to load DSL (Nintendo DS Loadable) files. They are a simplified version of ELF files created by dsltool, which is a tool included in BlocksDS.

Function Documentation

dlclose()

int dlclose

(

void *

handle

)

Frees all memory used by a dynamic library.

Parameters

handle

The handle returned by dlopen().

Returns

On success, it returns 0. On error it returns a non-zero value, and the user is expected to call dlerror() to get a user-readable string with the reason of the error.

dlerror()

char * dlerror

(

void

)

Returns a user-readable error string.

It clears the error string after being called.

Returns

A user-readable error string or NULL if no error has happened since the last call to dlerror().

dlmembase()

void * dlmembase

(

void *

handle

)

Returns a pointer to the base address of the code loaded with the library.

The purpose of this function is to print this address to be used when debugging the code with emulators. You must provide this address when loading the elf file of the library. For example, with the GDB command line:

Note that this is a libnds-specific function.

add-symbol-file path/to/dynamic.elf -s .progbits <load_address>

Note

This is a non-standard function, it's only available in libnds.

Parameters

handle

The handle returned by dlopen().

Returns

On success, it returns a pointer to the base address of the code loaded to RAM. On error it returns NULL, and the user is expected to call dlerror() to get a user-readable string with the reason of the error.

dlopen()

void * dlopen	(	const char *	file,
		int	mode
	)

Loads a dynamic library (in DSL format) into RAM.

Note

The value of the environment variable LD_LIBRARY_PATH is ignored.

Parameters

file	Path of the DSL file.
mode	Mode in which the file will be opened. Currently, the only mode supported is RTLD_NOW | RTLD_LOCAL. Also, RTLD_LOCAL is the default setting, so it isn't required to specify it explicitly.

Returns

On success, it returns a handle to be used by dlsym() and dlclose(). On error, it returns NULL, and the user is expected to call dlerror() to get a user-readable string with the reason of the error.

dlopen_FILE()

void * dlopen_FILE	(	FILE *	f,
		int	mode
	)

Loads a dynamic library (in DSL format) into RAM from a FILE handle.

The handle must be opened before dlopen_FILE() is called and it must be closed after dlopen_FILE() returns. It isn't needed after the library has been loaded.

For example, you can use this to load a dynamic library that you have already loaded to RAM. You can use fmemopen() on the buffer where the library is stored and pass the resulting handle to dlopen_FILE().

Note

This is a non-standard function, it's only available in libnds.

The value of the environment variable LD_LIBRARY_PATH is ignored.

Parameters

f	Open file handle to the DSL library file.
mode	Mode in which the file will be opened. Currently, the only mode supported is RTLD_NOW | RTLD_LOCAL. Also, RTLD_LOCAL is the default setting, so it isn't required to specify it explicitly.

Returns

On success, it returns a handle to be used by dlsym() and dlclose(). On error, it returns NULL, and the user is expected to call dlerror() to get a user-readable string with the reason of the error.

dlsym()

void * dlsym	(	void *	handle,
		const char *	name
	)

Returns a pointer to the requested symbol.

Warning

Don't use free() with the pointers returned by this function.

Parameters

handle	The handle returned by dlopen().
name	The name of the requested symbol.

Returns

On success, it returns a pointer to the location of the symbol in memory. On error it returns a non-zero value, and the user is expected to call dlerror() to get a user-readable string with the reason of the error.

dsl_set_symbol_resolver()

void dsl_set_symbol_resolver

(

SymbolResolverFn

fn

)

Set the symbol resolver callback function. Passing NULL is allowed, and disables symbol resolution. You may provide a callback to resolve (or override) symbol values of a DSL before relocation. This is the primary way to let DSLs call functions in each other.

The callback must return whether symbol resolution succeeded as a boolean. If false is returned for any symbol, dlopen() will fail with the error "symbol resolver failed".

You should use this safety mechanism to return false if you did not resolve a symbol attributed with DSL_SYMBOL_UNRESOLVED. Not resolving these symbols while returning true will result in undefined behavior.

Note

This is a non-standard function, it's only available in libnds.

Parameters

fn	The symbol resolver callback function.