Libraries

API for managing dynamically loaded libraries More...

Topics
	ELF File Format
	API for loading and managing ELF files

Files
file	exports.h
	Kernel exported symbols support.
file	library.h
	Dynamically loadable library support.

Data Structures
struct	export_sym_t
	A single export symbol. More...
struct	symtab_handler_t
	A symbol table "handler" for nmmgr. More...
struct	klibrary_t
	Loaded library structure. More...

Macros
#define	LIBRARY_DEFAULTS   0
	Defaults: no flags.

Typedefs
typedef tid_t	libid_t
	Library ID type.

Functions
void	export_init (void)
	Setup initial kernel exports.
export_sym_t *	export_lookup (const char *name)
	Look up a symbol by name.
export_sym_t *	export_lookup_path (const char *name, const char *path)
	Look up a symbol by name and Name Manager path.
export_sym_t *	export_lookup_addr (uintptr_t addr)
	Look up a symbol by approx addr.
klibrary_t *	library_by_libid (libid_t libid)
	Look up a library by ID.
klibrary_t *	library_create (int flags)
	Create a new library shell.
int	library_destroy (klibrary_t *lib)
	Destroy a library.
klibrary_t *	library_open (const char *name, const char *fn)
	Try to open a library by name.
klibrary_t *	library_lookup (const char *name)
	Look up a library by name.
klibrary_t *	library_lookup_fn (const char *fn)
	Look up a library by filename.
int	library_close (klibrary_t *lib)
	Close a previously opened library.
libid_t	library_get_libid (klibrary_t *lib)
	Retrieve the specified library's runtime-assigned ID.
int	library_get_refcnt (klibrary_t *lib)
	Retrieve the specified library's reference count.
const char *	library_get_name (klibrary_t *lib)
	Retrieve the specified library's name.
uint32_t	library_get_version (klibrary_t *lib)
	Retrieve the specified library's version.

Detailed Description

API for managing dynamically loaded libraries

Macro Definition Documentation

LIBRARY_DEFAULTS

#define LIBRARY_DEFAULTS   0

Defaults: no flags.

Typedef Documentation

libid_t

typedef tid_t libid_t

Library ID type.

Function Documentation

export_init()

void export_init

(

void

)

Setup initial kernel exports.

export_lookup()

export_sym_t * export_lookup

(

const char *

name

)

Look up a symbol by name.

Parameters

name	The symbol to look up

Returns

The export structure, or NULL on failure

export_lookup_addr()

export_sym_t * export_lookup_addr

(

uintptr_t

addr

)

Look up a symbol by approx addr.

It can be useful for unhandled exceptions messages.

Parameters

addr	The symbol to look up

Returns

The export structure, or NULL on failure

export_lookup_path()

export_sym_t * export_lookup_path	(	const char *	name,
		const char *	path )

Look up a symbol by name and Name Manager path.

Parameters

name	The symbol to look up
path	The Name Manager path to look up

Returns

The export structure, or NULL on failure

library_by_libid()

klibrary_t * library_by_libid

(

libid_t

libid

)

Look up a library by ID.

This function looks up a library by its library ID.

Parameters

libid

The library ID to look up

Returns

The specified library, or NULL if not found

library_close()

int library_close

(

klibrary_t *

lib

)

Close a previously opened library.

This function will close the specified library. This may involve simply decrementing its reference count, however, it may also involve actually closing and freeing the library. Thus, don't try to use the library after calling this without reopening it first.

Parameters

lib	The library to close

Return values

0	On success
-1	On error, errno may be set to an appropriate code

Error Conditions:

EINVAL - the library is not valid

library_create()

klibrary_t * library_create

(

int

flags

)

Create a new library shell.

This function creates a new library, adding it to the list of libraries. You generally should not call this function directly, unless you have some good reason to do so.

Parameters

flags

Flags to create the library with.

Returns

The newly created library, or NULL on error

library_destroy()

int library_destroy

(

klibrary_t *

lib

)

Destroy a library.

This function will take a loaded library and destroy it, unloading it completely. Generally, you should not call this function, but rather use library_close() to make sure that you're not closing something that is still in use.

Parameters

lib	The library to close

Return values

0	Upon successfully destroying the library

library_get_libid()

libid_t library_get_libid

(

klibrary_t *

lib

)

Retrieve the specified library's runtime-assigned ID.

Parameters

lib	The library to examine

Returns

The library's ID, or -1 on error

Error Conditions:

EINVAL - the library is not valid

library_get_name()

const char * library_get_name

(

klibrary_t *

lib

)

Retrieve the specified library's name.

Parameters

lib	The library to examine

Returns

The library's symbolic name, or NULL on error

Error Conditions:

EINVAL - the library is not valid

library_get_refcnt()

int library_get_refcnt

(

klibrary_t *

lib

)

Retrieve the specified library's reference count.

Parameters

lib	The library to examine

Returns

The library's reference count, or -1 on error

Error Conditions:

EINVAL - the library is not valid

library_get_version()

uint32_t library_get_version

(

klibrary_t *

lib

)

Retrieve the specified library's version.

Parameters

lib	The library to examine

Returns

The library's version number, or 0 on error

Error Conditions

EINVAL - the library is not valid

library_lookup()

klibrary_t * library_lookup

(

const char *

name

)

Look up a library by name.

This is useful if you want to reuse opened library and this is used for library_open().

Parameters

name	The name of the library to search for

Returns

The library, if found. NULL if not found, errno set as appropriate.

Error Conditions:

ENOENT - the library was not found

library_lookup_fn()

klibrary_t * library_lookup_fn

(

const char *

fn

)

Look up a library by filename.

This is useful if you want to reuse opened library and this is used for library_open().

Parameters

fn	The filename of the library to search for

Returns

The library, if found. NULL if not found, errno set as appropriate.

Error Conditions:

ENOENT - the library was not found

library_open()

klibrary_t * library_open	(	const char *	name,
		const char *	fn )

Try to open a library by name.

This function attempts to open a library by its name. If it cannot be found by name, this function will attempt to open by filename. If it cannot be found by filename, this function will attempt to load the library from the specified filename. If the library is already opened, this may only involve increasing the reference count.

Parameters

name	The symbolic name of the library
fn	The filename to load the library from

Returns

A handle to the library, or NULL on error with errno set as appropriate

Error Conditions:

EINVAL - the library was found or loaded, but invalid
ENOMEM - out of memory
ENOENT - library not found and no filename given