@@ -251,6 +251,9 @@ success. It will check for the return value and reports failure if the return
value is not equal to 0. The call also sets the 'TST_PASS' variable to 1 if
the call succeeeded.
+As seen above, this and similar macros take optional variadic arguments. These
+begin with a format string and then appropriate values to be formatted.
+
[source,c]
-------------------------------------------------------------------------------
static void test(void)
@@ -291,8 +294,44 @@ static void test(void)
}
-------------------------------------------------------------------------------
-The 'TST_EXP_FAIL2()' is the same as 'TST_EXP_FAIL()' except the return value
-is expected to be non-negative integer if call passes.
+The 'TST_EXP_FAIL2()' is the same as 'TST_EXP_FAIL()' except the return value is
+expected to be non-negative integer if call passes. These macros build upon the
++TEST()+ macro and associated variables.
+
+[source,c]
+-------------------------------------------------------------------------------
+TEST(socket(AF_INET, SOCK_RAW, 1));
+if (TST_RET > -1) {
+ tst_res(TFAIL, "Created raw socket");
+ SAFE_CLOSE(TST_RET);
+} else if (TST_ERR != EPERM) {
+ tst_res(TFAIL | TTERRNO,
+ "Failed to create socket for wrong reason");
+} else {
+ tst_res(TPASS | TTERRNO, "Didn't create raw socket");
+}
+-------------------------------------------------------------------------------
+
+The +TEST+ macro sets +TST_RET+ to its argument's return value and +TST_ERR+ to
++errno+. The +TTERNO+ flag can be used to print the error number's symbolic
+value.
+
+No LTP library function or macro, except those in 'tst_test_macros.h', will
+write to these variables (rule 'LTP-002'). So their values will not be changed
+unexpectedly.
+
+[source,c]
+-------------------------------------------------------------------------------
+TST_EXP_POSITIVE(wait(&status));
+
+if (!TST_PASS)
+ return;
+-------------------------------------------------------------------------------
+
+If the return value of 'wait' is positive. This macro will print a pass result
+and set +TST_PASS+ appropriately. If the return value is zero or negative, then
+it will print fail. There are many similar macros to those shown here, please
+see 'tst_test_macros.h'.
[source,c]
-------------------------------------------------------------------------------
@@ -21,10 +21,24 @@ 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.
+
3. Shell API
------------