kld man page on OpenDarwin

Man page or keyword search:  
man Server   3202 pages
apropos Keyword Search (all sections)
Output format
OpenDarwin logo
[printable version]

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 ker‐
       nel  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 provided 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 speci‐
       fied by object_filename or memory pointed to by	obj_addr  respectively
       to the base file that was previous loaded with a call to kld_load_base‐
       file or kld_load_basefile_from_memory.

       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
       -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 exam‐
       ple), 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 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 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 out‐
       put_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_base‐
       file_from_memory is an alternate interface 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  pro‐
       gram  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  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.	  kld_address_func  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.

       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_memory()

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 sym‐
       bols.   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)
[top]

List of man pages available for OpenDarwin

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
...................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net