Unix/Linux Go Back    


OpenDarwin 7.2.1 - man page for kld (opendarwin section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


KLD(3)											   KLD(3)

NAME
       kld_load,    kld_load_from_memory,    kld_lookup,    kld_forget_symbol,	  kld_unload_all,
       kld_load_basefile, kld_load_basefile_from_memory, kld_address_func, kld_set_link_options -
       programmatically link edit and load driver object files

SYNOPSIS
       #include <kld.h>

       #ifdef __DYNAMIC__
       __private_extern__ long kld_load_basefile(
	    const char *base_filename);

       __private_extern__ long kld_load(
	    struct mach_header **header_addr,
	    const char *object_filename,
	    const char *output_filename);

       __private_extern__ long kld_load_from_memory(
	    struct mach_header **header_addr,
	    const char *object_name,
	    char *object_addr,
	    long object_size,
	    const char *output_filename);
       #endif /* __DYNAMIC__ */

       #ifdef __STATIC__
       __private_extern__ long kld_load_from_memory(
	    struct mach_header **header_addr,
	    const char *object_name,
	    char *object_addr,
	    long *object_size);
       #endif /* __STATIC__ */

       __private_extern__ long kld_load_basefile_from_memory(
	    const char *base_filename,
	    char *base_addr,
	    long base_size);

       __private_extern__ long kld_lookup(
	    const char *symbol_name,
	    unsigned long *value);

       __private_extern__ long kld_forget_symbol(
	    const char *symbol_name);

       __private_extern__ long kld_unload_all(
	    long deallocate_sets);

       __private_extern__ void kld_address_func(
	    unsigned long (*func)(unsigned long size, unsigned long headers_size));

       #define KLD_STRIP_ALL	0x00000000
       #define KLD_STRIP_NONE	0x00000001

       __private_extern__ void kld_set_link_options(
	   unsigned long link_options);

DESCRIPTION
       The kld package is designed for loading kernel drivers both by the kernel for loading boot
       drivers and kmodload for loading other drivers.	The library that contains the kld package
       is  linked  with  the -lkld linker flag.  For the kernel when linked with the -static flag
       the -lkld linker flag will link the library libkld.a.  And for kmodload when  linked  with
       the -dynamic flag the -lkld linker flag will link the library libkld.dylib.

       For  the  kernel the kld_load_basefile_from_memory, and kld_load_from_memory APIs are pro-
       vided in the library libkld.a compiled with the -static compiler flag.  Using this library
       one must define the following variable:
	    extern char *kld_basefile_name;
       which is the the name of the base file used for error messages.

       For   kmodload	the   kld_load_basefile,   kld_load_basefile_from_memory,  kld_load,  and
       kld_load_from_memory APIs are provided in  the  library	libkld.dylib  compiled	with  the
       -dynamic compiler flag.

       kld_load  or  kld_load_from_memory link edits and loads the file specified by object_file-
       name or memory pointed to by obj_addr respectively to the  base	file  that  was  previous
       loaded with a call to kld_load_basefile or kld_load_basefile_from_memory.

       If  the	program, in this case the kernel, is to allow the loaded object files to use sym-
       bols from itself, it must be built with the -seglinkedit 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 -s filename option  to  strip(1).   For
       the routines described here, only global symbols are used, so local symbols can be removed
       with the -x 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  kld_load_from_memory  or
       kld_load_basefile.  (This is true of the first call in the program, as well as  the  first
       call  after  an	invocation of kld_unload_all).	The first call to kld_load_from_memory or
       kld_load_basefile must go through all the symbols of the program or basefile,  so  if  the
       program	has  been  compiled  for debugging (for example), it can take orders of magnitude
       longer.

       Since the objects loaded with kld_load or kld_load_from_memory 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 -all_load option
       to ld(1) when building the executable.  This will copy all the library code into the  exe-
       cutable.

       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 supplied routine will be called:
	    extern void kld_error_vprintf(const char *format, va_list ap);

       If  the	link  editing  and  loading  is successful, the address of the header of what was
       loaded is returned through the pointer header_addr (if it isn't	NULL).	 If  kld_load  is
       successful and the parameter output_filename 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 kld_load function returns 1 for success and 0 for failure.
       If a fatal system error (out of memory, etc.) occurs, all future calls to kld_load and the
       other routines described here will fail.

       kld_load_from_memory()  is  similar to kld_load(), but works on memory rather than a file.
       The argument object_name is the name associated with the memory and is used for	messages.
       (It  must  not  be NULL.) The arguments object_addr and object_size are the memory address
       and size of the object file.  kld_load_from_memory() only allows one thin object file (not
       an archive or ``fat'' file) to be loaded.

       kld_lookup()  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 kld_error_vprintf routine (For kld_lookup, only
       internal errors can result.)

       kld_forget_symbol() 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 kld_error_vprintf routine (For  this  routine,  only
       internal errors can result.)

       kld_unload_all()  clears out all allocated data structures used by these routines.  If the
       parameter deallocate_sets is non-zero, the function also unloads  all  objects  that  were
       loaded.	 If  deallocate_sets 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  kld_unload_all  call  between	calls  to
       kld_load  allows  the  objects to be loaded without fear of global symbol names' clashing.
       kld_unload_all returns 1 if it is successful and 0 otherwise.  If any  errors  occur  also
       calls the user supplied kld_error_vprintf routine.

       The  argument  to  kld_load_basefile specifies a base file, whose symbol table is taken as
       the basis for subsequent kld_load's.  kld_load_basefile_from_memory is an alternate inter-
       face  that  allows  mapped  ``thin'' object image to be specified rather than a file.  The
       base file may be a ``fat'' file, and must contain an architecture that  would  execute  on
       the host; otherwise, it is an error.  If the file is a fat file, the ``best'' architecture
       (as defined by  what  the  kernel  exec(2)  would  select)  is  used  as  the  base  file.
       kld_load_basefile  must	be invoked before any call to kld_load.  Alternatively, it can be
       called after kld_unload_all, 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 base_filename contains  the  symbol  table  of  the  target  program.   The  routine
       kld_address_func, described next, would also be used.

       kld_address_func  is  passed  a	pointer  to  a	function,  func, that will be called from
       kld_load.  The parameter values that kld_load will supply to func are the size of the mem-
       ory  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.  kld_address_func is intended to be used
       when a program is dynamically loading objects into a program other than itself; the  func-
       tion allows it to pick the place in the address space of the target program.

       kld_set_link_options  is  passed a mask of options, link_options, that are used to control
       some aspects of the following kld_load operations. Passing KLD_STRIP_NONE  will	stop  kld
       from  stripping	symbols from the output in all cases. By default all symbols are stripped
       for kernel loads and when output_filename is NULL for  kld_load()  and  kld_load_from_mem-
       ory()

FAT FILE SUPPORT
       All  functions  that accept object files or archives also accept ``fat'' files, except for
       the restrictions noted above for kld_load_from_memory and kld_load_basefile.

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

BUGS
       There exists one semantic link edit problem with respect to common symbols.  If an  object
       file  is  loaded that has common symbols left after the symbols have been merged, kld_load
       has to allocate storage for these symbols for the code to run without error.  The  problem
       occurs  if, on a later call to kld_load, one of the common symbols that kld_load allocated
       appears in an object file as a defining symbol (not a common  or  undefined  symbol).   In
       this  case,  kld_load  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.			   May 28, 2003 				   KLD(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 02:20 PM.