KLD(3) KLD(3)

NAME
       kldload,    kldloadfrommemory,    kldlookup,    kldforgetsymbol,
       kldunloadall,    kldloadbasefile,    kldloadbasefilefrommemory,
       kldaddressfunc, kldsetlinkoptions - programmatically link edit and
       load driver object files

SYNOPSIS
       #include 

       #ifdef DYNAMIC
       privateextern long kldloadbasefile(
            const char *basefilename);

       privateextern long kldload(
            struct machheader **headeraddr,
            const char *objectfilename,
            const char *outputfilename);

       privateextern long kldloadfrommemory(
            struct machheader **headeraddr,
            const char *objectname,
            char *objectaddr,
            long objectsize,
            const char *outputfilename);
       #endif /* DYNAMIC */

       #ifdef STATIC
       privateextern long kldloadfrommemory(
            struct machheader **headeraddr,
            const char *objectname,
            char *objectaddr,
            long *objectsize);
       #endif /* STATIC */

       privateextern long kldloadbasefilefrommemory(
            const char *basefilename,
            char *baseaddr,
            long basesize);

       privateextern long kldlookup(
            const char *symbolname,
            unsigned long *value);

       privateextern long kldforgetsymbol(
            const char *symbolname);

       privateextern long kldunloadall(
            long deallocatesets);

       privateextern void kldaddressfunc(
            unsigned long (*func)(unsigned long size, unsigned long headerssize));

       #define KLDSTRIPALL    0x00000000
       #define KLDSTRIPNONE   0x00000001

       privateextern void kldsetlinkoptions(
           unsigned long linkoptions);

DESCRIPTION
       The kld package is designed for loading kernel drivers both by the ker-
       nel  for  loading  boot drivers and kextload for loading other drivers.
       The library that contains the kld package  is  linked  with  the  -llkld
       linker  flag.   For  the  kernel  when linked with the -ssttaattiicc flag the
       -llkld linker flag will link the library  libkld.a.   And  for  kextload
       when  linked with the -ddyynnaammiicc flag the -llkld linker flag will link the
       library libkld.dylib.

       For    the    kernel     the     kldloadbasefilefrommemory,     and
       kldloadfrommemory APIs are provided in the library libkld.a compiled
       with the -ssttaattiicc compiler flag.  Using this library one must define the
       following variable:
            extern char *kldbasefilename;
       which is the the name of the base file used for error messages.


       For   kextload  the  kldloadbasefile,  kldloadbasefilefrommemory,
       kldload, and kldloadfrommemory APIs are  provided  in  the  library
       libkld.dylib compiled with the -ddyynnaammiicc compiler flag.

       kldload  or  kldloadfrommemory link edits and loads the file speci-
       fied by objectfilename or memory pointed to by  objaddr  respectively
       to the base file that was previous loaded with a call to kldloadbase-
       file or kldloadbasefilefrommemory.

       If the program, in this case the kernel, is to allow the loaded  object
       files   to  use  symbols  from  itself,  it  must  be  built  with  the
       -sseegglliinnkkeeddiitt option of the link editor, ld(1), in  order  to  have  its
       symbol table mapped into memory.

       The  symbol  table may be trimmed to limit which symbols are allowed to
       be referenced by loaded objects.  This can be accomplished with the  -ss
       ffiilleennaammee  option  to  strip(1).   For the routines described here, only
       global symbols are used, so local symbols can be removed  with  the  -xx
       option to ld(1) or strip(1).  Doing so saves space in the final program
       and  vastly  decreases  the  time  spent   by   the   first   call   to
       kldloadfrommemory  or kldloadbasefile.  (This is true of the first
       call in the program, as well as the first call after an  invocation  of
       kldunloadall).    The   first   call   to   kldloadfrommemory   or
       kldloadbasefile must go through all the symbols  of  the  program  or
       basefile,  so if the program has been compiled for debugging (for exam-
       ple), it can take orders of magnitude longer.

       Since the objects loaded with kldload or kldloadfrommemory can only
       use  symbols that appear in the executable program, if the program uses
       a library and wants to make all the symbols in that  library  available
       to  the  loaded  objects, it must force all of the library symbols into
       the executable.  This can be done for all libraries with the  -aallllllooaadd
       option  to  ld(1) when building the executable.  This will copy all the
       library code into the executable.


       The object file being loaded will only be successful if  there  are  no
       link  edit  errors  (undefined symbols, etc.).  If an error occurs, the
       object file is unloaded automatically.  If errors occur the  user  sup-
       plied routine will be called:
            extern void klderrorvprintf(const char *format, valist ap);

       If  the  link  editing  and  loading  is successful, the address of the
       header of what was loaded is returned through the  pointer  headeraddr
       (if  it  isn't NULL).  If kldload is successful and the parameter out-
       putfilename isn't NULL, an object file is written  to  that  filename.
       This  file  can  be  used with the gdb(1) add-file command to debug the
       code in the dynamically loaded object.  The kldload function returns 1
       for success and 0 for failure.  If a fatal system error (out of memory,
       etc.) occurs, all future calls  to  kldload  and  the  other  routines
       described here will fail.

       kldloadfrommemory()  is  similar  to kldload(), but works on memory
       rather than a file.  The argument objectname is  the  name  associated
       with  the  memory and is used for messages.  (It must not be NULL.) The
       arguments objectaddr and objectsize are the memory address  and  size
       of the object file.  kldloadfrommemory() only allows one thin object
       file (not an archive or ``universal'' file) to be loaded.

       kldlookup() looks up the specified symbol name and returns  its  value
       indirectly  through  the  pointer  value.  It returns 1 if it finds the
       symbol, and 0 otherwise.  If any errors occur it also  calls  the  user
       supplied  klderrorvprintf  routine  (For  kldlookup,  only  internal
       errors can result.)

       kldforgetsymbol() causes this package to forget the existence of  the
       specified  symbol  name.   This  allows  a new object to be loaded that
       defines this symbol.  All objects loaded before this call will continue
       to  use  the  value  of the symbol in effect at the time the object was
       loaded.  It returns 1 if it finds the symbol and 0 otherwise.   If  any
       errors  occur it also calls the user supplied klderrorvprintf routine
       (For this routine, only internal errors can result.)

       kldunloadall() clears out all allocated data structures used by these
       routines.   If  the parameter deallocatesets is non-zero, the function
       also unloads all objects that were loaded.  If deallocatesets is  zero
       the  object  sets  aren't unloaded, and the program can continue to use
       the code and data loaded.   However,  further  calls  to  the  routines
       described  here will no longer know about the symbols in those objects.
       If objects aren't to be allowed access  to  each  other's  symbols,  an
       kldunloadall  call between calls to kldload allows the objects to be
       loaded without fear of global symbol names'  clashing.   kldunloadall
       returns  1  if  it  is successful and 0 otherwise.  If any errors occur
       also calls the user supplied klderrorvprintf routine.

       The argument to kldloadbasefile specifies a base file,  whose  symbol
       table  is taken as the basis for subsequent kldload's.  kldloadbase-
       filefrommemory is an alternate interface that allows mapped  ``thin''
       object  image to be specified rather than a file.  The base file may be
       a ``universal'' file, and must contain an architecture that would  exe-
       cute  on the host; otherwise, it is an error.  If the file is a univer-
       sal file, the ``best'' architecture (as  defined  by  what  the  kernel
       exec(2) would select) is used as the base file.  kldloadbasefile must
       be invoked before any call  to  kldload.   Alternatively,  it  can  be
       called after kldunloadall, which unloads the base file.  This call is
       intended to be used when a program is dynamically loading  object  sets
       into a program other than itself, where basefilename contains the sym-
       bol  table  of  the  target  program.   The  routine  kldaddressfunc,
       described next, would also be used.

       kldaddressfunc  is passed a pointer to a function, func, that will be
       called from kldload.  The parameter values that kldload  will  supply
       to  func  are  the  size  of  the  memory required for the object being
       loaded, and the size of the headers (which are  also  included  in  the
       calculation of size).  The function specified by func should return the
       address where the output is to be  link  edited.   kldaddressfunc  is
       intended  to be used when a program is dynamically loading objects into
       a program other than itself; the function allows it to pick  the  place
       in the address space of the target program.

       kldsetlinkoptions  is  passed  a mask of options, linkoptions, that
       are used to control some aspects of the following kldload  operations.
       Passing  KLDSTRIPNONE  will  stop kld from stripping symbols from the
       output in all cases. By default all symbols  are  stripped  for  kernel
       loads   and   when   outputfilename   is   NULL   for  kldload()  and
       kldloadfrommemory()


UUNNIIVVEERRSSAALL FFIILLEE SSUUPPPPOORRTT
       All functions that accept object files or archives also  accept  ``uni-
       versal''   files,   except   for   the  restrictions  noted  above  for
       kldloadfrommemory and kldloadbasefile.


SEE ALSO
       ld(1), strip(1), gdb(1)


BUGS
       There exists one semantic link edit problem with respect to common sym-
       bols.   If  an object file is loaded that has common symbols left after
       the symbols have been merged, kldload  has  to  allocate  storage  for
       these  symbols  for  the code to run without error.  The problem occurs
       if, on a later call  to  kldload,  one  of  the  common  symbols  that
       kldload  allocated appears in an object file as a defining symbol (not
       a common or undefined symbol).  In this case, kldload will report  the
       symbol  as  being  multiply  defined.   However, if this combination of
       object files were statically linked, no error would occur.



Apple Computer, Inc.             July 28, 2005                          KLD(3)