.TH DYNLD 10.2.SH NAMEdynfindsym, dynfreeimport, dynloadfd, dynloadgen, dynobjfree, dyntabsize \- load object file dynamically.SH SYNOPSIS.B #include <lib9.h>.br.B #include <a.out.h>.br.B #include <dynld.h>.PP.ta \w'\fLDynsym*** 'u.BDynsym* dynfindsym(char *name, Dynsym *syms, int nsym).PP.BDynobj* dynloadfd(int fd, Dynsym *exports, int nexport,.br.B ulong maxsize).PP.BDynobj* dynloadgen(void *file, long (*read)(void*,void*,long),.br.B vlong (*seek)(void*,vlong,int), void (*err)(char*),.br.B Dynsym *exports, int nexport, ulong maxsize).PP.Bvoid* dynimport(Dynobj *o, char *name, ulong sig).PP.Bvoid dynfreeimport(Dynobj *o).PP.Bvoid dynobjfree(Dynobj *o).PP.Bint dyntabsize(Dynsym *t).PP.Bextern Dynsym _exporttab[];.DT.SH DESCRIPTIONThese functions allow a process to load further code and datainto the currently executing image.A dynamically-loadable file, called a.I modulehere, is a variant of the.IR a.out (10.6)executable format with some extra components.The loader for the architecture(see.IR 2l (1))creates a module file from component object file(s) when given the.B -uoption.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 matchthe symbols in the module's import table..PPA symbol entry in a symbol table names a global function or data item, and has an associated.I signaturevalue representing the type of the corresponding function or data in the source code.The.B Dynsymstructure defines a symbol:.IP.EXtypedef struct { ulong sig; ulong addr; char* name;} Dynsym;.EE.PPThe structure is known to the loaders.IR 2l (1)..I Nameis the linkage name of the function or data..I Addris 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.I sigis the value produced by the C compiler's.B signofoperator applied to the type.Symbol tables must be sorted by.IR name ..PPAn executable that wishes to load modules will normally be linked using the.B -xoption to the appropriate loader.IR 2l (1).The resulting executable contains an export table.B _exporttabthat lists all the exported symbols of the program (by default, all external symbols).A nil name marks the end of the table.See.IR 2l (1)for details.The table can be given to the functions below to allow a loaded moduleto access those symbols..PPA loaded module is described by a.B Dynobjstructure:.IP.EXtypedef 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;.EE.PPSeveral fields give sizes of the module's components, as noted in comments above..I Basegives the address at which the module has been loaded.All its internalreferences have been adjusted where needed to reflect its current address..I Exportpoints to a symbol table listing the symbols exported by the module;.I nexportgives the table's length..I Importpoints to a list of symbols imported by the module;note that each entry actually points to an entry in a symbol tableprovided by the program that loaded the module (see below)..I Nimportgives the import table's length.If the import table is not required, call.I dynfreeimporton the module pointer to free it..PP.I Dynfindysmlooks up the entry for the given.I namein symbol table.I syms(of length.IR nsym ).It returns a pointer to the entry if found; nil otherwise.The symbol table must be sorted by name in ascending order..PP.I Dyntabsizereturns the length of symbol table.IR t ,defined to be the number of.B Dynsymvalues starting at.I tthat have non-nil.I namefields.It is used to find the length of.BR _exporttab ..PP.I Dynloadfdloads a module from the file open for reading on.IR fd ,and returns the resulting module pointer on success,or nil on error.If.I maxsizeis non-zerothe size of the dynamically-loaded module's code and datais limited to.I maxsizebytes..I Exportsis an array of.I nexportsymbols in the current program that can be imported by the current module.It uses.IR read (2)and.IR seek (2)to access.IR fd ,and calls.I werrstr(see.IR errstr (2))to set the error string if necessary..PP.I Dynloadgenis a more general function that can load a module from anarbitrary source, not just an open file descriptor.(In particular, it can becalled by the kernel using functions internal to the kernelinstead of making system calls.).IR Exports ,.I nexportand.I maxsizeare just as for.IR dynloadfd ..I Fileis a pointer to a structure defined by the caller that represents the filecontaining the module.It is passed to.I readand.IR seek ..I Readis invoked as.BI (*read)( file , buf ,\ \fInbytes\fP)\fR.\fP.I Readshould read.I nbytesof data from.I fileinto.I bufand return the number of bytes transferred.It should return -1 on error..I Seekis invoked as.BI (*seek)( file , n ,\ \fItype\fP)where.I nand.I typeare just as for.IR seek (2);it should seek to the requested offset in.IR file ,or return -1 on error..I Dynloadgenreturns a pointer to the loaded module on success.On error,it returns nil after calling its.I errparameter to set the error string..PP.I Dynimportreturns a pointer to the value of the symbol.I namein loaded module.IR o ,or.I nilif.I odoes not export a symbol with the given.IR name .If.I sigis non-zero, the exported symbol's signature must equal.IR sig ,or.I dynimportagain returns nil.For example:.IP.EXDev *d;d = dynimport(obj, "XXXdevtab", signof(*d));if(d == nil) error("not a dynamically-loadable driver");.EE.PP.I Dynobjfreefrees the module.IR o .There is no reference counting: it is the caller's responsibility to decide whethera module is no longer needed..SH SEE ALSO.IR 2l (10.1),.\".IR mach (2),.IR a.out (10.6).SH DIAGNOSTICSFunctions that return pointers return nil on error..I Dynloadfdsets the error string and returns nil.
.TH DYNLD 10.2
.SH NAME
dynfindsym, dynfreeimport, dynloadfd, dynloadgen, dynobjfree, dyntabsize \- load object file dynamically
.SH SYNOPSIS
.B #include <lib9.h>
.br
.B #include <a.out.h>
.br
.B #include <dynld.h>
.PP
.ta \w'\fLDynsym*** 'u
.B
Dynsym* dynfindsym(char *name, Dynsym *syms, int nsym)
.PP
.B
Dynobj* dynloadfd(int fd, Dynsym *exports, int nexport,
.br
.B
ulong maxsize)
.PP
.B
Dynobj* dynloadgen(void *file, long (*read)(void*,void*,long),
.br
.B
vlong (*seek)(void*,vlong,int), void (*err)(char*),
.br
.B
Dynsym *exports, int nexport, ulong maxsize)
.PP
.B
void* dynimport(Dynobj *o, char *name, ulong sig)
.PP
.B
void dynfreeimport(Dynobj *o)
.PP
.B
void dynobjfree(Dynobj *o)
.PP
.B
int dyntabsize(Dynsym *t)
.PP
.B
extern Dynsym _exporttab[];
.DT
.SH DESCRIPTION
These functions allow a process to load further code and data
into the currently executing image.
A dynamically-loadable file, called a
.I module
here, is a variant of the
.IR a.out (10.6)
executable format with some extra components.
The loader for the architecture
(see
.IR 2l (1))
creates a module file from component object file(s) when given the
.B -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.
.PP
A symbol entry in a symbol table names a global function or data item, and has an associated
.I signature
value representing the type of the corresponding function or data in the source code.
The
.B Dynsym
structure defines a symbol:
.IP
.EX
typedef struct {
ulong sig;
ulong addr;
char* name;
} Dynsym;
.EE
.PP
The structure is known to the loaders
.IR 2l (1).
.I Name
is the linkage name of the function or data.
.I 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
.I sig
is the value produced by the C compiler's
.B signof
operator applied to the type.
Symbol tables must be sorted by
.IR name .
.PP
An executable that wishes to load modules will normally be linked using the
.B -x
option to the appropriate loader
.IR 2l (1).
The resulting executable contains an export table
.B _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
.IR 2l (1)
for details.
The table can be given to the functions below to allow a loaded module
to access those symbols.
.PP
A loaded module is described by a
.B Dynobj
structure:
.IP
.EX
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;
.EE
.PP
Several fields give sizes of the module's components, as noted in comments above.
.I 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.
.I Export
points to a symbol table listing the symbols exported by the module;
.I nexport
gives the table's length.
.I 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 module (see below).
.I Nimport
gives the import table's length.
If the import table is not required, call
.I dynfreeimport
on the module pointer to free it.
.PP
.I Dynfindysm
looks up the entry for the given
.I name
in symbol table
.I syms
(of length
.IR nsym ).
It returns a pointer to the entry if found; nil otherwise.
The symbol table must be sorted by name in ascending order.
.PP
.I Dyntabsize
returns the length of symbol table
.IR t ,
defined to be the number of
.B Dynsym
values starting at
.I t
that have non-nil
.I name
fields.
It is used to find the length of
.BR _exporttab .
.PP
.I Dynloadfd
loads a module from the file open for reading on
.IR fd ,
and returns the resulting module pointer on success,
or nil on error.
If
.I maxsize
is non-zero
the size of the dynamically-loaded module's code and data
is limited to
.I maxsize
bytes.
.I Exports
is an array of
.I nexport
symbols in the current program that can be imported by the current module.
It uses
.IR read (2)
and
.IR seek (2)
to access
.IR fd ,
and calls
.I werrstr
(see
.IR errstr (2))
to set the error string if necessary.
.PP
.I 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 functions internal to the kernel
instead of making system calls.)
.IR Exports ,
.I nexport
and
.I maxsize
are just as for
.IR dynloadfd .
.I File
is a pointer to a structure defined by the caller that represents the file
containing the module.
It is passed to
.I read
and
.IR seek .
.I Read
is invoked as
.BI (*read)( file , buf ,\ \fInbytes\fP)\fR.\fP
.I Read
should read
.I nbytes
of data from
.I file
into
.I buf
and return the number of bytes transferred.
It should return -1 on error.
.I Seek
is invoked as
.BI (*seek)( file , n ,\ \fItype\fP)
where
.I n
and
.I type
are just as for
.IR seek (2);
it should seek to the requested offset in
.IR file ,
or return -1 on error.
.I Dynloadgen
returns a pointer to the loaded module on success.
On error,
it returns nil after calling its
.I err
parameter to set the error string.
.PP
.I Dynimport
returns a pointer to the value of the symbol
.I name
in loaded module
.IR o ,
or
.I nil
if
.I o
does not export a symbol with the given
.IR name .
If
.I sig
is non-zero, the exported symbol's signature must equal
.IR sig ,
or
.I dynimport
again returns nil.
For example:
.IP
.EX
Dev *d;
d = dynimport(obj, "XXXdevtab", signof(*d));
if(d == nil)
error("not a dynamically-loadable driver");
.EE
.PP
.I Dynobjfree
frees the module
.IR o .
There is no reference counting: it is the caller's responsibility to decide whether
a module is no longer needed.
.SH SEE ALSO
.IR 2l (10.1),
.\".IR mach (2),
.IR a.out (10.6)
.SH DIAGNOSTICS
Functions that return pointers return nil on error.
.I Dynloadfd
sets the error string and returns nil.