What is Antithesis? How we’re different Problems we solve Security approach Demo Fintech Customer stories Working with Antithesis Contact us Backstory Leadership Careers Brand

C/C++ Instrumentation

Prerequisites

Instrumentation for C and C++ is packaged with the C++ SDK. Instrumentation is supported by the header file antithesis_instrumentation.h. This file must be included in one, and only one translation unit at link time. Coverage instrumentation requires Clang 13 or higher, and either C++ 11 or higher or C89 or higher.

We recommended that you include the instrumentation header in the file where you define the main function, as follows:

#include "antithesis_instrumentation.h"

If you are unable to meet the requirements of our C/C++ instrumentation, perhaps because you use an older version of Clang or are unable to include a header file, then you can try our legacy instrumentation approach. This approach does not require a modern Clang or a header file, but it will instead require you to provide a shared object at link-time.

Build Requirements

Your instrumented binary must be built with libraries and dependencies that it will use at runtime.

Add the following compile flag:

-fsanitize-coverage=trace-pc-guard -g

And add the following link flag:

--build-id

LLVM-instrumented binaries must have GNU build ids for symbolization to work. As long as you use the --build-id link flag above, you’ll be fine.

If your build process includes a single compile/link step, then add both compile and link flags with the following:

-fsanitize-coverage=trace-pc-guard -g -Wl,--build-id

We recommend the use of -g but it is not necessary. It will provide more detailed information when bugs are found, which may make debugging easier.

Validation

To confirm that the instrumentation process was successful, you can run the command nm to list all the symbols in a binary, and then grep the string “antithesis_load_libvoidstar”.

$ nm client_binary | grep "antithesis_load_libvoidstar"
T antithesis_load_libvoidstar

Notice the “T” character in the previous code block: it means the symbol is in the text (code) section.

If this does not work you probably failed to include the header file.

Symbolization

The LLVM compiler infrastructure will output debug symbols in the DWARF format. They could be separate debug info or just the original unstripped binary. These files should be symlinked (or moved) into a directory named /symbols in the root of the appropriate container image.

Help

Contact us if you need help with this.

  • Introduction
  • How Antithesis Works
  • Tutorial
  • Testing with Antithesis
  • Build and run an etcd cluster
  • Meet the Test Composer
  • User manual
  • Setup guide
  • Properties and Assertions
  • Properties in Antithesis
  • Assertions in Antithesis
  • Sometimes Assertions
  • Properties to Test For
  • Test Composer
  • Test Composer Basics
  • Test Composer Reference
  • Principles of Test Composition
  • Checking Test Templates Locally
  • Webhooks
  • Launching a test
  • Retrieving logs
  • Launching a debugging session
  • Webhook API
  • Reports
  • The triage report
  • Findings
  • Environment
  • Utilization
  • Properties
  • The bug report
  • Context, Instance, & Logs
  • Bug likelihood over time
  • Statistical debug information
  • Multiverse debugging
  • Overview
  • Exploring the multiverse
  • Querying with event sets
  • The Environment and its utilities
  • Using the Antithesis Notebook
  • Cookbook
  • The Environment and Multiverse
  • The Antithesis Environment
  • Fault Injection
  • CPUID
  • Reference
  • Handling External Dependencies
  • SDK reference
  • Go
  • Tutorial
  • Instrumentor
  • Assert (reference)
  • Lifecycle (reference)
  • Random (reference)
  • Java
  • Tutorial
  • Instrumentation
  • Assert (reference)
  • Lifecycle (reference)
  • Random (reference)
  • C
  • C++
  • Tutorial
  • C/C++ Instrumentation
  • Assert (reference)
  • Lifecycle (reference)
  • Random (reference)
  • JavaScript
  • Python
  • Tutorial
  • Assert (reference)
  • Lifecycle (reference)
  • Random (reference)
  • Rust
  • Tutorial
  • Instrumentation
  • Assert (reference)
  • Lifecycle (reference)
  • Random (reference)
  • .NET
  • Languages not listed above
  • Assert (reference)
  • Lifecycle (reference)
  • Tooling integrations
  • CI integration
  • Discord and Slack integrations
  • Configuring Antithesis
  • Instrumentation
  • User management
  • Sizing your deployment
  • Best practices
  • Docker best practices
  • Is Antithesis working?
  • Optimizing for Antithesis
  • Finding more bugs
  • FAQ
  • About Antithesis POCs
  • Release notes
  • Release notes