DYNLD(10.2) DYNLD(10.2)
NAME
dynfindsym, dynfreeimport, dynloadfd, dynloadgen,
dynobjfree, dyntabsize - load object file dynamically
SYNOPSIS
#include <lib9.h>
#include <a.out.h>
#include <dynld.h>
Dynsym* dynfindsym(char *name, Dynsym *syms, int nsym)
Dynobj* dynloadfd(int fd, Dynsym *exports, int nexport,
ulong maxsize)
Dynobj* dynloadgen(void *file, long
(*read)(void*,void*,long),
vlong (*seek)(void*,vlong,int), void
(*err)(char*),
Dynsym *exports, int nexport, ulong maxsize)
void* dynimport(Dynobj *o, char *name, ulong sig)
void dynfreeimport(Dynobj *o)
void dynobjfree(Dynobj *o)
int dyntabsize(Dynsym *t)
extern Dynsym _exporttab[];
DESCRIPTION
These functions allow a process to load further code and
data into the currently executing image. A dynamically-
loadable file, called a module here, is a variant of the
a.out(10.6) executable format with some extra components.
The loader for the architecture (see 2l(1)) creates a module
file from component object file(s) when given the -u option.
A module contains text and data sections, an import table,
an export table, and relocation data. The import table
lists the symbols the module needs from the loading program;
the export table lists symbols the module provides when
loaded. A program that loads a module provides a table of
its own symbols to match the symbols in the module's import
table.
A symbol entry in a symbol table names a global function or
data item, and has an associated signature value represent-
ing the type of the corresponding function or data in the
source code. The Dynsym structure defines a symbol:
Page 1 Plan 9 (printed 4/24/24)
DYNLD(10.2) DYNLD(10.2)
typedef struct {
ulong sig;
ulong addr;
char* name;
} Dynsym;
The structure is known to the loaders 2l(1). Name is the
linkage name of the function or data. Addr is its address,
which is relative to the start of the module before loading,
and an address in the current address space after loading.
The signature sig is the value produced by the C compiler's
signof operator applied to the type. Symbol tables must be
sorted by name.
An executable that wishes to load modules will normally be
linked using the -x option to the appropriate loader 2l(1).
The resulting executable contains an export table _exporttab
that lists all the exported symbols of the program (by
default, all external symbols). A nil name marks the end of
the table. See 2l(1) for details. The table can be given
to the functions below to allow a loaded module to access
those symbols.
A loaded module is described by a Dynobj structure:
typedef struct {
ulong size; /* total size in bytes */
ulong text; /* bytes of text */
ulong data; /* bytes of data */
ulong bss; /* bytes of bss */
uchar* base; /* start of text, data, bss */
int nexport;
Dynsym* export; /* export table */
int nimport;
Dynsym** import; /* import table */
} Dynobj;
Several fields give sizes of the module's components, as
noted in comments above. Base gives the address at which
the module has been loaded. All its internal references
have been adjusted where needed to reflect its current
address. Export points to a symbol table listing the sym-
bols exported by the module; nexport gives the table's
length. Import points to a list of symbols imported by the
module; note that each entry actually points to an entry in
a symbol table provided by the program that loaded the mod-
ule (see below). Nimport gives the import table's length.
If the import table is not required, call dynfreeimport on
the module pointer to free it.
Dynfindysm looks up the entry for the given name in symbol
table syms (of length nsym). It returns a pointer to the
Page 2 Plan 9 (printed 4/24/24)
DYNLD(10.2) DYNLD(10.2)
entry if found; nil otherwise. The symbol table must be
sorted by name in ascending order.
Dyntabsize returns the length of symbol table t, defined to
be the number of Dynsym values starting at t that have non-
nil name fields. It is used to find the length of
_exporttab.
Dynloadfd loads a module from the file open for reading on
fd, and returns the resulting module pointer on success, or
nil on error. If maxsize is non-zero the size of the
dynamically-loaded module's code and data is limited to
maxsize bytes. Exports is an array of nexport symbols in
the current program that can be imported by the current mod-
ule. It uses read(2) and seek(2) to access fd, and calls
werrstr (see errstr(2)) to set the error string if neces-
sary.
Dynloadgen is a more general function that can load a module
from an arbitrary source, not just an open file descriptor.
(In particular, it can be called by the kernel using func-
tions internal to the kernel instead of making system
calls.) Exports, nexport and maxsize are just as for
dynloadfd. File is a pointer to a structure defined by the
caller that represents the file containing the module. It
is passed to read and seek. Read is invoked as
(*read)(file,buf, nbytes). Read should read nbytes of data
from file into buf and return the number of bytes trans-
ferred. It should return -1 on error. Seek is invoked as
(*seek)(file,n, type) where n and type are just as for
seek(2); it should seek to the requested offset in file, or
return -1 on error. Dynloadgen returns a pointer to the
loaded module on success. On error, it returns nil after
calling its err parameter to set the error string.
Dynimport returns a pointer to the value of the symbol name
in loaded module o, or nil if o does not export a symbol
with the given name. If sig is non-zero, the exported
symbol's signature must equal sig, or dynimport again
returns nil. For example:
Dev *d;
d = dynimport(obj, "XXXdevtab", signof(*d));
if(d == nil)
error("not a dynamically-loadable driver");
Dynobjfree frees the module o. There is no reference count-
ing: it is the caller's responsibility to decide whether a
module is no longer needed.
SEE ALSO
2l(10.1), a.out(10.6)
Page 3 Plan 9 (printed 4/24/24)
DYNLD(10.2) DYNLD(10.2)
DIAGNOSTICS
Functions that return pointers return nil on error.
Dynloadfd sets the error string and returns nil.
Page 4 Plan 9 (printed 4/24/24)