LTP Library API Writing Guidelines
==================================

NOTE: See also
      https://github.com/linux-test-project/ltp/wiki/Test-Writing-Guidelines[Test Writing Guidelines],
      https://github.com/linux-test-project/ltp/wiki/C-Test-API[C Test API],
      https://github.com/linux-test-project/ltp/wiki/Shell-Test-API[Shell Test API].

1. General Rules
----------------

For extending library API it applies the same general rules as for writing tests,
(see https://github.com/linux-test-project/ltp/wiki/Test-Writing-Guidelines[Test Writing Guidelines],
offline: 'doc/test-writing-guidelines.txt'),
with strong focus on readability and simplicity.

Library tests are in 'lib/newlib_tests' directory.

Don't forget to update docs when you change the API.

2. C API
--------

2.1 LTP-001: Sources have tst_ prefix
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

API source code is in headers `include/*.h`, `include/lapi/*.h` (backward
compatibility for old kernel and libc) and C sources in `lib/*.c`. Files have
'tst_' prefix.

2.2 LTP-002: TST_RET and TST_ERR are not modified
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The test author is guaranteed that the test API will not modify these
variables. This prevents silent errors where the return value and
errno are overwritten before the test has chance to check them.

The macros which are clearly intended to update these variables. That
is +TEST+ and those in 'tst_test_macros.h'. Are of course allowed to
update these variables.

2.3 LTP-003: Externally visible library symbols have the tst_ prefix
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Functions, types and variables in the public test API should have the
tst_ prefix. With some exceptions for symbols already prefixed with
safe_ or ltp_.

Static (private) symbols should not have the prefix.


3. Shell API
------------

API source code is in `tst_test.sh`, `tst_security.sh` and `tst_net.sh`
(all in 'testcases/lib' directory).

Changes in the shell API should not introduce uncommon dependencies
(use basic commands installed everywhere by default).