Chapter 24
Runtime Linker/Loader: liboskit_rtld.a

24.1 Introduction

This section describes the Runtime Linker/Loader (RTLD) support in the OSKit. The library code is derived from the FreeBSD 3.0 ELF runtime link-editor library, and was modified to work in the OSKit. Rather than operating as an “interpreter,” the RTLD library is linked in directly with an OSKit kernel, and exports the standard set of interface functions that allow shared libraries to be loaded and unloaded. The OSKit kernel must have been compiled and linked properly so that the kernel is in the correct binary format (ELF), and contains the necessary information (dynamic symbol table, etc.) in the executable file. The reader should consult the demonstration kernel in examples/dyntest, which shows how the kernel should be linked, and how to compile, link, and load a shared library. Shared libraries are loaded into the kernel using the dlopen function, which is described below. Once a library is loaded, the dlsym function is used to find individual symbols inside that library. A shared library is unloaded with the dlclose function.

In order to use the RTLD functions, the OSKit kernel must first initialize the RTLD library. This is done with the oskit_boot_rtld function.

24.1.1 oskit_boot_rtld: Initialize the RTLD library

SYNOPSIS

#include <dlfnc.h>

int oskit_boot_rtld(char *aoutname);

DESCRIPTION

Initialize the runtime loader library, allowing shared libraries to be loaded. The initialization routine takes an optional pathname, which is the location of the OSKit executable image. If the kernel was loaded with netboot (see Section 46), or any other loader that loads all of the “loadable” sections of an ELF binary, the kernel image is not required since all of the necessary information is already available. Otherwise, the path of the OSKit kernel image must be specified. The initialization function will interpret the dynamic symbol table information, and create the necessary data structures to allow Shared libraries to be loaded and linked against the OSKit kernel.

PARAMETERS
aoutname:
Pathname to the oskit kernel image.
RETURNS

Returns 0 on success.

24.1.2 dlopen: Load a shared library

SYNOPSIS

#include <dlfnc.h>

void *dlopen(const char *name, int mode);

DESCRIPTION

Load the shared library named name, returning a descriptor that can be used in subsequent calls to dlsym and dlclose. If the library is already loaded, a new reference to the same object is returned. When a shared library is first loaded, its _init() function, if it exists, is called by the linker. The mode argument is currently ignored.

PARAMETERS
name:
Path to the shared library to be loaded.
mode:
Modify how external references are bound.
RETURNS

Returns a descriptor that can be used in later references to the object. Returns NULL on failure.

24.1.3 dlsym: Find the address binding for a symbol

SYNOPSIS

#include <dlfnc.h>

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

DESCRIPTION

Return the address binding of the symbol name from the shared library identified by handle. The symbols that are exported from shared libraries loaded with dlopen, can only be accessed with dlsym. The name of the symbol is its assembly language representation, which is not necessarily the same as its representation in the C source code. Be sure to consult your local compiler documentation. If the symbol cannot be found, dlsym returns NULL and and sets an error condition which may be queried with dlerror.

PARAMETERS
handle:
The descriptor of the shared library to search.
name:
The name of the symbol to search for.
RETURNS

Returns the address binding of the symbol on success, NULL otherwise.

24.1.4 dlclose: Delete a reference to a shared library

SYNOPSIS

#include <dlfnc.h>

int dlclose(void *handle);

DESCRIPTION

Delete the reference to the shared library referenced by handle. When the reference count reaches zero, the shared library is removed the OSKit kernel’s address space, and the descriptor becomes invalid. Subsequent attempts to use the descriptor will result in undefined behavior. When the final reference to a shared library is deleted, the library’s finalization function _fini(), if it exists, is called by the linker.

PARAMETERS
handle:
The descriptor of the shared library to delete.
RETURNS

Returns 0 on success.

24.1.5 dlerror: Return an error message describing the last error

SYNOPSIS

#include <dlfnc.h>

const char *dlerror(void);

DESCRIPTION

Return a null-terminated string describing the last error that occurred during a call to dlopen, dlsym, or dlclose. After a call to dlerror, the error status is reset, and a subsequent call will return a NULL pointer.

RETURNS

Returns a null-terminated string, or NULL if there is no error to report.