README.md

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