dlfcn.h File Reference

Helpers to load dynamic libraries. More...

#include <stdio.h>

Macros
#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.

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.