KallistiOS  ##version##
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
library.h
Go to the documentation of this file.
1 /* KallistiOS ##version##
2 
3  include/kos/library.h
4  Copyright (C)2003 Dan Potter
5 
6 */
7 
8 /** \file kos/library.h
9  \brief Dynamically loadable library support.
10 
11  This file contains definitions for accessing loadable libraries at runtime.
12  Each library has a name and a version number that it can be referenced by.
13  One must be careful with these dynamic libraries as there is no private
14  storage per instance, and all memory space is shared.
15 
16  Libraries can both export and import symbols. Imported symbols may require
17  other libraries to be loaded earlier. Libraries are reference counted so
18  that they can be opened multiple times without actually loading them
19  multiple times, and so that a close will act as expected in situations like
20  this.
21 
22  \author Dan Potter
23 */
24 
25 #ifndef __KOS_LIBRARY_H
26 #define __KOS_LIBRARY_H
27 
28 #include <sys/cdefs.h>
29 __BEGIN_DECLS
30 
31 #include <kos/thread.h>
32 #include <kos/elf.h>
33 #include <kos/fs.h>
34 
35 /** \cond */
36 /* Pre-define list/queue types */
37 struct klibrary;
38 TAILQ_HEAD(klqueue, klibrary);
39 LIST_HEAD(kllist, klibrary);
40 /** \endcond */
41 
42 /* Thread IDs are ok for us */
43 typedef tid_t libid_t; /**< \brief Library ID type. */
44 
45 /** \brief Loaded library structure.
46 
47  This structure represents a single loaded library. Each library is
48  essentially a loaded binary of code and a set of exported entry points that
49  are standardized.
50 
51  Each loaded library should export at least the functions described in this
52  structure:
53  \li const char *lib_get_name()
54  \li uint32 %lib_get_version()
55  \li int lib_open(struct klibrary *lib)
56  \li int lib_close(struct klibrary *lib)
57 
58  You should not modify any members of this structure yourself (except if you
59  are implementing a library).
60 
61  \headerfile kos/library.h
62 */
63 typedef struct klibrary {
64  /** \brief Library list handle.
65 
66  Contrary to what doxygen might think, this is not a function.
67  */
68  LIST_ENTRY(klibrary) list;
69 
70  /** \brief Library ID (assigned at runtime). */
72 
73  /** \brief Library flags. */
75 
76  /** \brief ELF image for this library.
77 
78  This can be used to look up additional entry points in the library.
79  */
81 
82  /** \brief Library reference count.
83 
84  This value is incremented every time the library is opened, and
85  decremented each time it is closed. Once the library's reference count
86  hits 0, a close will actually destroy the library.
87  */
88  int refcnt;
89 
90  /* Standard library entry points. Every loaded library must provide
91  at least these things. */
92 
93  /** \brief Retrieve the library's symbolic name.
94 
95  This function must be implemented by all loadable libraries to fetch the
96  library's symbolic name. This function must work before calling
97  lib_open() on the library.
98 
99  \return The library's symbolic name
100  */
101  const char * (*lib_get_name)();
102 
103  /** \brief Retrieve the library's version.
104 
105  This function must be implemented by all loadble libraries to fetch the
106  library's version number. This function must work before calling
107  lib_open() on the library.
108 
109  \return The library's version number
110  */
112 
113  /** \brief Open a library.
114 
115  This function must be implemented by all loadable libraries to
116  initialize the library on load. If the library is already opened, this
117  may only involve increasing the reference count.
118 
119  \param lib The library structure
120  \return Values >= 0 indicate success, < 0 indicates failure.
121  A failure on the first lib_open is indicative that
122  the library should be removed from memory.
123  */
124  int (*lib_open)(struct klibrary * lib);
125 
126  /** \brief Close an opened library.
127 
128  This function must be implemented by all loadable libraries to close and
129  deinitialize a library. If the library's reference count is > 1 when
130  this function is called, this may involve simply decrementing the
131  reference count.
132 
133  \param lib The library structure
134  \return Values >= 0 indicate success, < 0 indicates failure
135  */
136  int (*lib_close)(struct klibrary * lib);
137 } klibrary_t;
138 
139 /* Library flag values */
140 #define LIBRARY_DEFAULTS 0 /**< \brief Defaults: no flags */
141 
142 /** \cond */
143 /* Library list; note: do not manipulate directly */
144 extern struct kllist library_list;
145 /** \endcond */
146 
147 /** \brief Look up a library by ID.
148 
149  This function looks up a library by its library ID.
150 
151  \param libid The library ID to look up
152  \return The specified library, or NULL if not found
153 */
155 
156 /** \brief Create a new library shell.
157 
158  This function creates a new library, adding it to the list of libraries. You
159  generally should not call this function directly, unless you have some good
160  reason to do so.
161 
162  \param flags Flags to create the library with.
163  \return The newly created library, or NULL on error
164 */
165 klibrary_t *library_create(int flags);
166 
167 /** \brief Destroy a library.
168 
169  This function will take a loaded library and destroy it, unloading it
170  completely. Generally, you should not call this function, but rather use
171  library_close() to make sure that you're not closing something that is still
172  in use.
173 
174  \param lib The library to close
175  \retval 0 Upon successfully destroying the library
176 */
177 int library_destroy(klibrary_t *lib);
178 
179 /** \brief Try to open a library by name.
180 
181  This function attempts to open a library by its name. If it cannot be found
182  by name, this function will attempt to load the library from the specified
183  filename.
184 
185  \param name The symbolic name of the library
186  \param fn The filename to load the library from
187  \return A handle to the library, or NULL on error with errno
188  set as appropriate
189 
190  \par Error Conditions:
191  \em EINVAL - the library was found or loaded, but invalid \n
192  \em ENOMEM - out of memory \n
193  \em ENOENT - library not found and no filename given
194 */
195 klibrary_t * library_open(const char * name, const char * fn);
196 
197 /** \brief Look up a library by name.
198 
199  This function looks up a library by its symbolic name without trying to
200  actually load or open it. This is useful if you want to open a library but
201  not keep around a handle to it (which isn't necessarily encouraged).
202 
203  \param name The name of the library to search for
204  \return The library, if found. NULL if not found, errno set
205  as appropriate.
206 
207  \par Error Conditions:
208  \em ENOENT - the library was not found
209 */
210 klibrary_t * library_lookup(const char * name);
211 
212 /** \brief Close a previously opened library.
213 
214  This function will close the specified library. This may involve simply
215  decrementing its reference count, however, it may also involve actually
216  closing and freeing the library. Thus, don't try to use the library after
217  calling this without reopening it first.
218 
219  \param lib The library to close
220  \retval 0 On success
221  \retval -1 On error, errno may be set to an appropriate code
222 
223  \par Error Conditions:
224  \em EINVAL - the library is not valid
225 */
226 int library_close(klibrary_t * lib);
227 
228 /** \brief Retrieve the specified library's runtime-assigned ID.
229  \param lib The library to examine
230  \return The library's ID, or -1 on error
231 
232  \par Error Conditions:
233  \em EINVAL - the library is not valid
234 */
236 
237 /** \brief Retrieve the specified library's reference count.
238  \param lib The library to examine
239  \return The library's reference count, or -1 on error
240 
241  \par Error Conditions:
242  \em EINVAL - the library is not valid
243 */
244 int library_get_refcnt(klibrary_t * lib);
245 
246 /** \brief Retrieve the specified library's name.
247  \param lib The library to examine
248  \return The library's symbolic name, or NULL on error
249 
250  \par Error Conditions:
251  \em EINVAL - the library is not valid
252 */
253 const char * library_get_name(klibrary_t * lib);
254 
255 /** \brief Retrieve the specified library's version.
256  \param lib The library to examine
257  \return The library's version number, or 0 on error
258 
259  \par Error Conditions
260  \em EINVAL - the library is not valid
261 */
263 
264 /** \cond */
265 /* Init */
266 int library_init();
267 
268 /* Shutdown */
269 void library_shutdown();
270 /** \endcond */
271 
272 __END_DECLS
273 
274 #endif /* __KOS_LIBRARY_H */
275 
elf_prog_t image
ELF image for this library.
Definition: library.h:80
typedef LIST_HEAD(nmmgr_list, nmmgr_handler) nmmgr_list_t
Name handler list type.
LIST_ENTRY(klibrary) list
Library list handle.
int refcnt
Library reference count.
Definition: library.h:88
Loaded library structure.
Definition: library.h:63
Virtual filesystem support.
handle_t tid_t
Thread ID type.
Definition: types.h:80
const char * library_get_name(klibrary_t *lib)
Retrieve the specified library's name.
Threading support.
uint32 flags
Library flags.
Definition: library.h:74
libid_t libid
Library ID (assigned at runtime).
Definition: library.h:71
int library_close(klibrary_t *lib)
Close a previously opened library.
int(* lib_open)(struct klibrary *lib)
Open a library.
Definition: library.h:124
uint32(* lib_get_version)()
Retrieve the library's version.
Definition: library.h:111
ELF binary loading support.
klibrary_t * library_by_libid(libid_t libid)
Look up a library by ID.
int library_destroy(klibrary_t *lib)
Destroy a library.
unsigned long uint32
32-bit unsigned integer
Definition: types.h:28
klibrary_t * library_open(const char *name, const char *fn)
Try to open a library by name.
libid_t library_get_libid(klibrary_t *lib)
Retrieve the specified library's runtime-assigned ID.
Kernel-specific definition of a loaded ELF binary.
Definition: elf.h:271
uint32 library_get_version(klibrary_t *lib)
Retrieve the specified library's version.
klibrary_t * library_create(int flags)
Create a new library shell.
int(* lib_close)(struct klibrary *lib)
Close an opened library.
Definition: library.h:136
tid_t libid_t
Library ID type.
Definition: library.h:43
struct klibrary klibrary_t
Loaded library structure.
klibrary_t * library_lookup(const char *name)
Look up a library by name.
int library_get_refcnt(klibrary_t *lib)
Retrieve the specified library's reference count.