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