Skip to content
GOTCHA is a library for wrapping function calls in shared libraries
C C++ CMake Other
Branch: develop
Clone or download
Latest commit c322e7a Aug 9, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
cmake Install a gotcha-config.cmake and gotcha-config-version.cmake Jun 14, 2018
docs More doc fixes Jun 14, 2018
src Handled corner type errors Jun 13, 2018
test Fixed up hammer test Jun 13, 2018
.gitignore Updated gitignore to allow for checkson whether working dir is functi… May 24, 2017
.travis.yml Travis is being weird, triggering a build again. Formatted travis.yml Jun 13, 2018
CMakeLists.txt Install a gotcha-config.cmake and gotcha-config-version.cmake Jun 14, 2018
COPYRIGHT Added copyright notice where necessary May 4, 2017
LGPL Commit with Doxygen and Copyright and headers Apr 3, 2017 Updated to reflect new organization Jul 11, 2019
codecov.yml Removed tracking of tests from coverage statistics May 18, 2017

GOTCHA v1.0.2

Build Status Coverage

Gotcha is a library that wraps functions. Tools can use gotcha to install hooks into other libraries, for example putting a wrapper function around libc's malloc.
It is similar to LD_PRELOAD, but operates via a programmable API. This enables easy methods of accomplishing tasks like code instrumentation or wholesale replacement of mechanisms in programs without disrupting their source code.

Quick Start

Building Gotcha is trivial. In the root directory of the repo

mkdir build
cd build
cmake -DCMAKE_INSTALL_PREFIX=<where you want to install GOTCHA> ../
make install

Usage is fairly simple. For us to wrap a function, we need to know its name, what you want it wrapped with (the wrapper), and we need to give you some ability to call the function you wrapped (wrappee). Gotcha works on triplets containing this information. We have small sample uses, but the standard workflow looks like

  #include <gotcha/gotcha.h>
  static gotcha_wrappee_t wrappee_puts_handle;
  static int puts_wrapper(const char* str); //this is the declaration of your wrapper
  static gotcha_wrappee_t wrappee_fputs_handle;
  static int fputs_wrapper(const char* str, FILE* f);
  struct gotcha_binding_t wrap_actions [] = {
    { "puts", puts_wrapper, &wrappee_puts_handle },
    { "fputs", fputs_wrapper, &wrappee_fputs_handle },
  int init_mytool(){
    gotcha_wrap(wrap_actions, sizeof(wrap_actions)/sizeof(struct gotcha_binding_t), "my_tool_name");
  static int fputs_wrapper(const char* str, FILE* f){
    // insert clever tool logic here
    typeof(&fputs_wrapper) wrappee_fputs = gotcha_get_wrappee(wrappee_fputs_handle); // get my wrappee from Gotcha
    return wrappee_fputs(str, f); //wrappee_fputs was directed to the original fputs by gotcha_wrap

Building your tool changes little, you just need to add the prefix you installed Gotcha to your include directories, the location the library was installed (default is <that_prefix>/lib) to your library search directories (-L...), and link (-lgotcha) with your tool. Very often this becomes "add -lgotcha to your link line," and nicer CMake integration is coming down the pipe.

A more advanced example can be seen in the GOTCHA-tracer project. This example shows how to implement a simple tracer with GOTCHA, including linking to GOTCHA through CMake and testing GOTCHA through direct invocation and using LD_PRELOAD.

That should represent all the work your application needs to do to use Gotcha.


The license is LGPL.

Primary contact/Lead developer

Matt Legendre (

You can’t perform that action at this time.