KallistiOS  ##version##
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
Data Structures | Macros | Typedefs | Functions
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. More...
 

Typedefs

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

Functions

klibrary_tlibrary_by_libid (libid_t libid)
 Look up a library by ID. More...
 
klibrary_tlibrary_create (int flags)
 Create a new library shell. More...
 
int library_destroy (klibrary_t *lib)
 Destroy a library. More...
 
klibrary_tlibrary_open (const char *name, const char *fn)
 Try to open a library by name. More...
 
klibrary_tlibrary_lookup (const char *name)
 Look up a library by name. More...
 
int library_close (klibrary_t *lib)
 Close a previously opened library. More...
 
libid_t library_get_libid (klibrary_t *lib)
 Retrieve the specified library's runtime-assigned ID. More...
 
int library_get_refcnt (klibrary_t *lib)
 Retrieve the specified library's reference count. More...
 
const char * library_get_name (klibrary_t *lib)
 Retrieve the specified library's name. More...
 
uint32 library_get_version (klibrary_t *lib)
 Retrieve the specified library's version. More...
 

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
libidThe 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
libThe library to close
Return values
0On success
-1On 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
flagsFlags 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
libThe library to close
Return values
0Upon successfully destroying the library
libid_t library_get_libid ( klibrary_t lib)

Retrieve the specified library's runtime-assigned ID.

Parameters
libThe 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
libThe 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
libThe 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
libThe 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
nameThe 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
nameThe symbolic name of the library
fnThe 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