README.md

   1 centaur
   2 =======
   3
   4 centaur is an ELF executable editing toolkit, focusing on code
   5 injection and function detouring.
   6
   7
   8 Example
   9 -------
  10
  11 Injecting an object file into a program and detouring a function
  12 could hardly be simpler:
  13
  14     elfucli --input program \
  15             --reladd objfile.o \
  16             --detour oldfunc,newfunc \
  17             --output program_modified
  18
  19 elfucli parses the command line parameters one by one like a script.
  20
  21 In this example, it:
  22
  23   1. Loads the executable `program` containing the function `oldfunc`.
  24   2. Injects an object file containing the function `newfunc`.
  25   3. Overwrites the beginning of `oldfunc` with a jump to `newfunc`.
  26   4. Writes the modified program to `program_modified`.
  27
  28 This functionality is exposed by the underlying `libelfu` via a C API,
  29 at the same high level. `elfucli` serves as an example application for
  30 it and doubles as a handy scalpel for ELF files.
  31
  32 More examples can be found in the testsuite. The 'detour' test is
  33 particularly similar to the example above.
  34
  35
  36 Build instructions, testing
  37 ---------------------------
  38
  39 Usually, a plain
  40
  41     make
  42
  43 should be enough to build centaur, provided that a version of libelf
  44 and its development files are installed. If not, see docs/building.md
  45 for further hints such as the packages to be installed on Ubuntu.
  46
  47 Once that is done,
  48
  49     make check
  50
  51 will build and run the testsuite. See docs/tests.md for details.
  52
  53
  54 License, etc
  55 ------------
  56
  57 See the docs/ directory for all other documentation.