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