1LTP C Test API 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-Case-Tutorial[C Test Case Tutorial], 7 https://github.com/linux-test-project/ltp/wiki/Shell-Test-API[Shell Test API]. 8 91 Writing a test in C 10--------------------- 11 121.1 Basic test structure 13~~~~~~~~~~~~~~~~~~~~~~~~ 14 15Let's start with an example, following code is a simple test for a 'getenv()'. 16 17[source,c] 18------------------------------------------------------------------------------- 19/*\ 20 * [Description] 21 * Tests basic functionality of getenv(). 22 * 23 * - create an env variable and verify that getenv() can get it 24 * - call getenv() with nonexisting variable name, check that it returns NULL 25 */ 26 27#include "tst_test.h" 28 29#define ENV1 "LTP_TEST_ENV" 30#define ENV2 "LTP_TEST_THIS_DOES_NOT_EXIST" 31#define ENV_VAL "val" 32 33static void setup(void) 34{ 35 if (setenv(ENV1, ENV_VAL, 1)) 36 tst_brk(TBROK | TERRNO, "setenv() failed"); 37} 38 39static void run(void) 40{ 41 char *ret; 42 43 ret = getenv(ENV1); 44 45 if (!ret) { 46 tst_res(TFAIL, "getenv(" ENV1 ") = NULL"); 47 goto next; 48 } 49 50 if (!strcmp(ret, ENV_VAL)) { 51 tst_res(TPASS, "getenv(" ENV1 ") = '"ENV_VAL "'"); 52 } else { 53 tst_res(TFAIL, "getenv(" ENV1 ") = '%s', expected '" 54 ENV_VAL "'", ret); 55 } 56 57next: 58 ret = getenv(ENV2); 59 60 if (ret) 61 tst_res(TFAIL, "getenv(" ENV2 ") = '%s'", ret); 62 else 63 tst_res(TPASS, "getenv(" ENV2 ") = NULL"); 64} 65 66static struct tst_test test = { 67 .test_all = run, 68 .setup = setup, 69}; 70------------------------------------------------------------------------------- 71 72Each test includes the 'tst_test.h' header and must define the 'struct 73tst_test test' structure. 74 75The overall test initialization is done in the 'setup()' function. 76 77The overall cleanup is done in a 'cleanup()' function. Here 'cleanup()' is 78omitted as the test does not have anything to clean up. If cleanup is set in 79the test structure it's called on test exit just before the test library 80cleanup. That especially means that cleanup can be called at any point in a 81test execution. For example even when a test setup step has failed, therefore 82the 'cleanup()' function must be able to cope with unfinished initialization, 83and so on. 84 85The test itself is done in the 'test()' function. The test function must work 86fine if called in a loop. 87 88There are two types of a test function pointers in the test structure. The 89first one is a '.test_all' pointer that is used when test is implemented as a 90single function. Then there is a '.test' function along with the number of 91tests '.tcnt' that allows for more detailed result reporting. If the '.test' 92pointer is set the function is called '.tcnt' times with an integer parameter 93in range of [0, '.tcnt' - 1]. 94 95IMPORTANT: Only one of '.test' and '.test_all' can be set at a time. 96 97Each test has a limit on how long it can run and the limit composes of two 98parts max_runtime and timeout. The max_runtime is a limit for how long can the 99'.test_all' or a set of '.test' functions take and the timeout is static part 100that should cover the duration of test setup and cleanup plus some safety. 101 102Any test that runs for more than a second or two has to make sure to: 103 104- set the runtime either by setting the '.max_runtime' in tst_test or by 105 calling 'tst_set_max_runtime()' in the test setup 106 107- monitor remaning runtime by regular calls to 'tst_remaining_runtime()' and 108 exit when runtime has been used up 109 110Test is free to exit before max_runtime has been used up for example when 111minimal number of iteration was finished. 112 113The limit is applied to a single call of the '.test_all' function that means 114that for example when '.test_variants' or '.all_filesystems' is set the whole 115test will be limited by 'variants * (max_runtime + timeout)' seconds and the 116test runtime will be likely close to 'variants * max_runtime' seconds. 117 118[source,c] 119------------------------------------------------------------------------------- 120/* 121 * Returns number of seconds or zero in case that runtime has been used up. 122 */ 123 124int tst_remaining_runtime(void); 125------------------------------------------------------------------------------- 126 127LAPI headers 128++++++++++++ 129 130Use our LAPI headers ('include "lapi/foo.h"') to keep compatibility with old 131distributions. LAPI header should always include original header. Older linux 132headers were problematic, therefore we preferred to use libc headers. There are 133still some bugs when combining certain glibc headers with linux headers, see 134https://sourceware.org/glibc/wiki/Synchronizing_Headers. 135 136A word about the cleanup() callback 137+++++++++++++++++++++++++++++++++++ 138 139There are a few rules that needs to be followed in order to write correct 140cleanup() callback. 141 1421. Free only resources that were initialized. Keep in mind that callback can 143 be executed at any point in the test run. 144 1452. Make sure to free resources in the reverse order they were 146 initialized. (Some of the steps may not depend on others and everything 147 will work if there were swapped but let's keep it in order.) 148 149The first rule may seem complicated at first however, on the contrary, it's 150quite easy. All you have to do is to keep track of what was already 151initialized. For example file descriptors needs to be closed only if they were 152assigned a valid file descriptor. For most of the things you need to create 153extra flag that is set right after successful initialization though. Consider, 154for example, test setup below. 155 156We also prefer cleaning up resources that would otherwise be released on the 157program exit. There are two main reasons for this decision. Resources such as 158file descriptors and mmaped memory could block umounting a block device in 159cases where the test library has mounted a filesystem for the test temporary 160directory. Not freeing allocated memory would upset static analysis and tools 161such as valgrind and produce false-positives when checking for leaks in the 162libc and other low level libraries. 163 164[source,c] 165------------------------------------------------------------------------------- 166static int fd0, fd1, mount_flag; 167 168#define MNTPOINT "mntpoint" 169#define FILE1 "mntpoint/file1" 170#define FILE2 "mntpoint/file2" 171 172static void setup(void) 173{ 174 SAFE_MKDIR(MNTPOINT, 0777); 175 SAFE_MKFS(tst_device->dev, tst_device->fs_type, NULL, NULL); 176 SAFE_MOUNT(tst_device->dev, MNTPOINT, tst_device->fs_type, 0, 0); 177 mount_flag = 1; 178 179 fd0 = SAFE_OPEN(cleanup, FILE1, O_CREAT | O_RDWR, 0666); 180 fd1 = SAFE_OPEN(cleanup, FILE2, O_CREAT | O_RDWR, 0666); 181} 182------------------------------------------------------------------------------- 183 184In this case the 'cleanup()' function may be invoked when any of the 'SAFE_*' 185macros has failed and therefore must be able to work with unfinished 186initialization as well. Since global variables are initialized to zero we can 187just check that fd > 0 before we attempt to close it. The mount function 188requires extra flag to be set after device was successfully mounted. 189 190[source,c] 191------------------------------------------------------------------------------- 192static void cleanup(void) 193{ 194 if (fd1 > 0) 195 SAFE_CLOSE(fd1); 196 197 if (fd0 > 0) 198 SAFE_CLOSE(fd0); 199 200 if (mount_flag && tst_umouont(MNTPOINT)) 201 tst_res(TWARN | TERRNO, "umount(%s)", MNTPOINT); 202} 203------------------------------------------------------------------------------- 204 205IMPORTANT: 'SAFE_MACROS()' used in cleanup *do not* exit the test. Failure 206 only produces a warning and the 'cleanup()' carries on. This is 207 intentional as we want to execute as much 'cleanup()' as possible. 208 209WARNING: Calling tst_brk() in test 'cleanup()' does not exit the test as well 210 and 'TBROK' is converted to 'TWARN'. 211 212NOTE: Creation and removal of the test temporary directory is handled in 213 the test library and the directory is removed recursively. Therefore 214 we do not have to remove files and directories in the test cleanup. 215 2161.2 Basic test interface 217~~~~~~~~~~~~~~~~~~~~~~~~ 218 219[source,c] 220------------------------------------------------------------------------------- 221void tst_res(int ttype, char *arg_fmt, ...); 222------------------------------------------------------------------------------- 223 224Printf-like function to report test result, it's mostly used with ttype: 225 226|============================== 227| 'TPASS' | Test has passed. 228| 'TFAIL' | Test has failed. 229| 'TINFO' | General message. 230| 'TDEBUG' | Debug message (new C API only, printed with '-D' or via 'LTP_ENABLE_DEBUG=1' or 'y' 231 environment variable), only for messages which would be too verbose for normal run. 232| 'TWARN' | Something went wrong but we decided to continue. Mostly used in cleanup functions. 233|============================== 234 235The 'ttype' can be combined bitwise with 'TERRNO' or 'TTERRNO' to print 236'errno', 'TST_ERR' respectively. 237 238[source,c] 239------------------------------------------------------------------------------- 240void tst_brk(int ttype, char *arg_fmt, ...); 241------------------------------------------------------------------------------- 242 243Printf-like function to report error and exit the test, it can be used with ttype: 244 245|============================================================ 246| 'TBROK' | Something has failed in test preparation phase. 247| 'TCONF' | Test is not appropriate for current configuration 248 (syscall not implemented, unsupported arch, ...) 249|============================================================ 250 251The 'ttype' can be combined bitwise with 'TERRNO' or 'TTERRNO' to print 252'errno', 'TST_ERR' respectively. 253 254There are also 'TST_EXP_*()' macros that can simplify syscall unit tests to a 255single line, use them whenever possible. These macros take a function call as 256the first parameter and a printf-like format string and parameters as well. 257These test macros then expand to a code that runs the call, checks the return 258value and errno and reports the test result. 259 260[source,c] 261------------------------------------------------------------------------------- 262static void run(void) 263{ 264 ... 265 TST_EXP_PASS(stat(fname, &statbuf), "stat(%s, ...)", fname); 266 267 if (!TST_PASS) 268 return; 269 ... 270} 271------------------------------------------------------------------------------- 272 273The 'TST_EXP_PASS()' can be used for calls that return -1 on failure and 0 on 274success. It will check for the return value and reports failure if the return 275value is not equal to 0. The call also sets the 'TST_PASS' variable to 1 if 276the call succeeeded. 277 278As seen above, this and similar macros take optional variadic arguments. These 279begin with a format string and then appropriate values to be formatted. 280 281[source,c] 282------------------------------------------------------------------------------- 283static void run(void) 284{ 285 ... 286 TST_EXP_FD(open(fname, O_RDONLY), "open(%s, O_RDONLY)", fname); 287 288 SAFE_CLOSE(TST_RET); 289 ... 290} 291------------------------------------------------------------------------------- 292 293The 'TST_EXP_FD()' is the same as 'TST_EXP_PASS()' the only difference is that 294the return value is expected to be a file descriptor so the call passes if 295positive integer is returned. 296 297[source,c] 298------------------------------------------------------------------------------- 299static void run(void) 300{ 301 ... 302 TST_EXP_FAIL(stat(fname, &statbuf), ENOENT, "stat(%s, ...)", fname); 303 ... 304} 305------------------------------------------------------------------------------- 306 307The 'TST_EXP_FAIL()' is similar to 'TST_EXP_PASS()' but it fails the test if 308the call haven't failed with -1 and 'errno' wasn't set to the expected one 309passed as the second argument. 310 311[source,c] 312------------------------------------------------------------------------------- 313static void run(void) 314{ 315 ... 316 TST_EXP_FAIL2(msgget(key, flags), EINVAL, "msgget(%i, %i)", key, flags); 317 ... 318} 319------------------------------------------------------------------------------- 320 321The 'TST_EXP_FAIL2()' is the same as 'TST_EXP_FAIL()' except the return value is 322expected to be non-negative integer if call passes. These macros build upon the 323+TEST()+ macro and associated variables. 324 325'TST_EXP_FAIL_SILENT()' and 'TST_EXP_FAIL2_SILENT()' variants are less verbose 326and do not print TPASS messages when SCALL fails as expected. 327 328[source,c] 329------------------------------------------------------------------------------- 330TEST(socket(AF_INET, SOCK_RAW, 1)); 331if (TST_RET > -1) { 332 tst_res(TFAIL, "Created raw socket"); 333 SAFE_CLOSE(TST_RET); 334} else if (TST_ERR != EPERM) { 335 tst_res(TFAIL | TTERRNO, 336 "Failed to create socket for wrong reason"); 337} else { 338 tst_res(TPASS | TTERRNO, "Didn't create raw socket"); 339} 340------------------------------------------------------------------------------- 341 342The +TEST+ macro sets +TST_RET+ to its argument's return value and +TST_ERR+ to 343+errno+. The +TTERRNO+ flag can be used to print the error number's symbolic 344value. 345 346No LTP library function or macro, except those in 'tst_test_macros.h', will 347write to these variables (rule 'LTP-002'). So their values will not be changed 348unexpectedly. 349 350[source,c] 351------------------------------------------------------------------------------- 352TST_EXP_POSITIVE(wait(&status)); 353 354if (!TST_PASS) 355 return; 356------------------------------------------------------------------------------- 357 358If the return value of 'wait' is positive or zero, this macro will print a pass 359result and set +TST_PASS+ appropriately. If the return value is negative, then 360it will print fail. There are many similar macros to those shown here, please 361see 'tst_test_macros.h'. 362 363[source,c] 364------------------------------------------------------------------------------- 365TST_EXP_EQ_LI(val1, val2); 366TST_EXP_EQ_UI(val1, val2); 367TST_EXP_EQ_SZ(val1, val2); 368TST_EXP_EQ_SSZ(val1, val2); 369 370/* Use as */ 371TST_EXP_EQ_LI(sig_caught, SIGCHLD); 372------------------------------------------------------------------------------- 373 374Set of macros for different integer type comparsions. These macros print the 375variable names as well as values in both pass and fail scenarios. 376 377[source,c] 378------------------------------------------------------------------------------- 379const char *tst_strsig(int sig); 380------------------------------------------------------------------------------- 381 382Return the given signal number's corresponding string. 383 384[source,c] 385------------------------------------------------------------------------------- 386const char *tst_strerrno(int err); 387------------------------------------------------------------------------------- 388 389Return the given errno number's corresponding string. Using this function to 390translate 'errno' values to strings is preferred. You should not use the 391'strerror()' function in the testcases. 392 393[source,c] 394------------------------------------------------------------------------------- 395const char *tst_strstatus(int status); 396------------------------------------------------------------------------------- 397 398Returns string describing the status as returned by 'wait()'. 399 400WARNING: This function is not thread safe. 401 402[source,c] 403------------------------------------------------------------------------------- 404void tst_set_max_runtime(int max_runtime); 405------------------------------------------------------------------------------- 406 407Allows for setting max_runtime per test iteration dynamically in the test 'setup()', 408the timeout is specified in seconds. There are a few testcases whose runtime 409can vary arbitrarily, these can disable timeouts by setting it to 410TST_UNLIMITED_RUNTIME. 411 412[source,c] 413------------------------------------------------------------------------------- 414void tst_flush(void); 415------------------------------------------------------------------------------- 416 417Flush output streams, handling errors appropriately. 418 419This function is rarely needed when you have to flush the output streams 420before calling 'fork()' or 'clone()'. Note that the 'SAFE_FORK()' and 'SAFE_CLONE()' 421calls this function automatically. See 2.4 FILE buffers and fork() for explanation 422why is this needed. 423 4241.3 Test temporary directory 425~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 426 427If '.needs_tmpdir' is set to '1' in the 'struct tst_test' unique test 428temporary is created and it's set as the test working directory. Tests *MUST 429NOT* create temporary files outside that directory. The flag is not needed to 430be set when use these flags: '.all_filesystems', '.format_device', '.mntpoint', 431'.mount_device' '.needs_checkpoints', '.needs_device', '.resource_file' 432(these flags imply creating temporary directory). 433 434IMPORTANT: Close all file descriptors (that point to files in test temporary 435 directory, even the unlinked ones) either in the 'test()' function 436 or in the test 'cleanup()' otherwise the test may break temporary 437 directory removal on NFS (look for "NFS silly rename"). 438 4391.4 Safe macros 440~~~~~~~~~~~~~~~ 441 442Safe macros aim to simplify error checking in test preparation. Instead of 443calling system API functions, checking for their return value and aborting the 444test if the operation has failed, you just use corresponding safe macro. 445 446Use them whenever it's possible. 447 448Instead of writing: 449 450[source,c] 451------------------------------------------------------------------------------- 452fd = open("/dev/null", O_RDONLY); 453if (fd < 0) 454 tst_brk(TBROK | TERRNO, "opening /dev/null failed"); 455------------------------------------------------------------------------------- 456 457You write just: 458 459[source,c] 460------------------------------------------------------------------------------- 461fd = SAFE_OPEN("/dev/null", O_RDONLY); 462------------------------------------------------------------------------------- 463 464IMPORTANT: The 'SAFE_CLOSE()' function also sets the passed file descriptor to -1 465 after it's successfully closed. 466 467They can also simplify reading and writing of sysfs files, you can, for 468example, do: 469 470[source,c] 471------------------------------------------------------------------------------- 472SAFE_FILE_SCANF("/proc/sys/kernel/pid_max", "%lu", &pid_max); 473------------------------------------------------------------------------------- 474 475See 'include/tst_safe_macros.h', 'include/tst_safe_stdio.h' and 476'include/tst_safe_file_ops.h' and 'include/tst_safe_net.h' for a complete list. 477 4781.5 Test specific command line options 479~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 480 481[source,c] 482------------------------------------------------------------------------------- 483struct tst_option { 484 char *optstr; 485 char **arg; 486 char *help; 487}; 488------------------------------------------------------------------------------- 489 490Test specific command line parameters can be passed with the 'NULL' terminated 491array of 'struct tst_option'. The 'optstr' is the command line option i.e. "o" 492or "o:" if option has a parameter. Only short options are supported. The 'arg' 493is where 'optarg' is stored upon match. If option has no parameter it's set to 494non-'NULL' value if option was present. The 'help' is a short help string. 495 496NOTE: The test parameters must not collide with common test parameters defined 497 in the library the currently used ones are +-i+, +-I+, +-C+, and +-h+. 498 499[source,c] 500------------------------------------------------------------------------------- 501int tst_parse_int(const char *str, int *val, int min, int max); 502int tst_parse_long(const char *str, long *val, long min, long max); 503int tst_parse_float(const char *str, float *val, float min, float max); 504int tst_parse_filesize(const char *str, long long *val, long long min, long long max); 505------------------------------------------------------------------------------- 506 507Helpers for parsing the strings returned in the 'struct tst_option'. 508 509Helpers return zero on success and 'errno', mostly 'EINVAL' or 'ERANGE', on 510failure. 511 512Helpers functions are no-op if 'str' is 'NULL'. 513 514The valid range for result includes both 'min' and 'max'. 515 516In particular, 'tst_parse_filesize' function accepts prefix multiplies such as 517"k/K for kilobytes, "m/M" for megabytes and "g/G" for gigabytes. For example, 51810K are converted into 10240 bytes. 519 520[source,c] 521------------------------------------------------------------------------------- 522#include <limits.h> 523#include "tst_test.h" 524 525static char *str_threads; 526static int threads = 10; 527 528static void setup(void) 529{ 530 if (tst_parse_int(str_threads, &threads, 1, INT_MAX)) 531 tst_brk(TBROK, "Invalid number of threads '%s'", str_threads); 532 533 ... 534} 535 536static void test_threads(void) 537{ 538 ... 539 540 for (i = 0; i < threads; i++) { 541 ... 542 } 543 544 ... 545} 546 547static struct tst_test test = { 548 ... 549 .options = (struct tst_option[]) { 550 {"t:", &str_threads, "Number of threads (default 10)"}, 551 {}, 552 ... 553}; 554------------------------------------------------------------------------------- 555 556 5571.6 Runtime kernel version detection 558~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 559 560Testcases for newly added kernel functionality require kernel newer than a 561certain version to run. All you need to skip a test on older kernels is to 562set the '.min_kver' string in the 'struct tst_test' to a minimal required 563kernel version, e.g. '.min_kver = "4.10.0"'. 564 565For more complicated operations such as skipping a test for a certain range 566of kernel versions, following functions could be used: 567 568[source,c] 569------------------------------------------------------------------------------- 570int tst_kvercmp(int r1, int r2, int r3); 571 572struct tst_kern_exv { 573 char *dist_name; 574 char *extra_ver; 575}; 576 577int tst_kvercmp2(int r1, int r2, int r3, struct tst_kern_exv *vers); 578------------------------------------------------------------------------------- 579 580These two functions are intended for runtime kernel version detection. They 581parse the output from 'uname()' and compare it to the passed values. 582 583The return value is similar to the 'strcmp()' function, i.e. zero means equal, 584negative value means that the kernel is older than the expected value and 585positive means that it's newer. 586 587The second function 'tst_kvercmp2()' allows for specifying per-vendor table of 588kernel versions as vendors typically backport fixes to their kernels and the 589test may be relevant even if the kernel version does not suggests so. 590 591[source,c] 592------------------------------------------------------------------------------- 593if (tst_kvercmp(5, 19, 0) >= 0) 594 tst_res(TCONF, "Test valid only for kernel < 5.19"); 595 596static struct tst_kern_exv kvers[] = { 597 { "UBUNTU", "4.4.0-48.69" }, 598 { NULL, NULL}, 599}; 600 601if (tst_kvercmp2(4, 4, 27, kvers) < 0) 602 /* code for kernel < v4.4.27 or ubuntu kernel < 4.4.0-48.69 */ 603------------------------------------------------------------------------------- 604 605WARNING: The shell 'tst_kvercmp' maps the result into unsigned integer - the 606 process exit value. 607 608NOTE: See also LTP 609 https://github.com/linux-test-project/ltp/wiki/Supported-kernel,-libc,-toolchain-versions#13-minimal-supported-kernel-version[minimal supported kernel version]. 610 6111.7 Fork()-ing 612~~~~~~~~~~~~~~ 613 614Be wary that if the test forks and there were messages printed by the 615'tst_*()' interfaces, the data may still be in libc/kernel buffers and these 616*ARE NOT* flushed automatically. 617 618This happens when 'stdout' gets redirected to a file. In this case, the 619'stdout' is not line buffered, but block buffered. Hence after a fork content 620of the buffers will be printed by the parent and each of the children. 621 622To avoid that you should use 'SAFE_FORK()', 'SAFE_CLONE()' or 'tst_clone()'. 623 624IMPORTANT: You have to set the '.forks_child' flag in the test structure 625 if your testcase forks or calls 'SAFE_CLONE()'. 626 6271.8 Doing the test in the child process 628~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 629 630Results reported by 'tst_res()' are propagated to the parent test process via 631block of shared memory. 632 633Calling 'tst_brk()' causes child process to exit with non-zero exit value. 634Which means that it's safe to use 'SAFE_*()' macros in the child processes as 635well. 636 637Children that outlive the 'test()' function execution are waited for in the 638test library. Unclean child exit (killed by signal, non-zero exit value, etc.) 639will cause the main test process to exit with 'tst_brk()', which especially 640means that 'TBROK' propagated from a child process will cause the whole test 641to exit with 'TBROK'. 642 643If a test needs a child that segfaults or does anything else that cause it to 644exit uncleanly all you need to do is to wait for such children from the 645'test()' function so that it's reaped before the main test exits the 'test()' 646function. 647 648[source,c] 649------------------------------------------------------------------------------- 650#include "tst_test.h" 651 652void tst_reap_children(void); 653------------------------------------------------------------------------------- 654 655The 'tst_reap_children()' function makes the process wait for all of its 656children and exits with 'tst_brk(TBROK, ...)' if any of them returned 657a non zero exit code. 658 659When using 'SAFE_CLONE' or 'tst_clone', this may not work depending on 660the parameters passed to clone. The following call to 'SAFE_CLONE' is 661identical to 'fork()', so will work as expected. 662 663[source,c] 664-------------------------------------------------------------------------------- 665const struct tst_clone_args args = { 666 .exit_signal = SIGCHLD, 667}; 668 669SAFE_CLONE(&args); 670-------------------------------------------------------------------------------- 671 672If 'exit_signal' is set to something else, then this will break 673'tst_reap_children'. It's not expected that all parameters to clone will 674work with the LTP library unless specific action is taken by the test code. 675 676.Using 'tst_res()' from binaries started by 'exec()' 677[source,c] 678------------------------------------------------------------------------------- 679/* test.c */ 680#define _GNU_SOURCE 681#include <unistd.h> 682#include "tst_test.h" 683 684static void do_test(void) 685{ 686 char *const argv[] = {"test_exec_child", NULL}; 687 char path[4096]; 688 689 if (tst_get_path("test_exec_child", path, sizeof(path))) 690 tst_brk(TCONF, "Couldn't find test_exec_child in $PATH"); 691 692 execve(path, argv, environ); 693 694 tst_res(TFAIL | TERRNO, "EXEC!"); 695} 696 697static struct tst_test test = { 698 .test_all = do_test, 699 .child_needs_reinit = 1, 700}; 701 702/* test_exec_child.c */ 703#define TST_NO_DEFAULT_MAIN 704#include "tst_test.h" 705 706int main(void) 707{ 708 tst_reinit(); 709 tst_res(TPASS, "Child passed!"); 710 return 0; 711} 712------------------------------------------------------------------------------- 713 714The 'tst_res()' function can be also used from binaries started by 'exec()', 715the parent test process has to set the '.child_needs_reinit' flag so that the 716library prepares for it and has to make sure the 'LTP_IPC_PATH' environment 717variable is passed down, then the very first thing the program has to call in 718'main()' is 'tst_reinit()' that sets up the IPC. 719 7201.9 Fork() and Parent-child synchronization 721~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 722 723As LTP tests are written for Linux, most of the tests involve fork()-ing and 724parent-child process synchronization. LTP includes a checkpoint library that 725provides wait/wake futex based functions. 726 727In order to use checkpoints the '.needs_checkpoints' flag in the 'struct 728tst_test' must be set to '1', this causes the test library to initialize 729checkpoints before the 'test()' function is called. 730 731[source,c] 732------------------------------------------------------------------------------- 733#include "tst_test.h" 734 735TST_CHECKPOINT_WAIT(id) 736 737TST_CHECKPOINT_WAIT2(id, msec_timeout) 738 739TST_CHECKPOINT_WAKE(id) 740 741TST_CHECKPOINT_WAKE2(id, nr_wake) 742 743TST_CHECKPOINT_WAKE_AND_WAIT(id) 744------------------------------------------------------------------------------- 745 746The checkpoint interface provides pair of wake and wait functions. The 'id' is 747unsigned integer which specifies checkpoint to wake/wait for. As a matter of 748fact it's an index to an array stored in a shared memory, so it starts on 749'0' and there should be enough room for at least of hundred of them. 750 751The 'TST_CHECKPOINT_WAIT()' and 'TST_CHECKPOINT_WAIT2()' suspends process 752execution until it's woken up or until timeout is reached. 753 754The 'TST_CHECKPOINT_WAKE()' wakes one process waiting on the checkpoint. 755If no process is waiting the function retries until it success or until 756timeout is reached. 757 758If timeout has been reached process exits with appropriate error message (uses 759'tst_brk()'). 760 761The 'TST_CHECKPOINT_WAKE2()' does the same as 'TST_CHECKPOINT_WAKE()' but can 762be used to wake precisely 'nr_wake' processes. 763 764The 'TST_CHECKPOINT_WAKE_AND_WAIT()' is a shorthand for doing wake and then 765immediately waiting on the same checkpoint. 766 767Child processes created via 'SAFE_FORK()' are ready to use the checkpoint 768synchronization functions, as they inherited the mapped page automatically. 769 770Child processes started via 'exec()', or any other processes not forked from 771the test process must initialize the checkpoint by calling 'tst_reinit()'. 772 773For the details of the interface, look into the 'include/tst_checkpoint.h'. 774 775[source,c] 776------------------------------------------------------------------------------- 777#include "tst_test.h" 778 779/* 780 * Waits for process state change. 781 * 782 * The state is one of the following: 783 * 784 * R - process is running 785 * S - process is sleeping 786 * D - process sleeping uninterruptibly 787 * Z - zombie process 788 * T - process is traced 789 */ 790TST_PROCESS_STATE_WAIT(pid, state, msec_timeout) 791------------------------------------------------------------------------------- 792 793The 'TST_PROCESS_STATE_WAIT()' waits until process 'pid' is in requested 794'state' or timeout is reached. The call polls +/proc/pid/stat+ to get this 795information. A timeout of 0 will wait infinitely. 796 797On timeout -1 is returned and errno set to ETIMEDOUT. 798 799It's mostly used with state 'S' which means that process is sleeping in kernel 800for example in 'pause()' or any other blocking syscall. 801 8021.10 Signals and signal handlers 803~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 804 805If you need to use signal handlers, keep the code short and simple. Don't 806forget that the signal handler is called asynchronously and can interrupt the 807code execution at any place. 808 809This means that problems arise when global state is changed both from the test 810code and signal handler, which will occasionally lead to: 811 812* Data corruption (data gets into inconsistent state), this may happen, for 813 example, for any operations on 'FILE' objects. 814 815* Deadlock, this happens, for example, if you call 'malloc(2)', 'free(2)', 816 etc. from both the test code and the signal handler at the same time since 817 'malloc' has global lock for it's internal data structures. (Be wary that 818 'malloc(2)' is used by the libc functions internally too.) 819 820* Any other unreproducible and unexpected behavior. 821 822Quite common mistake is to call 'exit(3)' from a signal handler. Note that this 823function is not signal-async-safe as it flushes buffers, etc. If you need to 824exit a test immediately from a signal handler use '_exit(2)' instead. 825 826TIP: See 'man 7 signal' for the list of signal-async-safe functions. 827 828If a signal handler sets a variable, its declaration must be 'volatile', 829otherwise compiler may misoptimize the code. This is because the variable may 830not be changed in the compiler code flow analysis. There is 'sig_atomic_t' 831type defined in C99 but this one *DOES NOT* imply 'volatile' (it's just a 832'typedef' to 'int'). So the correct type for a flag that is changed from a 833signal handler is either 'volatile int' or 'volatile sig_atomic_t'. 834 835If a crash (e.g. triggered by signal SIGSEGV) is expected in testing, you 836can avoid creation of core files by calling 'tst_no_corefile()' function. 837This takes effect for process (and its children) which invoked it, unless 838they subsequently modify RLIMIT_CORE. 839 840Note that LTP library will reap any processes that test didn't reap itself, 841and report any non-zero exit code as failure. 842 8431.11 Kernel Modules 844~~~~~~~~~~~~~~~~~~~ 845 846There are certain cases where the test needs a kernel part and userspace part, 847happily, LTP can build a kernel module and then insert it to the kernel on test 848start for you. See 'testcases/kernel/device-drivers/block' for details. 849 8501.12 Useful macros 851~~~~~~~~~~~~~~~~~~ 852 853These macros are defined in 'include/tst_common.h'. 854 855[source,c] 856------------------------------------------------------------------------------- 857ARRAY_SIZE(arr) 858------------------------------------------------------------------------------- 859 860Returns the size of statically defined array, i.e. 861'(sizeof(arr) / sizeof(*arr))' 862 863[source,c] 864------------------------------------------------------------------------------- 865LTP_ALIGN(x, a) 866------------------------------------------------------------------------------- 867 868Aligns the x to be next multiple of a. The a must be power of 2. 869 870[source,c] 871------------------------------------------------------------------------------- 872TST_TO_STR(s) /* stringification */ 873TST_TO_STR_(s) /* macro expansion */ 874------------------------------------------------------------------------------- 875 876Macros for stringification. 877 8781.13 Filesystem type detection and skiplist 879~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 880 881Some tests are known to fail on certain filesystems (you cannot swap on TMPFS, 882there are unimplemented 'fcntl()' etc.). 883 884If your test needs to be skipped on certain filesystems use the 885'.skip_filesystems' field in the tst_test structure as follows: 886 887[source,c] 888------------------------------------------------------------------------------- 889#include "tst_test.h" 890 891static struct tst_test test = { 892 ... 893 .skip_filesystems = (const char *const []) { 894 "tmpfs", 895 "ramfs", 896 "nfs", 897 NULL 898 }, 899}; 900------------------------------------------------------------------------------- 901 902When the '.all_filesystems' flag is set the '.skip_filesystems' list is passed 903to the function that detects supported filesystems any listed filesystem is 904not included in the resulting list of supported filesystems. 905 906If test needs to adjust expectations based on filesystem type it's also 907possible to detect filesystem type at the runtime. This is preferably used 908when only subset of the test is not applicable for a given filesystem. 909 910NOTE: ext2, ext3 or ext4 in '.skip_filesystems' on tests which does *not* use 911 '.all_filesystems' needs to be defined as 'ext2/ext3/ext4'. The reason 912 is that it is hard to detect used filesystem due to overlapping the functionality. 913 OTOH tests which use '.skip_filesystems' *with* '.all_filesystems' can skip 914 only filesystems which are actually used in '.all_filesystems': ext2, ext3, 915 ext4, xfs, btrfs, vfat, exfat, ntfs, tmpfs (defined in 'fs_type_whitelist[]'). 916 It does not make sense to list other filesystems. 917 918 919[source,c] 920------------------------------------------------------------------------------- 921#include "tst_test.h" 922 923static void run(void) 924{ 925 ... 926 927 switch ((type = tst_fs_type("."))) { 928 case TST_NFS_MAGIC: 929 case TST_TMPFS_MAGIC: 930 case TST_RAMFS_MAGIC: 931 tst_brk(TCONF, "Subtest not supported on %s", 932 tst_fs_type_name(type)); 933 return; 934 break; 935 } 936 937 ... 938} 939------------------------------------------------------------------------------- 940 9411.14 Thread-safety in the LTP library 942~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 943 944It is safe to use library 'tst_res()' function in multi-threaded tests. 945 946Only the main thread must return from the 'test()' function to the test 947library and that must be done only after all threads that may call any library 948function has been terminated. That especially means that threads that may call 949'tst_brk()' must terminate before the execution of the 'test()' function 950returns to the library. This is usually done by the main thread joining all 951worker threads at the end of the 'test()' function. Note that the main thread 952will never get to the library code in a case that 'tst_brk()' was called from 953one of the threads since it will sleep at least in 'pthread_join()' on the 954thread that called the 'tst_brk()' till 'exit()' is called by 'tst_brk()'. 955 956The test-supplied cleanup function runs *concurrently* to the rest of the 957threads in a case that cleanup was entered from 'tst_brk()'. Subsequent 958threads entering 'tst_brk()' must be suspended or terminated at the start of 959the user supplied cleanup function. It may be necessary to stop or exit 960the rest of the threads before the test cleans up as well. For example threads 961that create new files should be stopped before temporary directory is be 962removed. 963 964Following code example shows thread safe cleanup function example using atomic 965increment as a guard. The library calls its cleanup after the execution returns 966from the user supplied cleanup and expects that only one thread returns from 967the user supplied cleanup to the test library. 968 969[source,c] 970------------------------------------------------------------------------------- 971#include "tst_test.h" 972 973static void cleanup(void) 974{ 975 static int flag; 976 977 if (tst_atomic_inc(&flag) != 1) 978 pthread_exit(NULL); 979 980 /* if needed stop the rest of the threads here */ 981 982 ... 983 984 /* then do cleanup work */ 985 986 ... 987 988 /* only one thread returns to the library */ 989} 990------------------------------------------------------------------------------- 991 992 9931.15 Testing with a block device 994~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 995 996Some tests needs a block device (inotify tests, syscall 'EROFS' failures, 997etc.). LTP library contains a code to prepare a testing device. 998 999If '.needs_device' flag in the 'struct tst_test' is set the 'tst_device' 1000structure is initialized with a path to a test device and default filesystem 1001to be used. 1002 1003You can also request minimal device size in megabytes by setting 1004'.dev_min_size' the device is guaranteed to have at least the requested size 1005then. 1006 1007If '.format_device' flag is set the device is formatted with a filesystem as 1008well. You can use '.dev_fs_type' to override the default filesystem type if 1009needed and pass additional options to mkfs via '.dev_fs_opts' and 1010'.dev_extra_opts' pointers. Note that '.format_device' implies '.needs_device' 1011there is no need to set both. 1012 1013If '.mount_device' is set, the device is mounted at '.mntpoint' which is used 1014to pass a directory name that will be created and used as mount destination. 1015You can pass additional flags and data to the mount command via '.mnt_flags' 1016and '.mnt_data' pointers. Note that '.mount_device' implies '.needs_device' 1017and '.format_device' so there is no need to set the later two. 1018 1019If '.needs_rofs' is set, read-only filesystem is mounted at '.mntpoint' this 1020one is supposed to be used for 'EROFS' tests. 1021 1022If '.all_filesystems' is set the test function is executed for all supported 1023filesystems. Supported filesystems are detected based on existence of the 1024'mkfs.$fs' helper and on kernel support to mount it. For each supported 1025filesystem the 'tst_device.fs_type' is set to the currently tested fs type, if 1026'.format_device' is set the device is formatted as well, if '.mount_device' is 1027set it's mounted at '.mntpoint'. Also the test timeout is reset for each 1028execution of the test function. This flag is expected to be used for filesystem 1029related syscalls that are at least partly implemented in the filesystem 1030specific code e.g. 'fallocate()'. 1031 1032[source,c] 1033------------------------------------------------------------------------------- 1034#include "tst_test.h" 1035 1036struct tst_device { 1037 const char *dev; 1038 const char *fs_type; 1039}; 1040 1041extern struct tst_device *tst_device; 1042 1043int tst_umount(const char *path); 1044------------------------------------------------------------------------------- 1045 1046In case that 'LTP_DEV' is passed to the test in an environment, the library 1047checks that the file exists and that it's a block device, if 1048'.device_min_size' is set the device size is checked as well. If 'LTP_DEV' 1049wasn't set or if size requirements were not met a temporary file is created 1050and attached to a free loop device. 1051 1052If there is no usable device and loop device couldn't be initialized the test 1053exits with 'TCONF'. 1054 1055The 'tst_umount()' function works exactly as 'umount(2)' but retries several 1056times on 'EBUSY'. This is because various desktop daemons (gvfsd-trash is known 1057for that) may be stupid enough to probe all newly mounted filesystem which 1058results in 'umount(2)' failing with 'EBUSY'. 1059 1060IMPORTANT: All testcases should use 'tst_umount()' instead of 'umount(2)' to 1061 umount filesystems. 1062 1063[source,c] 1064------------------------------------------------------------------------------- 1065#include "tst_test.h" 1066 1067int tst_find_free_loopdev(const char *path, size_t path_len); 1068------------------------------------------------------------------------------- 1069 1070This function finds a free loopdev and returns the free loopdev minor (-1 for no 1071free loopdev). If path is non-NULL, it will be filled with free loopdev path. 1072If you want to use a customized loop device, we can call 'tst_find_free_loopdev(NULL, 0)' 1073in tests to get a free minor number and then mknod. 1074 1075[source,c] 1076------------------------------------------------------------------------------- 1077#include "tst_test.h" 1078 1079unsigned long tst_dev_bytes_written(const char *dev); 1080------------------------------------------------------------------------------- 1081 1082This function reads test block device stat file ('/sys/block/<device>/stat') and 1083returns the bytes written since the last invocation of this function. To avoid 1084FS deferred IO metadata/cache interference, we suggest doing "syncfs" before the 1085tst_dev_bytes_written first invocation. And an inline function named 'tst_dev_sync()' 1086is created for that intention. 1087 1088[source,c] 1089------------------------------------------------------------------------------- 1090#include "tst_test.h" 1091 1092void tst_find_backing_dev(const char *path, char *dev, size_t dev_size); 1093------------------------------------------------------------------------------- 1094 1095This function finds the block dev that this path belongs to, using uevent in sysfs. 1096For Btrfs it uses '/sys/fs/btrfs/UUID/devices/DEV_NAME/uevent'; for other 1097filesystems it uses '/sys/dev/block/MAJOR:MINOR/uevent'. 1098 1099[source,c] 1100------------------------------------------------------------------------------- 1101#include "tst_test.h" 1102 1103uint64_t tst_get_device_size(const char *dev_path); 1104------------------------------------------------------------------------------- 1105 1106This function gets size of the given block device, it checks the 'dev_path' is 1107valid first, if yes, return the size in MB, otherwise return -1. 1108 1109[source,c] 1110------------------------------------------------------------------------------- 1111#include "tst_test.h" 1112 1113int tst_dev_block_size(const char *path); 1114------------------------------------------------------------------------------- 1115 1116This function returns the physical device block size for the specific `path`. 1117It finds the device where `path` is located and then uses `ioctl` (BLKSSZGET) 1118to get a physical device block size. 1119 11201.16 Formatting a device with a filesystem 1121~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1122 1123[source,c] 1124------------------------------------------------------------------------------- 1125#include "tst_test.h" 1126 1127static void setup(void) 1128{ 1129 ... 1130 SAFE_MKFS(tst_device->dev, tst_device->fs_type, NULL, NULL); 1131 ... 1132} 1133------------------------------------------------------------------------------- 1134 1135This function takes a path to a device, filesystem type and an array of extra 1136options passed to mkfs. 1137 1138The fs options 'fs_opts' should either be 'NULL' if there are none, or a 1139'NULL' terminated array of strings such as: 1140+const char *const opts[] = {"-b", "1024", NULL}+. 1141 1142The extra options 'extra_opts' should either be 'NULL' if there are none, or a 1143'NULL' terminated array of strings such as +{"102400", NULL}+; 'extra_opts' 1144will be passed after device name. e.g: +mkfs -t ext4 -b 1024 /dev/sda1 102400+ 1145in this case. 1146 1147Note that perfer to store the options which can be passed before or after device 1148name by 'fs_opts' array. 1149 11501.17 Verifying a filesystem's free space 1151~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1152 1153Some tests have size requirements for the filesystem's free space. If these 1154requirements are not satisfied, the tests should be skipped. 1155 1156[source,c] 1157------------------------------------------------------------------------------- 1158#include "tst_test.h" 1159 1160int tst_fs_has_free(const char *path, unsigned int size, unsigned int mult); 1161------------------------------------------------------------------------------- 1162 1163The 'tst_fs_has_free()' function returns 1 if there is enough space and 0 if 1164there is not. 1165 1166The 'path' is the pathname of any directory/file within a filesystem. 1167 1168The 'mult' is a multiplier, one of 'TST_BYTES', 'TST_KB', 'TST_MB' or 'TST_GB'. 1169 1170The required free space is calculated by 'size * mult', e.g. 1171'tst_fs_has_free("/tmp/testfile", 64, TST_MB)' will return 1 if the 1172filesystem, which '"/tmp/testfile"' is in, has 64MB free space at least, and 0 1173if not. 1174 11751.18 Files, directories and fs limits 1176~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1177 1178Some tests need to know the maximum count of links to a regular file or 1179directory, such as 'rename(2)' or 'linkat(2)' to test 'EMLINK' error. 1180 1181[source,c] 1182------------------------------------------------------------------------------- 1183#include "tst_test.h" 1184 1185int tst_fs_fill_hardlinks(const char *dir); 1186------------------------------------------------------------------------------- 1187 1188Try to get maximum count of hard links to a regular file inside the 'dir'. 1189 1190NOTE: This number depends on the filesystem 'dir' is on. 1191 1192This function uses 'link(2)' to create hard links to a single file until it 1193gets 'EMLINK' or creates 65535 links. If the limit is hit, the maximum number of 1194hardlinks is returned and the 'dir' is filled with hardlinks in format 1195"testfile%i", where i belongs to [0, limit) interval. If no limit is hit or if 1196'link(2)' failed with 'ENOSPC' or 'EDQUOT', zero is returned and previously 1197created files are removed. 1198 1199[source,c] 1200------------------------------------------------------------------------------- 1201#include "tst_test.h" 1202 1203int tst_fs_fill_subdirs(const char *dir); 1204------------------------------------------------------------------------------- 1205 1206Try to get maximum number of subdirectories in directory. 1207 1208NOTE: This number depends on the filesystem 'dir' is on. For current kernel, 1209subdir limit is not available for all filesystems (available for ext2, ext3, 1210minix, sysv and more). If the test runs on some other filesystems, like ramfs, 1211tmpfs, it will not even try to reach the limit and return 0. 1212 1213This function uses 'mkdir(2)' to create directories in 'dir' until it gets 1214'EMLINK' or creates 65535 directories. If the limit is hit, the maximum number 1215of subdirectories is returned and the 'dir' is filled with subdirectories in 1216format "testdir%i", where i belongs to [0, limit - 2) interval (because each 1217newly created dir has two links already - the '.' and the link from parent 1218dir). If no limit is hit or if 'mkdir(2)' failed with 'ENOSPC' or 'EDQUOT', 1219zero is returned and previously created directories are removed. 1220 1221[source,c] 1222------------------------------------------------------------------------------- 1223#include "tst_test.h" 1224 1225int tst_dir_is_empty(const char *dir, int verbose); 1226------------------------------------------------------------------------------- 1227 1228Returns non-zero if directory is empty and zero otherwise. 1229 1230Directory is considered empty if it contains only '.' and '..'. 1231 1232[source,c] 1233------------------------------------------------------------------------------- 1234#include "tst_test.h" 1235 1236void tst_purge_dir(const char *path); 1237------------------------------------------------------------------------------- 1238 1239Deletes the contents of given directory but keeps the directory itself. Useful 1240for cleaning up the temporary directory and mount points between test cases or 1241test iterations. Terminates the program with 'TBROK' on error. 1242 1243[source,c] 1244------------------------------------------------------------------------------- 1245#include "tst_test.h" 1246 1247int tst_fill_fd(int fd, char pattern, size_t bs, size_t bcount); 1248------------------------------------------------------------------------------- 1249 1250Fill a file with specified pattern using file descriptor. 1251 1252[source,c] 1253------------------------------------------------------------------------------- 1254#include "tst_test.h" 1255 1256int tst_prealloc_size_fd(int fd, size_t bs, size_t bcount); 1257------------------------------------------------------------------------------- 1258 1259Preallocate the specified amount of space using 'fallocate()'. Falls back to 1260'tst_fill_fd()' if 'fallocate()' fails. 1261 1262[source,c] 1263------------------------------------------------------------------------------- 1264#include "tst_test.h" 1265 1266int tst_fill_file(const char *path, char pattern, size_t bs, size_t bcount); 1267------------------------------------------------------------------------------- 1268 1269Creates/overwrites a file with specified pattern using file path. 1270 1271[source,c] 1272------------------------------------------------------------------------------- 1273#include "tst_test.h" 1274 1275int tst_prealloc_file(const char *path, size_t bs, size_t bcount); 1276------------------------------------------------------------------------------- 1277 1278Create/overwrite a file and preallocate the specified amount of space for it. 1279The allocated space will not be initialized to any particular content. 1280 12811.19 Getting an unused PID number 1282~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1283 1284Some tests require a 'PID', which is not used by the OS (does not belong to 1285any process within it). For example, kill(2) should set errno to 'ESRCH' if 1286it's passed such 'PID'. 1287 1288[source,c] 1289------------------------------------------------------------------------------- 1290#include "tst_test.h" 1291 1292pid_t tst_get_unused_pid(void); 1293------------------------------------------------------------------------------- 1294 1295Return a 'PID' value not used by the OS or any process within it. 1296 1297[source,c] 1298------------------------------------------------------------------------------- 1299#include "tst_test.h" 1300 1301int tst_get_free_pids(void); 1302------------------------------------------------------------------------------- 1303 1304Returns number of unused pids in the system. Note that this number may be 1305different once the call returns and should be used only for rough estimates. 1306 13071.20 Running executables 1308~~~~~~~~~~~~~~~~~~~~~~~~ 1309 1310[source,c] 1311------------------------------------------------------------------------------- 1312#include "tst_test.h" 1313 1314int tst_cmd(const char *const argv[], 1315 const char *stdout_path, 1316 const char *stderr_path, 1317 enum tst_cmd_flags flags); 1318------------------------------------------------------------------------------- 1319 1320'tst_cmd()' is a wrapper for 'vfork() + execvp()' which provides a way 1321to execute an external program. 1322 1323'argv[]' is a 'NULL' terminated array of strings starting with the program name 1324which is followed by optional arguments. 1325 1326'TST_CMD_PASS_RETVAL' enum 'tst_cmd_flags' makes 'tst_cmd()' 1327return the program exit code to the caller, otherwise 'tst_cmd()' exit the 1328tests on failure. 'TST_CMD_TCONF_ON_MISSING' check for program in '$PATH' and exit 1329with 'TCONF' if not found. 1330 1331In case that 'execvp()' has failed and the enum 'TST_CMD_PASS_RETVAL' flag was set, the 1332return value is '255' if 'execvp()' failed with 'ENOENT' and '254' otherwise. 1333 1334'stdout_path' and 'stderr_path' determine where to redirect the program 1335stdout and stderr I/O streams. 1336 1337'SAFE_CMD()' is a wrapper for 'tst_cmd()' which can be used for automatic 1338handling non-zero exit (exits with 'TBROK') and 'ENOENT' (the program not in 1339'$PATH', exits with 'TCONF'). 1340 1341.Example 1342[source,c] 1343------------------------------------------------------------------------------- 1344#include "tst_test.h" 1345 1346const char *const cmd[] = { "ls", "-l", NULL }; 1347 1348... 1349 /* Store output of 'ls -l' into log.txt */ 1350 tst_cmd(cmd, "log.txt", NULL, 0); 1351... 1352------------------------------------------------------------------------------- 1353 13541.21 Measuring elapsed time and helper functions 1355~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1356 1357[source,c] 1358------------------------------------------------------------------------------- 1359#include "tst_timer.h" 1360 1361void tst_timer_check(clockid_t clk_id); 1362 1363void tst_timer_start(clockid_t clk_id); 1364 1365void tst_timer_stop(void); 1366 1367struct timespec tst_timer_elapsed(void); 1368 1369long long tst_timer_elapsed_ms(void); 1370 1371long long tst_timer_elapsed_us(void); 1372 1373int tst_timer_expired_ms(long long ms); 1374------------------------------------------------------------------------------- 1375 1376The 'tst_timer_check()' function checks if specified 'clk_id' is supported and 1377exits the test with 'TCONF' otherwise. It's expected to be used in test 1378'setup()' before any resources that needs to be cleaned up are initialized, 1379hence it does not include a cleanup function parameter. 1380 1381The 'tst_timer_start()' marks start time and stores the 'clk_id' for further 1382use. 1383 1384The 'tst_timer_stop()' marks the stop time using the same 'clk_id' as last 1385call to 'tst_timer_start()'. 1386 1387The 'tst_timer_elapsed*()' returns time difference between the timer start and 1388last timer stop in several formats and units. 1389 1390The 'tst_timer_expired_ms()' function checks if the timer started by 1391'tst_timer_start()' has been running longer than ms milliseconds. The function 1392returns non-zero if timer has expired and zero otherwise. 1393 1394IMPORTANT: The timer functions use 'clock_gettime()' internally which needs to 1395 be linked with '-lrt' on older glibc. Please do not forget to add 1396 'LDLIBS+=-lrt' in Makefile. 1397 1398[source,c] 1399------------------------------------------------------------------------------- 1400#include "tst_test.h" 1401#include "tst_timer.h" 1402 1403static void setup(void) 1404{ 1405 ... 1406 tst_timer_check(CLOCK_MONOTONIC); 1407 ... 1408} 1409 1410static void run(void) 1411{ 1412 ... 1413 tst_timer_start(CLOCK_MONOTONIC); 1414 ... 1415 while (!tst_timer_expired_ms(5000)) { 1416 ... 1417 } 1418 ... 1419} 1420 1421struct tst_test test = { 1422 ... 1423 .setup = setup, 1424 .test_all = run, 1425 ... 1426}; 1427------------------------------------------------------------------------------- 1428 1429Expiration timer example usage. 1430 1431[source,c] 1432------------------------------------------------------------------------------- 1433long long tst_timespec_to_us(struct timespec t); 1434long long tst_timespec_to_ms(struct timespec t); 1435 1436struct timeval tst_us_to_timeval(long long us); 1437struct timeval tst_ms_to_timeval(long long ms); 1438 1439int tst_timespec_lt(struct timespec t1, struct timespec t2); 1440 1441struct timespec tst_timespec_add_us(struct timespec t, long long us); 1442 1443struct timespec tst_timespec_diff(struct timespec t1, struct timespec t2); 1444long long tst_timespec_diff_us(struct timespec t1, struct timespec t2); 1445long long tst_timespec_diff_ms(struct timespec t1, struct timespec t2); 1446 1447struct timespec tst_timespec_abs_diff(struct timespec t1, struct timespec t2); 1448long long tst_timespec_abs_diff_us(struct timespec t1, struct timespec t2); 1449long long tst_timespec_abs_diff_ms(struct timespec t1, struct timespec t2); 1450------------------------------------------------------------------------------- 1451 1452The first four functions are simple inline conversion functions. 1453 1454The 'tst_timespec_lt()' function returns non-zero if 't1' is earlier than 1455't2'. 1456 1457The 'tst_timespec_add_us()' function adds 'us' microseconds to the timespec 1458't'. The 'us' is expected to be positive. 1459 1460The 'tst_timespec_diff*()' functions returns difference between two times, the 1461't1' is expected to be later than 't2'. 1462 1463The 'tst_timespec_abs_diff*()' functions returns absolute value of difference 1464between two times. 1465 1466NOTE: All conversions to ms and us rounds the value. 1467 14681.22 Datafiles 1469~~~~~~~~~~~~~~ 1470 1471[source,c] 1472------------------------------------------------------------------------------- 1473#include "tst_test.h" 1474 1475static const char *const res_files[] = { 1476 "foo", 1477 "bar", 1478 NULL 1479}; 1480 1481static struct tst_test test = { 1482 ... 1483 .resource_files = res_files, 1484 ... 1485} 1486------------------------------------------------------------------------------- 1487 1488If the test needs additional files to be copied to the test temporary 1489directory all you need to do is to list their filenames in the 1490'NULL' terminated array '.resource_files' in the tst_test structure. 1491 1492When resource files is set test temporary directory is created automatically, 1493there is need to set '.needs_tmpdir' as well. 1494 1495The test library looks for datafiles first, these are either stored in a 1496directory called +datafiles+ in the +$PWD+ at the start of the test or in 1497+$LTPROOT/testcases/data/${test_binary_name}+. If the file is not found the 1498library looks into +$LTPROOT/testcases/bin/+ and to +$PWD+ at the start of the 1499test. This ensures that the testcases can copy the file(s) effortlessly both 1500when test is started from the directory it was compiled in as well as when LTP 1501was installed. 1502 1503The file(s) are copied to the newly created test temporary directory which is 1504set as the test working directory when the 'test()' functions is executed. 1505 15061.23 Code path tracing 1507~~~~~~~~~~~~~~~~~~~~~~ 1508 1509'tst_res' is a macro, so on when you define a function in one file: 1510 1511[source,c] 1512------------------------------------------------------------------------------- 1513int do_action(int arg) 1514{ 1515 ... 1516 1517 if (ok) { 1518 tst_res(TPASS, "check passed"); 1519 return 0; 1520 } else { 1521 tst_res(TFAIL, "check failed"); 1522 return -1; 1523 } 1524} 1525------------------------------------------------------------------------------- 1526 1527and call it from another file, the file and line reported by 'tst_res' in this 1528function will be from the former file. 1529 1530'TST_TRACE' can make the analysis of such situations easier. It's a macro which 1531inserts a call to 'tst_res(TINFO, ...)' in case its argument evaluates to 1532non-zero. In this call to 'tst_res(TINFO, ...)' the file and line will be 1533expanded using the actual location of 'TST_TRACE'. 1534 1535For example, if this another file contains: 1536 1537[source,c] 1538------------------------------------------------------------------------------- 1539#include "tst_test.h" 1540 1541if (TST_TRACE(do_action(arg))) { 1542 ... 1543} 1544------------------------------------------------------------------------------- 1545 1546the generated output may look similar to: 1547 1548------------------------------------------------------------------------------- 1549common.h:9: FAIL: check failed 1550test.c:8: INFO: do_action(arg) failed 1551------------------------------------------------------------------------------- 1552 15531.24 Tainted kernels 1554~~~~~~~~~~~~~~~~~~~~ 1555 1556If you need to detect whether a testcase triggers a kernel warning, bug or 1557oops, the following can be used to detect TAINT_W or TAINT_D: 1558 1559[source,c] 1560------------------------------------------------------------------------------- 1561#include "tst_test.h" 1562 1563static struct tst_test test = { 1564 ... 1565 .taint_check = TST_TAINT_W | TST_TAINT_D, 1566 ... 1567}; 1568 1569void run(void) 1570{ 1571 ... 1572 if (tst_taint_check() != 0) 1573 tst_res(TFAIL, "kernel has issues"); 1574 else 1575 tst_res(TPASS, "kernel seems to be fine"); 1576} 1577------------------------------------------------------------------------------- 1578 1579To initialize taint checks, you have to set the taint flags you want to test 1580for in the 'taint_check' attribute of the tst_test struct. LTP library will 1581then automatically call 'tst_taint_init()' during test setup. The function 1582will generate a 'TCONF' if the requested flags are not fully supported on the 1583running kernel, and 'TBROK' if the kernel is already tainted before executing 1584the test. 1585 1586LTP library will then automatically check kernel taint at the end of testing. 1587If '.all_filesystems' is set in struct tst_test, taint check will be performed 1588after each file system and taint will abort testing early with 'TFAIL'. You 1589can optionally also call 'tst_taint_check()' during 'run()', which returns 0 1590or the tainted flags set in '/proc/sys/kernel/tainted' as specified earlier. 1591 1592Depending on your kernel version, not all tainted-flags will be supported. 1593 1594For reference to tainted kernels, see kernel documentation: 1595Documentation/admin-guide/tainted-kernels.rst or 1596https://www.kernel.org/doc/html/latest/admin-guide/tainted-kernels.html 1597 15981.25 Checksums 1599~~~~~~~~~~~~~~ 1600 1601CRC32c checksum generation is supported by LTP. In order to use it, the 1602test should include 'tst_checksum.h' header, then can call 'tst_crc32c()'. 1603 16041.26 Checking kernel for the driver support 1605~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1606 1607Some tests may need specific kernel drivers, either compiled in, or built 1608as a module. If '.needs_drivers' points to a 'NULL' terminated array of kernel 1609module names these are all checked and the test exits with 'TCONF' on the 1610first missing driver. 1611 1612The detection is based on reading 'modules.dep' and 'modules.builtin' files 1613generated by kmod. The check is skipped on Android. 1614 16151.27 Saving & restoring /proc|sys values 1616~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1617 1618LTP library can be instructed to save and restore value of specified 1619(/proc|sys) files. This is achieved by initialized tst_test struct 1620field 'save_restore'. It is a NULL-terminated array of struct 1621'tst_path_val' where each tst_path_val.path represents a file, whose 1622value is saved at the beginning and restored at the end of the test. 1623If non-NULL string is passed in tst_path_val.val, it is written 1624to the respective file at the beginning of the test. Only the first line 1625of a specified file is saved and restored. 1626 1627By default, the test will end with TCONF if the file is read-only or 1628does not exist. If the optional write of new value fails, the test will end 1629with 'TBROK'. This behavior can be changed using tst_path_val.flags: 1630 1631* 'TST_SR_TBROK_MISSING' – End test with 'TBROK' if the file does not exist 1632* 'TST_SR_TCONF_MISSING' – End test with 'TCONF' if the file does not exist 1633* 'TST_SR_SKIP_MISSING' – Continue without saving the file if it does not exist 1634* 'TST_SR_TBROK_RO' – End test with 'TBROK' if the file is read-only 1635* 'TST_SR_TCONF_RO' – End test with 'TCONF' if the file is read-only 1636* 'TST_SR_SKIP_RO' – Continue without saving the file if it is read-only 1637* 'TST_SR_IGNORE_ERR' – Ignore errors when writing new value into the file 1638 1639Common flag combinations also have shortcuts: 1640 1641* 'TST_SR_TCONF' – Equivalent to 'TST_SR_TCONF_MISSING | TST_SR_TCONF_RO' 1642* 'TST_SR_TBROK' – Equivalent to 'TST_SR_TBROK_MISSING | TST_SR_TBROK_RO' 1643* 'TST_SR_SKIP' – Equivalent to 'TST_SR_SKIP_MISSING | TST_SR_SKIP_RO' 1644 1645'restore' is always strict and will TWARN if it encounters any error. 1646 1647[source,c] 1648------------------------------------------------------------------------------- 1649static struct tst_test test = { 1650 ... 1651 .setup = setup, 1652 .save_restore = (const struct tst_path_val[]) { 1653 {"/proc/sys/kernel/core_pattern", NULL, TST_SR_TCONF}, 1654 {"/proc/sys/user/max_user_namespaces", NULL, TST_SR_SKIP}, 1655 {"/sys/kernel/mm/ksm/run", "1", TST_SR_TBROK}, 1656 {} 1657 }, 1658}; 1659------------------------------------------------------------------------------- 1660 16611.28 Parsing kernel .config 1662~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1663 1664Generally testcases should attempt to autodetect as much kernel features as 1665possible based on the currently running kernel. We do have tst_check_driver() 1666to check if functionality that could be compiled as kernel module is present 1667on the system, disabled syscalls can be detected by checking for 'ENOSYS' 1668errno etc. 1669 1670However in rare cases core kernel features couldn't be detected based on the 1671kernel userspace API and we have to resort to parse the kernel .config. 1672 1673For this cases the test should set the 'NULL' terminated '.needs_kconfigs' 1674array of boolean expressions with constraints on the kconfig variables. The 1675boolean expression consits of variables, two binary operations '&' and '|', 1676negation '!' and correct sequence of parentesis '()'. Variables are expected 1677to be in a form of "CONFIG_FOO[=bar]". 1678 1679The test will continue to run if all expressions are evaluated to 'True'. 1680Missing variable is mapped to 'False' as well as variable with different than 1681specified value, e.g. 'CONFIG_FOO=bar' will evaluate to 'False' if the value 1682is anything else but 'bar'. If config variable is specified as plain 1683'CONFIG_FOO' it's evaluated to true it's set to any value (typically =y or =m). 1684 1685[source,c] 1686------------------------------------------------------------------------------- 1687#include "tst_test.h" 1688 1689static const char *kconfigs[] = { 1690 "CONFIG_X86_INTEL_UMIP | CONFIG_X86_UMIP", 1691 NULL 1692}; 1693 1694static struct tst_test test = { 1695 ... 1696 .needs_kconfigs = kconfigs, 1697 ... 1698}; 1699------------------------------------------------------------------------------- 1700 17011.29 Changing the Wall Clock Time during test execution 1702~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1703 1704There are some tests that, for different reasons, might need to change the 1705system-wide clock time. Whenever this happens, it is imperative that the clock 1706is restored, at the end of test's execution, taking in consideration the amount 1707of time elapsed during that test. 1708 1709In order for that to happen, struct tst_test has a variable called 1710"restore_wallclock" that should be set to "1" so LTP knows it should: (1) 1711initialize a monotonic clock during test setup phase and (2) use that monotonic 1712clock to fix the system-wide clock time at the test cleanup phase. 1713 1714[source,c] 1715------------------------------------------------------------------------------- 1716#include "tst_test.h" 1717 1718static void setup(void) 1719{ 1720 ... 1721} 1722 1723static void run(void) 1724{ 1725 ... 1726} 1727 1728struct tst_test test = { 1729 ... 1730 .setup = setup, 1731 .test_all = run, 1732 .restore_wallclock = 1, 1733 ... 1734}; 1735------------------------------------------------------------------------------- 1736 17371.30 Testing similar syscalls in one test 1738~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1739 1740In some cases kernel has several very similar syscalls that do either the same 1741or very similar job. This is most noticeable on i386 where we commonly have 1742two or three syscall versions. That is because i386 was first platform that 1743Linux was developed on and because of that most mistakes in API happened there 1744as well. However this is not limited to i386 at all, it's quite common that 1745version two syscall has added missing flags parameters or so. 1746 1747In such cases it does not make much sense to copy&paste the test code over and 1748over, rather than that the test library provides support for test variants. 1749The idea behind test variants is simple, we run the test several times each 1750time with different syscall variant. 1751 1752The implementation consist of test_variants integer that, if set, denotes number 1753of test variants. The test is then forked and executed test_variants times each 1754time with different value in global tst_variant variable. 1755 1756[source,c] 1757------------------------------------------------------------------------------- 1758#include "tst_test.h" 1759 1760static int do_foo(void) 1761{ 1762 switch (tst_variant) { 1763 case 0: 1764 return foo(); 1765 case 1: 1766 return syscall(__NR_foo); 1767 } 1768 1769 return -1; 1770} 1771 1772static void run(void) 1773{ 1774 ... 1775 1776 TEST(do_foo); 1777 1778 ... 1779} 1780 1781static void setup(void) 1782{ 1783 switch (tst_variant) { 1784 case 0: 1785 tst_res(TINFO, "Testing foo variant 1"); 1786 break; 1787 case 1: 1788 tst_res(TINFO, "Testing foo variant 2"); 1789 break; 1790 } 1791} 1792 1793struct tst_test test = { 1794 ... 1795 .setup = setup, 1796 .test_all = run, 1797 .test_variants = 2, 1798 ... 1799}; 1800------------------------------------------------------------------------------- 1801 18021.31 Guarded buffers 1803~~~~~~~~~~~~~~~~~~~~ 1804 1805The test library supports guarded buffers, which are buffers allocated so 1806that: 1807 1808* The end of the buffer is followed by a PROT_NONE page 1809 1810* The remainder of the page before the buffer is filled with random canary 1811 data 1812 1813Which means that the any access after the buffer will yield a Segmentation 1814fault or EFAULT depending on if the access happened in userspace or the kernel 1815respectively. The canary before the buffer will also catch any write access 1816outside of the buffer. 1817 1818The purpose of the patch is to catch off-by-one bugs which happens when 1819buffers and structures are passed to syscalls. New tests should allocate 1820guarded buffers for all data passed to the tested syscall which are passed by 1821a pointer. 1822 1823[source,c] 1824------------------------------------------------------------------------------- 1825#include "tst_test.h" 1826 1827static struct foo *foo_ptr; 1828static struct iovec *iov; 1829static void *buf_ptr; 1830static char *id; 1831... 1832 1833static void run(void) 1834{ 1835 ... 1836 1837 foo_ptr->bar = 1; 1838 foo_ptr->buf = buf_ptr; 1839 1840 ... 1841} 1842 1843static void setup(void) 1844{ 1845 ... 1846 1847 id = tst_strdup(string); 1848 1849 ... 1850} 1851 1852static struct tst_test test = { 1853 ... 1854 .bufs = (struct tst_buffers []) { 1855 {&foo_ptr, .size = sizeof(*foo_ptr)}, 1856 {&buf_ptr, .size = BUF_SIZE}, 1857 {&iov, .iov_sizes = (int[]){128, 32, -1}, 1858 {} 1859 } 1860}; 1861------------------------------------------------------------------------------- 1862 1863Guarded buffers can be allocated on runtime in a test setup() by a 1864'tst_alloc()' or by 'tst_strdup()' as well as by filling up the .bufs array in 1865the tst_test structure. 1866 1867So far the tst_test structure supports allocating either a plain buffer by 1868setting up the size or struct iovec, which is allocated recursively including 1869the individual buffers as described by an '-1' terminated array of buffer 1870sizes. 1871 18721.32 Adding and removing capabilities 1873~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1874 1875Some tests may require the presence or absence of particular 1876capabilities. Using the API provided by 'tst_capability.h' the test author can 1877try to ensure that some capabilities are either present or absent during the 1878test. 1879 1880For example; below we try to create a raw socket, which requires 1881CAP_NET_ADMIN. During setup we should be able to do it, then during run it 1882should be impossible. The LTP capability library will check before setup that 1883we have this capability, then after setup it will drop it. 1884 1885[source,c] 1886-------------------------------------------------------------------------------- 1887#include "tst_test.h" 1888#include "tst_capability.h" 1889#include "tst_safe_net.h" 1890 1891#include "lapi/socket.h" 1892 1893static void run(void) 1894{ 1895 TEST(socket(AF_INET, SOCK_RAW, 1)); 1896 if (TST_RET > -1) { 1897 tst_res(TFAIL, "Created raw socket"); 1898 } else if (TST_ERR != EPERM) { 1899 tst_res(TFAIL | TTERRNO, 1900 "Failed to create socket for wrong reason"); 1901 } else { 1902 tst_res(TPASS | TTERRNO, "Didn't create raw socket"); 1903 } 1904} 1905 1906static void setup(void) 1907{ 1908 TEST(socket(AF_INET, SOCK_RAW, 1)); 1909 if (TST_RET < 0) 1910 tst_brk(TCONF | TTERRNO, "We don't have CAP_NET_RAW to begin with"); 1911 1912 SAFE_CLOSE(TST_RET); 1913} 1914 1915static struct tst_test test = { 1916 .setup = setup, 1917 .test_all = run, 1918 .caps = (struct tst_cap []) { 1919 TST_CAP(TST_CAP_REQ, CAP_NET_RAW), 1920 TST_CAP(TST_CAP_DROP, CAP_NET_RAW), 1921 {} 1922 }, 1923}; 1924-------------------------------------------------------------------------------- 1925 1926Look at the test struct at the bottom. We have filled in the 'caps' field with 1927a 'NULL' terminated array containing two 'tst_cap' structs. 'TST_CAP_REQ' 1928actions are executed before setup and 'TST_CAP_DROP' are executed after 1929setup. This means it is possible to both request and drop a capability. 1930 1931[source,c] 1932-------------------------------------------------------------------------------- 1933static struct tst_test test = { 1934 .test_all = run, 1935 .caps = (struct tst_cap []) { 1936 TST_CAP(TST_CAP_REQ, CAP_NET_RAW), 1937 TST_CAP(TST_CAP_DROP, CAP_SYS_ADMIN), 1938 {} 1939 }, 1940}; 1941-------------------------------------------------------------------------------- 1942 1943Here we request 'CAP_NET_RAW', but drop 'CAP_SYS_ADMIN'. If the capability is 1944in the permitted set, but not the effective set, the library will try to 1945permit it. If it is not in the permitted set, then it will fail with 'TCONF'. 1946 1947This API does not require 'libcap' to be installed. However it has limited 1948features relative to 'libcap'. It only tries to add or remove capabilities 1949from the effective set. This means that tests which need to spawn child 1950processes may have difficulties ensuring the correct capabilities are 1951available to the children (see the capabilities (7) manual pages). 1952 1953However a lot of problems can be solved by using 'tst_cap_action(struct 1954tst_cap *cap)' directly which can be called at any time. This also helps if 1955you wish to drop a capability at the beginning of setup. 1956 19571.33 Reproducing race-conditions 1958~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1959 1960If a bug is caused by two tasks in the kernel racing and you wish to create a 1961regression test (or bug-fix validation test) then the 'tst_fuzzy_sync.h' 1962library should be used. 1963 1964It allows you to specify, in your code, two race windows. One window in each 1965thread's loop (triggering a race usually requires many iterations). These 1966windows show fuzzy-sync where the race can happen. They don't need to be 1967exact, hence the 'fuzzy' part. If the race condition is not immediately 1968triggered then the library will begin experimenting with different timings. 1969 1970[source,c] 1971-------------------------------------------------------------------------------- 1972#include "tst_fuzzy_sync.h" 1973 1974static struct tst_fzsync_pair fzsync_pair; 1975 1976static void setup(void) 1977{ 1978 tst_fzsync_pair_init(&fzsync_pair); 1979} 1980 1981static void cleanup(void) 1982{ 1983 tst_fzsync_pair_cleanup(&fzsync_pair); 1984} 1985 1986static void *thread_b(void *arg) 1987{ 1988 while (tst_fzsync_run_b(&fzsync_pair)) { 1989 1990 tst_fzsync_start_race_b(&fzsync_pair); 1991 1992 /* This is the race window for thread B */ 1993 1994 tst_fzsync_end_race_b(&fzsync_pair); 1995 } 1996 1997 return arg; 1998} 1999 2000static void thread_a(void) 2001{ 2002 tst_fzsync_pair_reset(&fzsync_pair, thread_b); 2003 2004 while (tst_fzsync_run_a(&fzsync_pair)) { 2005 2006 tst_fzsync_start_race_a(&fzsync_pair); 2007 2008 /* This is the race window for thread A */ 2009 2010 tst_fzsync_end_race_a(&fzsync_pair); 2011 } 2012} 2013 2014static struct tst_test test = { 2015 .test_all = thread_a, 2016 .setup = setup, 2017 .cleanup = cleanup, 2018}; 2019-------------------------------------------------------------------------------- 2020 2021Above is a minimal template for a test using fuzzy-sync. In a simple case, you 2022just need to put the bits you want to race inbetween 'start_race' and 2023'end_race'. Meanwhile, any setup you need to do per-iteration goes outside the 2024windows. 2025 2026Fuzzy sync synchronises 'run_a' and 'run_b', which act as barriers, so that 2027neither thread can progress until the other has caught up with it. There is 2028also the 'pair_wait' function which can be used to add barriers in other 2029locations. Of course 'start/end_race_a/b' are also a barriers. 2030 2031The library decides how long the test should run for based on the timeout 2032specified by the user plus some other heuristics. 2033 2034For full documentation see the comments in 'include/tst_fuzzy_sync.h'. 2035 20361.34 Reserving hugepages 2037~~~~~~~~~~~~~~~~~~~~~~~~ 2038 2039Many of the LTP tests need to use hugepage in their testing, this allows the 2040test can reserve hugepages from system via '.hugepages = {xx, TST_REQUEST}'. 2041 2042We achieved two policies for reserving hugepages: 2043 2044TST_REQUEST: 2045 It will try the best to reserve available huge pages and return the number 2046 of available hugepages in tst_hugepages, which may be 0 if hugepages are 2047 not supported at all. 2048 2049TST_NEEDS: 2050 This is an enforced requirement, LTP should strictly do hpages applying and 2051 guarantee the 'HugePages_Free' no less than pages which makes that test can 2052 use these specified numbers correctly. Otherwise, test exits with TCONF if 2053 the attempt to reserve hugepages fails or reserves less than requested. 2054 2055With success test stores the reserved hugepage number in 'tst_hugepages'. For 2056system without hugetlb supporting, variable 'tst_hugepages' will be set to 0. 2057If the hugepage number needs to be set to 0 on supported hugetlb system, please 2058use '.hugepages = {TST_NO_HUGEPAGES}'. 2059 2060Also, we do cleanup and restore work for the hpages resetting automatically. 2061 2062[source,c] 2063------------------------------------------------------------------------------- 2064#include "tst_test.h" 2065 2066static void run(void) 2067{ 2068 ... 2069 2070 if (tst_hugepages == test.hugepages.number) 2071 TEST(do_hpage_test); 2072 else 2073 ... 2074 ... 2075} 2076 2077struct tst_test test = { 2078 .test_all = run, 2079 .hugepages = {2, TST_REQUEST}, 2080 ... 2081}; 2082------------------------------------------------------------------------------- 2083 2084or, 2085 2086[source,c] 2087------------------------------------------------------------------------------- 2088#include "tst_test.h" 2089 2090static void run(void) 2091{ 2092 ... 2093} 2094 2095static void setup(void) 2096{ 2097 /* TST_NEEDS achieved this automatically in the library */ 2098 if (tst_hugepages != test.hugepages.number) 2099 tst_brk(TCONF, "..."); 2100} 2101 2102struct tst_test test = { 2103 .test_all = run, 2104 .hugepages = {2, TST_NEEDS}, 2105 ... 2106}; 2107------------------------------------------------------------------------------- 2108 21091.35 Checking for required commands 2110~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2111 2112Required commands can be checked with '.needs_cmds', which points to a 'NULL' 2113terminated array of strings such as: 2114 2115[source,c] 2116------------------------------------------------------------------------------- 2117.needs_cmds = (const char *const []) { 2118 "useradd", 2119 "userdel", 2120 NULL 2121}, 2122------------------------------------------------------------------------------- 2123 2124Also can check required command version whether is satisfied by using 'needs_cmds' 2125such as: 2126 2127[source,c] 2128------------------------------------------------------------------------------- 2129.needs_cmds = (const char *const []) { 2130 "mkfs.ext4 >= 1.43.0", 2131 NULL 2132}, 2133------------------------------------------------------------------------------- 2134 2135Currently, we only support mkfs.ext4 command version check. 2136If you want to support more commands, please fill your own .parser and .table_get 2137method in the version_parsers structure of lib/tst_cmd.c. 2138 21391.36 Assert sys or proc file value 2140~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2141Using TST_ASSERT_INT/STR(path, val) to assert that integer value or string stored in 2142the prefix field of file pointed by path equals to the value passed to this function. 2143 2144Also having a similar api pair TST_ASSERT_FILE_INT/STR(path, prefix, val) to assert 2145the field value of file. 2146 21471.37 Using Control Group 2148~~~~~~~~~~~~~~~~~~~~~~~~ 2149 2150Some LTP tests need specific Control Group configurations. 'tst_cgroup.h' 2151provides APIs to discover and use CGroups. There are many differences between 2152CGroups API V1 and V2. We encapsulate the details of configuring CGroups in 2153high-level functions which follow the V2 kernel API where possible. Allowing one 2154to write code that works on both V1 or V2. At least some of the time anyway; 2155often the behavioural differences between V1 and V2 are too great. In such cases 2156we revert to branching on the CGroup version. 2157 2158Also, the LTP library will automatically mount/umount and configure the CGroup 2159hierarchies if that is required (e.g. if you run the tests from init with no 2160system manager). 2161 2162[source,c] 2163------------------------------------------------------------------------------- 2164#include "tst_test.h" 2165 2166static void run(void) 2167{ 2168 ... 2169 // do test under cgroup 2170 ... 2171} 2172 2173static void setup(void) 2174{ 2175 SAFE_CG_PRINTF(tst_cg, "cgroup.procs", "%d", getpid()); 2176 SAFE_CG_PRINTF(tst_cg, "memory.max", "%lu", MEMSIZE); 2177 if (SAFE_CG_HAS(tst_cg, "memory.swap.max")) 2178 SAFE_CG_PRINTF(tst_cg, "memory.swap.max", "%zu", memsw); 2179} 2180 2181struct tst_test test = { 2182 .setup = setup, 2183 .test_all = run, 2184 .cleanup = cleanup, 2185 .needs_cgroup_ctrls = (const char *const []){ "memory", NULL }, 2186 ... 2187}; 2188------------------------------------------------------------------------------- 2189 2190Above, we first ensure the memory controller is available on the 2191test's CGroup with '.needs_cgroup_ctrls'. This populates a structure, 2192'tst_cg', which represents the test's CGroup. 2193 2194We then write the current processes PID into 'cgroup.procs', which 2195moves the current process into the test's CGroup. After which we set 2196the maximum memory size by writing to 'memory.max'. If the memory 2197controller is mounted on CGroups V1 then the library will actually 2198write to 'memory.limit_in_bytes'. As a general rule, if a file exists 2199on both CGroup versions, then we use the V2 naming. 2200 2201Some controller features, such as 'memory.swap', can be 2202disabled. Therefor we need to check if they exist before accessing 2203them. This can be done with 'SAFE_CG_HAS' which can be called on 2204any control file or feature. 2205 2206Most tests only require setting a few limits similar to the above. In 2207such cases the differences between V1 and V2 are hidden. Setup and 2208cleanup is also mostly hidden. However things can get much worse. 2209 2210[source,c] 2211------------------------------------------------------------------------------- 2212static struct tst_cg_group *cg_child; 2213 2214static void run(void) 2215{ 2216 char buf[BUFSIZ]; 2217 size_t mem = 0; 2218 2219 cg_child = tst_cg_group_mk(tst_cg, "child"); 2220 SAFE_CG_PRINTF(cg_child, "cgroup.procs", "%d", getpid()); 2221 2222 if (!TST_CG_VER_IS_V1(tst_cg, "memory")) 2223 SAFE_CG_PRINT(tst_cg, "cgroup.subtree_control", "+memory"); 2224 if (!TST_CG_VER_IS_V1(tst_cg, "cpuset")) 2225 SAFE_CG_PRINT(tst_cg, "cgroup.subtree_control", "+cpuset"); 2226 2227 if (!SAFE_FORK()) { 2228 SAFE_CG_PRINTF(cg_child, "cgroup.procs", "%d", getpid()); 2229 2230 if (SAFE_CG_HAS(cg_child, "memory.swap")) { 2231 SAFE_CG_SCANF(cg_child, 2232 "memory.swap.current", "%zu", &mem); 2233 } 2234 SAFE_CG_READ(cg_child, "cpuset.mems", buf, sizeof(buf)); 2235 2236 // Do something with cpuset.mems and memory.current values 2237 ... 2238 2239 exit(0); 2240 } 2241 2242 tst_reap_children(); 2243 SAFE_CG_PRINTF(tst_cg_drain, "cgroup.procs", "%d", getpid()); 2244 cg_child = tst_cg_group_rm(cg_child); 2245} 2246 2247static void cleanup(void) 2248{ 2249 if (cg_child) { 2250 SAFE_CG_PRINTF(tst_cg_drain, "cgroup.procs", "%d", getpid()); 2251 cg_child = tst_cg_group_rm(cg_child); 2252 } 2253} 2254 2255struct tst_test test = { 2256 .setup = setup, 2257 .test_all = run, 2258 .needs_cgroup_ctrls = (const char *const []){ 2259 "cpuset", 2260 "memory", 2261 NULL 2262 }, 2263 ... 2264}; 2265------------------------------------------------------------------------------- 2266 2267Starting with setup; we can see here that we fetch the 'drain' 2268CGroup. This is a shared group (between parallel tests) which may 2269contain processes from other tests. It should have default settings 2270and these should not be changed by the test. It can be used to remove 2271processes from other CGroups incase the hierarchy root is not 2272accessible. 2273 2274Note that 'tst_cg_get_drain_group' should not be called many times, 2275as it is allocated in a guarded buffer (See section 2.2.31). Therefor 2276it is best to call it once in 'setup' and not 'run' because 'run' may 2277be repeated with the '-i' option. 2278 2279In 'run', we first create a child CGroup with 'tst_cg_mk'. As we 2280create this CGroup in 'run' we should also remove it at the end of 2281run. We also need to check if it exists and remove it in cleanup as 2282well. Because there are 'SAFE_' functions which may jump to cleanup. 2283 2284We then move the main test process into the child CGroup. This is 2285important as it means that before we destroy the child CGroup we have 2286to move the main test process elsewhere. For that we use the 'drain' 2287group. 2288 2289Next we enable the memory and cpuset controller configuration on the 2290test CGroup's descendants (i.e. 'cg_child'). This allows each child to 2291have its own settings. The file 'cgroup.subtree_control' does not 2292exist on V1. Because it is possible to have both V1 and V2 active at 2293the same time. We can not simply check if 'subtree_control' exists 2294before writing to it. We have to check if a particular controller is 2295on V2 before trying to add it to 'subtree_control'. Trying to add a V1 2296controller will result in 'ENOENT'. 2297 2298We then fork a child process and add this to the child CGroup. Within 2299the child process we try to read 'memory.swap.current'. It is possible 2300that the memory controller was compiled without swap support, so it is 2301necessary to check if 'memory.swap' is enabled. That is unless the 2302test will never reach the point where 'memory.swap.*' are used without 2303swap support. 2304 2305The parent process waits for the child process to be reaped before 2306destroying the child CGroup. So there is no need to transfer the child 2307to drain. However the parent process must be moved otherwise we will 2308get 'EBUSY' when trying to remove the child CGroup. 2309 2310Another example of a behavioral difference between versions is shown below. 2311 2312[source,c] 2313------------------------------------------------------------------------------- 2314 if (TST_CG_VER_IS_V1(tst_cg, "memory")) 2315 SAFE_CG_PRINTF(tst_cg, "memory.swap.max", "%lu", ~0UL); 2316 else 2317 SAFE_CG_PRINT(tst_cg, "memory.swap.max", "max"); 2318------------------------------------------------------------------------------- 2319 2320CGroups V2 introduced a feature where 'memory[.swap].max' could be set to 2321"max". This does not appear to work on V1 'limit_in_bytes' however. For most 2322tests, simply using a large number is sufficient and there is no need to use 2323"max". Importantly though, one should be careful to read both the V1 and V2 2324kernel docs. Presently the LTP library does not attempt to handle most 2325differences in semantics. It does the minimal amount of work to make testing on 2326both V1 and V2 feasible. 2327 23281.38 Require minimum numbers of CPU for a testcase 2329~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2330 2331Some tests require more than specific number of CPU. It can be defined with 2332`.min_cpus = N`. 2333 23341.39 Require minimum memory or swap size for a testcase 2335~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2336 2337Some tests require at least size(MB) of free RAM or Swap. 2338 2339To make sure that test will run only on systems with more than minimal 2340required amount of RAM set `.min_mem_avail = N`. 2341 2342Similarily for tests that require certain amount of free Swap use 2343`.min_swap_avail = N`. 2344 23451.40 Test tags 2346~~~~~~~~~~~~~~ 2347 2348Test tags are name-value pairs that can hold any test metadata. 2349 2350We have additional support for CVE entries, git commit in mainline kernel, 2351stable kernel or glibc git repository. If a test is a regression test it 2352should include these tags. They are printed when test fails and exported 2353into documentation. 2354 2355CVE, mainline and stable kernel git commits in a regression test for a kernel bug: 2356[source,c] 2357------------------------------------------------------------------------------- 2358struct tst_test test = { 2359 ... 2360 .tags = (const struct tst_tag[]) { 2361 {"linux-git", "9392a27d88b9"}, 2362 {"linux-git", "ff002b30181d"}, 2363 {"known-fail", "ustat() is known to fail with EINVAL on Btrfs"}, 2364 {"linux-stable-git", "c4a23c852e80"}, 2365 {"CVE", "2020-29373"}, 2366 {} 2367 } 2368}; 2369------------------------------------------------------------------------------- 2370 2371NOTE: We don't track all backports to stable kernel but just those which are 2372 stable branch specific (unique), i.e. no commit in mainline. Example of 2373 commits: c4a23c852e80, cac68d12c531. 2374 2375Glibc and musl git commits in a regression test for glibc and musl bugs: 2376[source,c] 2377------------------------------------------------------------------------------- 2378struct tst_test test = { 2379 ... 2380 .tags = (const struct tst_tag[]) { 2381 {"glibc-git", "574500a108be"}, 2382 {"musl-git", "fa4a8abd06a4"}, 2383 {} 2384 } 2385}; 2386------------------------------------------------------------------------------- 2387 23881.41 Testing on the specific architecture 2389~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2390Testcases for specific arch should be limited on that only being supported 2391platform to run, we now involve a '.supported_archs' to achieve this feature 2392in LTP library. All you need to run a test on the expected arch is to set 2393the '.supported_archs' array in the 'struct tst_test' to choose the required 2394arch list. e.g. 2395 2396 .supported_archs = (const char *const []){"x86_64", "ppc64", NULL} 2397 2398This helps move the TCONF info from code to tst_test metadata as well. 2399 2400And, we also export a struct tst_arch to save the system architecture for 2401using in the whole test cases. 2402 2403 extern const struct tst_arch { 2404 char name[16]; 2405 enum tst_arch_type type; 2406 } tst_arch; 2407 2408[source,c] 2409------------------------------------------------------------------------------- 2410#include "tst_test.h" 2411 2412static struct tst_test test = { 2413 ... 2414 .setup = setup, 2415 .supported_archs = (const char *const []) { 2416 "x86_64", 2417 "ppc64", 2418 "s390x", 2419 NULL 2420 }, 2421}; 2422------------------------------------------------------------------------------- 2423 24241.42 Skipping test based on system state 2425~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2426Test can be skipped on various conditions: on enabled SecureBoot 2427('.skip_in_secureboot = 1'), lockdown ('.skip_in_lockdown = 1') or in 32-bit 2428compat mode ('.skip_in_compat = 1'). 2429 24301.43 Set resource limits 2431~~~~~~~~~~~~~~~~~~~~~~~~ 2432 2433'.ulimit' allows to set resource limits on particular resource. NOTE: It sets 'rlim_max' 2434only if it's higher than 'rlim_cur'. 2435 2436[source,c] 2437------------------------------------------------------------------------------- 2438#include "tst_test.h" 2439 2440static struct tst_test test = { 2441 ... 2442 .ulimit = (const struct tst_ulimit_val[]) { 2443 {RLIMIT_STACK, RLIM_INFINITY}, 2444 {} 2445 }, 2446}; 2447------------------------------------------------------------------------------- 2448 24492. Common problems 2450------------------ 2451 2452This chapter describes common problems/misuses and less obvious design patters 2453(quirks) in UNIX interfaces. Read it carefully :) 2454 24552.1 umask() 2456~~~~~~~~~~~ 2457 2458I've been hit by this one several times already... When you create files 2459with 'open()' or 'creat()' etc, the mode specified as the last parameter *is 2460not* the mode the file is created with. The mode depends on current 'umask()' 2461settings which may clear some of the bits. If your test depends on specific 2462file permissions you need either to change umask to 0 or 'chmod()' the file 2463afterwards or use 'SAFE_TOUCH()' that does the 'chmod()' for you. 2464 24652.2 access() 2466~~~~~~~~~~~~ 2467 2468If 'access(some_file, W_OK)' is executed by root, it will return success even 2469if the file doesn't have write permission bits set (the same holds for R_OK 2470too). For sysfs files you can use 'open()' as a workaround to check file 2471read/write permissions. It might not work for other filesystems, for these you 2472have to use 'stat()', 'lstat()' or 'fstat()'. 2473 24742.3 umount() EBUSY 2475~~~~~~~~~~~~~~~~~~ 2476 2477Various desktop daemons (gvfsd-trash is known for that) may be stupid enough 2478to probe all newly mounted filesystem which results in 'umount(2)' failing 2479with 'EBUSY'; use 'tst_umount()' described in 1.19 that retries in this case 2480instead of plain 'umount(2)'. 2481 24822.4 FILE buffers and fork() 2483~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2484 2485Be vary that if a process calls 'fork(2)' the child process inherits open 2486descriptors as well as copy of the parent memory so especially if there are 2487any open 'FILE' buffers with a data in them they may be written both by the 2488parent and children resulting in corrupted/duplicated data in the resulting 2489files. 2490 2491Also open 'FILE' streams are flushed and closed at 'exit(3)' so if your 2492program works with 'FILE' streams, does 'fork(2)', and the child may end up 2493calling 'exit(3)' you will likely end up with corrupted files. 2494 2495The solution to this problem is either simply call 'fflush(NULL)' that flushes 2496all open output 'FILE' streams just before doing 'fork(2)'. You may also use 2497'_exit(2)' in child processes which does not flush 'FILE' buffers and also 2498skips 'atexit(3)' callbacks. 2499