API-SANITY-CHECKER(1)

💖 bestie. wake UP. API-SANITY-CHECKER(1) is here and it lives in User Commands (section 1) and it's literally about to hand you free unit tests for your C/C++ library API. no cap. let's go ✨

🎀 NAME 🎀

api-sanity-checker — an automatic generator of basic unit tests for a C/C++ library API. that's the whole vibe. 🦋

✨ DESCRIPTION ✨

💅 NAME:

API Sanity Checker (api-sanity-checker) — Generate basic unit tests for a C/C++ library API. iconic behaviour, honestly.

🌸 DESCRIPTION:

okay so, API Sanity Checker is an automatic generator of basic unit tests for a C/C++ library. it helps you quickly generate simple ("sanity" or "shallow" quality) tests for every function in an API, using their signatures, data type definitions, and the relationships between functions — pulled straight from the library header files ("Header-Driven Generation"). main character energy fr. 🌟

each test case contains a function call with reasonable input parameters (in most, but unfortunately not all, cases — it said what it said 😭). the quality of the generated tests lets you check for the absence of critical errors in simple use cases, and it can be greatly improved by bringing in highly reusable specialized types for the library. 💅

the tool can execute the generated tests and detect crashes, aborts, all kinds of emitted signals, non-zero program return code, program hanging, and requirement failures (if specified). so it's giving "out-of-box low-cost sanity checking of a library API" and "test development framework for the initial generation of templates for advanced tests." it also supports the universal Template2Code format of tests, splint specifications, random test generation mode, and other useful features. obsessed. 🫶

this tool is free software: you can redistribute it and/or modify it under the terms of the GNU LGPL or GNU GPL. periodt. 💖

🧚 USAGE:

api-sanity-checker [options]

🌈 EXAMPLE:

api-sanity-checker -lib NAME -d VER.xml -gen -build -run

and VERSION.xml is the XML-descriptor:

<version>

1.0

</version>

<headers>

/path1/to/header(s)/ /path2/to/header(s)/

...

</headers>

<libs>

/path1/to/library(ies)/ /path2/to/library(ies)/

...

</libs>

---

💜 INFORMATION OPTIONS 💜

• -h, -help — Print this help. the "bestie explain" button 🫶
• -info — Print complete info. all of it. the whole lore dump.
• -v, -version — Print version information.
• -dumpversion — Print the tool version (1.98.7) and don't do anything else. just the number, nothing more, she said 💅

🌸 GENERAL OPTIONS 🌸

• -l, -lib, -library NAME — Library name (without version). keep it bare, no version attached.
• -d, -descriptor PATH — Path to the library descriptor (the VER.xml file):

<version>

1.0

</version>

<headers>

/path1/to/header(s)/ /path2/to/header(s)/ ...

</headers>

<libs>

/path1/to/library(ies)/ /path2/to/library(ies)/ ...

</libs>

for more information, please see: http://lvc.github.com/api-sanity-checker/Xml-Descriptor.html

• -gen, -generate — Generate test(s). Options -l and -d should be specified. To generate a test for a particular function, use it together with the -f option. Exit code: number of test cases failed to build.
• -build, -make — Build test(s). Options -l and -d should be specified. To build a test for a particular function, use it together with the -f option. Exit code: number of test cases failed to generate.
• -run — Run test(s), create test report. Options -l and -d should be specified. To run a test for a particular function, use it together with the -f option. Exit code: number of failed test cases.
• -clean — Clean test(s). Options -l and -d should be specified. To clean a test for a particular function, use it together with the -f option.

🔥 EXTRA OPTIONS 🔥

• -vnum NUM — Specify library version outside the descriptor.
• -s, -symbol NAME — Generate/Build/Run test for the specified function (mangled name in C++). yes bestie, mangled. that's the rule 😌
• -symbols-list PATH — This option allows you to specify a file with a list of functions (one per line, mangled name in C++) that should be tested; other library functions will not be tested.
• -header NAME — This option allows you to restrict the list of functions that should be tested by providing a header file name in which they are declared. This option is intended for step-by-step tests development. little by little, we love a slow burn ✨
• -all — Generate tests for all symbols recursively included in header file(s).
• -xvfb — Use Xvfb-server instead of the current X-server (default) for running tests.
• -t2c, -template2code — Generate tests in the universal Template2Code format. For more information, please see: http://sourceforge.net/projects/template2code/
• -strict-gen — Terminate the process of generating tests and return error code '1' if it cannot generate at least one test case. she is NOT playing 🚫
• -strict-build — Terminate the process of building tests and return error code '1' if it cannot build at least one test case.
• -strict-run — Terminate the process of running tests and return error code '1' if at least one test case failed.
• -strict — This option enables all -strict-* options. the whole squad, activated 💅
• -r, -random — Random test generation mode. chaos mode, love that for us.
• -min — Generate minimun code, call functions with the minimum number of parameters to initialize parameters of other functions.
• -max — Generate maximum code, call functions with the maximum number of parameters to initialize parameters of other functions.
• -show-retval — Show the function return type in the report.
• -check-retval — Insert requirements on return values (retval!=NULL) for each called function.
• -st, -specialized-types PATH — Path to the file with the collection of specialized types. For more information, please see: http://lvc.github.com/api-sanity-checker/Specialized-Type.html
• -td, -test-data PATH — Path to the directory with the test data files. For more information, please see: http://lvc.github.com/api-sanity-checker/Specialized-Type.html
• -headers-only — If the library consists of inline functions only and has no shared objects, then you should specify this option.
• -no-inline — Don't generate tests for inline functions.
• -keep-internal — Generate tests for internal symbols (functions with a '__' prefix and methods of classes declared inside other classes).
• -isolated — Allow one to restrict functions usage by the lists specified by the -functions-list option or by the group devision in the descriptor.
• -view-only — Remove all files from the test suite except *.html files. This option allows one to create a lightweight html-index for all tests. declutter queen 🧹
• -disable-default-values — Disable usage of default values for function parameters.
• -optimize-includes LEVEL — Enable optimization of the list of included headers in each test case. Available levels:
  • High (default)
  • Medium
  • Low
  • None - disable
• -p, -params PATH — Path to a file with the function parameter names. It can be used for improving generated tests if the library header files don't contain parameter names. File format:

func1;param1;param2;param3 ...
func2;param1;param2;param3 ...
...

• -title NAME — The name of the library in the report title.
• -relpath, -reldir PATH — Replace {RELPATH} in the library descriptor by PATH.
• -lang LANG — Set library language (C or C++). You can use this option if the tool cannot auto-detect a language.
• -target COMPILER — The compiler that should be used to build generated tests under Windows. Supported:
  • gcc - GNU compiler
  • cl - MS compiler (default)
• -debug — Write extended log for debugging. for when you need the receipts 🔍
• -cache — Cache the ABI dump and use it on the next run. work smarter not harder 💅

🦋 OTHER OPTIONS 🦋

• -test — Run internal tests. Create a simple library and run the tool on it. This option allows one to check if the tool works correctly on the system. a little vibe check for your machine ✨
• -disable-variable-reuse — Disable reusing of previously created variables in the test.
• -long-variable-names — Enable long (complex) variable names instead of short names.

⭐ EXIT CODES: ⭐

• 0 - Successful tests. The tool has run without any errors.
• non-zero - Tests failed or the tool has run with errors.

heads up bestie: if you see a non-zero walking out the door, something either failed or straight up went wrong. no in-between. 😭

🌈 MORE INFORMATION: 🌈

http://lvc.github.com/api-sanity-checker/ — go read, iykyk 💖

👑 AUTHOR 👑

This manual page was written by Mathieu Malaterre <malat@debian.org> for the Debian GNU/Linux system (but may be used by others). give her her flowers 💐

Written by Andrey Ponomarenko.

🎀 COPYRIGHT 🎀

Copyright © 2015 Andrey Ponomarenko's ABI Laboratory License: LGPL or GPL http://www.gnu.org/licenses/ This program is free software: you can redistribute it and/or modify it. absolute slay, go forth and redistribute 🫶

---

okay that's the whole page, bestie — this was the API Sanity Checker, version 1.98.7, dated December 2025 💖✨ ily, go build something and let the checker carry the sanity for you 🎀🦋💅