1LTP Library API Writing Guidelines 2================================== 3 4NOTE: See also 5 https://github.com/linux-test-project/ltp/wiki/Test-Writing-Guidelines[Test Writing Guidelines], 6 https://github.com/linux-test-project/ltp/wiki/C-Test-API[C Test API], 7 https://github.com/linux-test-project/ltp/wiki/Shell-Test-API[Shell Test API]. 8 91. General Rules 10---------------- 11 12For extending library API it applies the same general rules as for writing tests, 13(see https://github.com/linux-test-project/ltp/wiki/Test-Writing-Guidelines[Test Writing Guidelines], 14offline: 'doc/test-writing-guidelines.txt'), 15with strong focus on readability and simplicity. 16 17Library tests are in 'lib/newlib_tests' directory. 18 19Don't forget to update docs when you change the API. 20 212. C API 22-------- 23 242.1 LTP-001: Sources have tst_ prefix 25~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 26 27API source code is in headers `include/*.h`, `include/lapi/*.h` (backward 28compatibility for old kernel and libc) and C sources in `lib/*.c`. Files have 29'tst_' prefix. 30 312.2 LTP-002: TST_RET and TST_ERR are not modified 32~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 33 34The test author is guaranteed that the test API will not modify these 35variables. This prevents silent errors where the return value and 36errno are overwritten before the test has chance to check them. 37 38The macros which are clearly intended to update these variables. That 39is +TEST+ and those in 'tst_test_macros.h'. Are of course allowed to 40update these variables. 41 422.3 LTP-003: Externally visible library symbols have the tst_ prefix 43~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 44 45Functions, types and variables in the public test API should have the 46tst_ prefix. With some exceptions for symbols already prefixed with 47safe_ or ltp_. 48 49Static (private) symbols should not have the prefix. 50 51 523. Shell API 53------------ 54 55API source code is in `tst_test.sh`, `tst_security.sh` and `tst_net.sh` 56(all in 'testcases/lib' directory). 57 58Changes in the shell API should not introduce uncommon dependencies 59(use basic commands installed everywhere by default). 60