library.h File Reference

Dynamically loadable library support. More...

#include <sys/cdefs.h>
#include <kos/thread.h>
#include <kos/elf.h>
#include <kos/fs.h>

Go to the source code of this file.

Data Structures
struct	klibrary
	Loaded library structure. More...

Macros
#define	LIBRARY_DEFAULTS   0
	Defaults: no flags.

Typedefs
typedef tid_t	libid_t
	Library ID type.
typedef struct klibrary	klibrary_t
	Loaded library structure.

Functions
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.
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	library_get_version (klibrary_t *lib)
	Retrieve the specified library's version.

---

Detailed Description

Dynamically loadable library support.

This file contains definitions for accessing loadable libraries at runtime. Each library has a name and a version number that it can be referenced by. One must be careful with these dynamic libraries as there is no private storage per instance, and all memory space is shared.

Libraries can both export and import symbols. Imported symbols may require other libraries to be loaded earlier. Libraries are reference counted so that they can be opened multiple times without actually loading them multiple times, and so that a close will act as expected in situations like this.

Author:

Dan Potter

---

Macro Definition Documentation

#define LIBRARY_DEFAULTS   0

Defaults: no flags.

---

Typedef Documentation

typedef struct klibrary klibrary_t

Loaded library structure.

This structure represents a single loaded library. Each library is essentially a loaded binary of code and a set of exported entry points that are standardized.

Each loaded library should export at least the functions described in this structure:

• const char *lib_get_name()
• uint32 lib_get_version()
• int lib_open(struct klibrary *lib)
• int lib_close(struct klibrary *lib)

You should not modify any members of this structure yourself (except if you are implementing a library).

typedef tid_t libid_t

Library ID type.

---

Function Documentation

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

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

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

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

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

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

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

uint32 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

klibrary_t* library_lookup

(

const char *

name

)

Look up a library by name.

This function looks up a library by its symbolic name without trying to actually load or open it. This is useful if you want to open a library but not keep around a handle to it (which isn't necessarily encouraged).

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

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 load the library from the specified filename.

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