home *** CD-ROM | disk | FTP | other *** search
/ Usenet 1994 January / usenetsourcesnewsgroupsinfomagicjanuary1994.iso / sources / unix / volume14 / bsd-dyna-link / dyna_link.doc < prev    next >
Encoding:
Text File  |  1988-05-08  |  4.3 KB  |  125 lines
  1.    #include <a.out.h>
  2.    #include "assoc.h"
  3.    #include "dyna_link.h
  4.    
  5.    
  6.    lk_get_header(fd, hdrp, offset)  /@ reads an a.out header into memory @/
  7.       int fd;               /@ an open file-descriptor @/
  8.       struct exec *hdrp;    /@ pointer to memory for a.out header @/
  9.       long offset;          /@ displacement of file (for archives)@/
  10.  
  11.    lk_get_symbols(fd, hdrp, offset)  /@ Reads symbols into memory @/
  12.       int fd;               /@ an open file-descriptor @/
  13.       struct exec *hdrp;    /@ pointer to previously initialized header @/
  14.       long offset;          /@ displacement of file (for archives) @/
  15.  
  16.    assoc_mem
  17.    lk_sym_hash(hdrp, syms); /@ Creates lookup-table for symbols @/
  18.       struct exec *hdrp;    /@ pointer to previously initialized header @/
  19.       struct nlist *syms;   /@ pointer to previously initialized symbols @/
  20.  
  21.    func_ptr 
  22.    lk_dynaload(codep, hdrp, hash_table, filename) /@ loads named file @/
  23.       int* codep;           /@ pointer to memory for return-code @/
  24.       struct exec* hdrp;    /@ pointer to previously initialized header @/
  25.       assoc_mem hash_table; /@ previously initialized lookup-table @/
  26.       char* filename;
  27.  
  28.    func_ptr  /@ loads a file, given by file-descriptor and offset. @/
  29.    lk_dynaload_fd(codep, hdrp, hash_tab, fd, offset)
  30.      int *codep;            /@ pointer to memory for return-code @/
  31.      struct exec *hdrp;     /@ pointer to previously initialized header @/
  32.      assoc_mem hash_tab;    /@ previously initialized lookup-table @/
  33.      int fd;                /@ an open file-descriptor @/
  34.      long disp;             /@ displacement of file (for archives) @/
  35.  
  36.    This library furnishes routines for doing a dynamic load of an executable
  37.    segment ( .o file).
  38.  
  39.    The caller first must build a lookup-table for the symbols
  40.    of the executing program.  (See assoc.doc for description
  41.    of lookup-table routines.)
  42.  
  43.    Once the lookup-table has been made, the program may repeatedly call
  44.    lk_dynaload() or lk_dynaload_fd() to load segments.
  45.    Loaded segments may be freed using free().
  46.  
  47.    The routines to be used for building the lookup-table are
  48.    lk_get_header(), lk_get_symbols(), and lk_sym_hash().  These are
  49.    also potentially useful for other link-editor applications, and
  50.    for that reason are parameterized so that they may be used on
  51.    archive members, as well as on individual a.out files.
  52.  
  53.    lk_get_header() returns 0 on success, -1 on failure.  Sets errno.
  54.  
  55.    lk_get_symbols() returns a buffer from malloc() on success, null
  56.      on failure.  Sets errno.
  57.  
  58.    lk_sym_hash() returns an assoc_mem on success (see assoc.doc), null
  59.      on failure.  Sets errno.
  60.  
  61.    lk_dynaload() and lk_dynaload_fd() return a pointer to the entry-point
  62.      of the .o file on success, null on failure.  Sets *codep (see
  63.      parameters).  The values for *codep are defined in dyna_link.h:
  64.  
  65.       #define lk_ok 0
  66.       #define lk_undefd 1
  67.       #define lk_bad_format 2
  68.       #define lk_perror -1
  69.  
  70.    lk_ok means "okay."
  71.    lk_undefd means that one or more symbols required by the .o file
  72.      are not defined in the lookup-table.  In this case the char
  73.      lk_undefined will have been set to point to a vector containing
  74.      the undefined symbols.
  75.    lk_bad_format means that the .o file is not formatted occording
  76.      to the a.out file conventions.
  77.    lk_perror means that errno has been set.
  78.  
  79.   
  80.    Tutorial example:
  81.  
  82.    main(argc, argv)
  83.      char argv;
  84.    {
  85.      char* me = (char*) (argv[0]);
  86.      char* prog = (char*)(argv[1]);
  87.      func_ptr entry_point;
  88.      assoc_mem hash_tab;
  89.      struct exec main_hdr;
  90.      struct nlist * main_syms;
  91.      int code;
  92.      int fd = open( me, O_RDONLY );
  93.    
  94.      lk_get_header(fd, &main_hdr, 0 );
  95.      main_syms = lk_get_symbols(fd, &main_hdr, 0 );
  96.      close(fd);
  97.      hash_tab = lk_sym_hash(&main_hdr, main_syms);
  98.    
  99.      (func_ptr) entry_point
  100.           = lk_dynaload( &code, &main_hdr, hash_tab, prog );
  101.      if(entry_point)
  102.        (*(func_ptr) entry_point)();
  103.      else
  104.         switch(code)
  105.            {
  106.            case lk_undefd:
  107.              { char undef = lk_undefined;
  108.            printf("undefined:\n");
  109.            while(*undef) printf("%s\n", *undef++);
  110.              }
  111.              break;
  112.            case lk_perror:
  113.              perror(prog);
  114.              break;
  115.            case lk_bad_format:
  116.              printf("bad format\n");
  117.              break;
  118.            }
  119.          }
  120.      }
  121.      exit(0);
  122.    }
  123.    
  124. */
  125.