README

   1 Usage
   2 -----
   3
   4 Provide `/usr/lib/libobjid.so' to the list of libraries in `LD_PRELOAD':
   5   LD_PRELOAD=/usr/lib/libobjid.so programname programarguments
   6
   7 It will extend the stored core file info in the case the program segfaults.
   8 In this case you can check it got activated by its STDERR message:
   9   libobjid: core
  10
  11 You need patched GDB and its --objectdirectory option to use the location info.
  12 Copy all the shared libraries used by the program to a common storage directory
  13 and invoke gdb as:
  14   gdb --objectdirectory=storage/directory --core=path/to/core.xyz
  15
  16 You should keep the original filenames and store them only to different
  17 directories, according to their version.  Be sure to also store the debuginfo
  18 files along:
  19   /path/to/libc.so.6
  20   /path/to/libc.so.6.debug
  21
  22 More debug info during segfault can be seen by setting the `LIBOBJID' level:
  23
  24   LIBOBJID=9 LD_PRELOAD=/usr/lib/libobjid.so programname programarguments
  25
  26
  27 Limitations
  28 -----------
  29
  30 The code currently does not undo any relocations.  Any (ineffective) non-PIC
  31 shared libraries will not be located by libobjid.
  32
  33 Non-PIE executable files are loaded at their compiled location - OK.
  34 PIC shared libraries do not use any relocations in their readonly sections - OK.
  35 x86_64 fails to load non-PIC shared libraries during tests - N/A.
  36 i386 permits running non-PIC shared libraries - FAIL but these are ineffective.
  37
  38
  39 Implementation Principle
  40 ------------------------
  41
  42 During SIGSEGV handling dl_iterate_phdr() is used to iterate program headers
  43 and the readonly sections get checksummed and stored to a newly mapped
  44 PAGE_SIZE-based memory being identified by its magic header.
  45
  46 Stored information structure can be found in "objid.h".
  47
  48 Unfortunately it cannot be linked to existing ELF structures as locating them
  49 requires the pages of the original executable binary which we try identify and
  50 find by them.
  51 The original executable's shared libraries list can be found from its
  52 program header DYNAMIC / section .dynamic - DT_NEEDED tag.
  53 While this section is located in writable memory stored in the core file the
  54 program headers / section headers table is in the executable read only pages
  55 not present in the core file.
  56
  57
  58 Implementation Invocation
  59 -------------------------
  60
  61 Currently the code binary-patches (after mprotect (PROT_WRITE)) glibc itself as
  62 it does not provide PLT to replace its `__sigaction' function being called by
  63 `__signal' and many others.
  64 It is currently the only architecture-dependent part of libobjid now.
  65
  66 Later with available `__sigaction' glibc PLT entry one would still need to
  67 `LD_PRELOAD=/usr/lib/libobjid.so'.  With integrating this library to Red Hat
  68 glibc it would apply to all the binaries except the ones statically built on
  69 non-libobjid glibc systems.  But statically built binaries do not need any
  70 libobjid functionality so it makes no problem.
  71
  72
  73 Proper Reimplementation
  74 -----------------------
  75
  76 Linux kernel should core dump the page(s) containing original executable's
  77 program headers, the page(s) containing its `DYNAMIC' segment and according to
  78 its `DT_GNU_LIBLIST' and `DT_GNU_LIBLISTSZ' also the page(s) containing its
  79 `.gnu.liblist' section.
  80
  81 prelink(8) should provide DYNAMIC's `DT_CHECKSUM' field even for executables.
  82
  83 GDB would be afterwards able locate `AUXVEC->AT_PHDR->DYNAMIC->DT_CHECKSUM' for
  84 the main executable checksum and `AUXVEC->AT_PHDR->DYNAMIC->DT_GNU_LIBLIST' for
  85 the list of the needed libraries identified by its `l_checksum' field.
  86
  87 Only the executables/libraries properly prelink(8)ed together would be
  88 identifiable by GDB.
  89
  90
  91 $Id$