1LTP Test Writing Guidelines 2=========================== 3 4This document describes LTP guidelines and LTP test interface and is intended 5for anybody who want to write or modify a LTP testcase. It's not a definitive 6guide and it's not, by any means, a substitute for common sense. 7 81. General Rules 9---------------- 10 111.1 Simplicity 12~~~~~~~~~~~~~~ 13 14For all it's worth keep the testcases simple or better as simple as possible. 15The kernel and libc are tricky beasts and the complexity imposed by their 16interfaces is quite high. Concentrate on the interface you want to test and 17follow the UNIX philosophy. It's a good idea to make the test as 18self-contained as possible too (it should not depend on tools or libraries 19that are not widely available). 20 21Do not reinvent the wheel! 22 23* Use LTP standard interface 24* Do not add custom PASS/FAIL reporting functions 25* Do not write Makefiles from scratch, 26 use LTP build system instead, etc. 27* ... 28 291.2 Code duplication 30~~~~~~~~~~~~~~~~~~~~ 31 32Copy & paste is a good servant but very poor master. If you are about to copy a 33large part of the code from one testcase to another, think what would happen if 34you find bug in the code that has been copied all around the tree. What about 35moving it to a library instead? 36 37The same goes for short but complicated parts, whenever you are about to copy & 38paste a syscall wrapper that packs arguments accordingly to machine 39architecture or similarly complicated code, put it into a header instead. 40 411.3 Coding style 42~~~~~~~~~~~~~~~~ 43 441.3.1 C coding style 45^^^^^^^^^^^^^^^^^^^^ 46 47LTP adopted Linux kernel coding style. If you aren't familiar with its rules 48locate 'linux/Documentation/CodingStyle' in the kernel sources and read it, 49it's a well written introduction. 50 51There is also a checkpatch (see 'linux/scripts/checkpatch.pl') script that can 52be used to check your patches before the submission. 53 54NOTE: If checkpatch does not report any problems, the code still may be wrong 55 as the tool only looks for common mistakes. 56 571.3.2 Shell coding style 58^^^^^^^^^^^^^^^^^^^^^^^^ 59 60When writing testcases in shell write in *portable shell* only, it's a good 61idea to try to run the test using alternative shell (alternative to bash, for 62example dash) too. 63 64*Portable shell* means Shell Command Language as defined by POSIX with a 65exception of few widely used extensions, namely 'local' keyword used inside of 66functions and '-o' and '-a' test parameters (that are marked as obsolete in 67POSIX). 68 69You can either try to run the testcases on Debian which has '/bin/sh' pointing 70to 'dash' by default or install 'dash' on your favorite distribution and use 71it to run the tests. If your distribution lacks 'dash' package you can always 72compile it from http://gondor.apana.org.au/~herbert/dash/files/[source]. 73 74Debian also has nice devscript 75https://salsa.debian.org/debian/devscripts/raw/master/scripts/checkbashisms.pl[checkbashism.pl] 76that can be used to check for non-portable shell code. 77 78Here are some common sense style rules for shell 79 80* Keep lines under 80 chars 81 82* Use tabs for indentation 83 84* Keep things simple, avoid unnecessary subshells 85 86* Don't do confusing things (i.e. don't name your functions like common shell 87 commands, etc.) 88 89* Quote variables 90 91* Be consistent 92 931.4 Commenting code 94~~~~~~~~~~~~~~~~~~~ 95 96Comments can sometimes save you day but they can easily do more harm than 97good. There has been several cases where comments and actual implementation 98were drifting slowly apart which yielded into API misuses and hard to find 99bugs. Remember there is only one thing worse than no documentation, wrong 100documentation. 101 102Generally everybody should write code that is obvious (which unfortunately 103isn't always possible). If there is a code that needs to be commented keep it 104short and to the point. Never ever comment the obvious. 105 106In case of LTP testcases it's customary to add a paragraph with highlevel test 107description somewhere at the beginning of the file (usually right under the GPL 108header). This helps other people to understand the overall goal of the test 109before they dive into the technical details. 110 1111.5 Backwards compatibility 112~~~~~~~~~~~~~~~~~~~~~~~~~~~ 113 114LTP test should be as backward compatible as possible. Think of an enterprise 115distributions with long term support (more than five years since the initial 116release) or of an embedded platform that needs to use several years old 117toolchain supplied by the manufacturer. 118 119Therefore LTP test for more current features should be able to cope with older 120systems. It should at least compile fine and if it's not appropriate for the 121configuration it should return 'TCONF' (see test interface description below). 122 123There are several types of checks we use: 124 125The *configure script* is usually used to detect availability of a function 126declarations in system headers. It's used to disable tests at compile time. 127 128We also have runtime kernel version detection that can be used to disable 129tests at runtime. 130 131Checking the *errno* value is another type of runtime check. Most of the 132syscalls returns either 'EINVAL' or 'ENOSYS' when syscall was not implemented 133or was disabled upon kernel compilation. 134 135Sometimes it also makes sense to define a few macros instead of creating 136configure test. One example are Linux specific POSIX clock ids in 137'include/lapi/posix_clocks.h'. 138 1391.6 Dealing with messed up legacy code 140~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 141 142LTP contains a lot of old and messy code and we are cleaning it up as fast as 143we can but despite the efforts there is still a lot. If you start modifying 144old or a messed up testcase and your changes are more complicated than simple 145typo fixes you should do a cleanup first (in a separate patch). It's easier to 146review the changes if you separate the formatting fixes from the changes that 147affects the test behavior. 148 149The same goes for moving files. If you need a rename or move file do it in a 150separate patch. 151 1521.7 License 153~~~~~~~~~~~ 154 155Code contributed to LTP should be licensed under GPLv2+ (GNU GPL version 2 or 156any later version). 157 1582. Writing a testcase 159--------------------- 160 1612.1 LTP Structure 162~~~~~~~~~~~~~~~~~ 163 164The structure of LTP is quite simple. Each test is a binary written either in 165portable shell or C. The test gets a configuration via environment variables 166and/or command line parameters, it prints additional information into the 167stdout and reports overall success/failure via the exit value. 168 169Tests are generally placed under the 'testcases/' directory. Everything that 170is a syscall or (slightly confusingly) libc syscall wrapper goes under 171'testcases/kernel/syscalls/'. Then there is 'testcases/open_posix_testsuite' 172which is a well maintained fork of the upstream project that has been dead 173since 2005 and also a number of directories with tests for more specific 174features. 175 1762.1.1 Runtest Files 177^^^^^^^^^^^^^^^^^^^ 178 179The list of tests to be executed is stored in runtest files under the 180'runtest/' directory. The default set of runtest files to be executed is 181stored in 'scenario_groups/default'. When you add a test you should add 182corresponding entries into some runtest file(s) as well. 183 184For syscall tests (these placed under 'testcases/kernel/syscalls/') use 185'runtest/syscalls' file, for kernel related tests for memory management we 186have 'runtest/mm', etc. 187 188IMPORTANT: The runtest files should have one entry per a test. Creating a 189 wrapper that runs all your tests and adding it as a single test 190 into runtest file is strongly discouraged. 191 1922.1.2 Datafiles 193^^^^^^^^^^^^^^^ 194 195If your test needs datafiles to work, these should be put into a subdirectory 196named 'datafiles' and installed into the 'testcases/data/$TCID' directory (to 197do that you have to add 'INSTALL_DIR := testcases/data/TCID' into the 198'datafiles/Makefile'). 199 200You can obtain path to datafiles via $TST_DATAROOT provided by test.sh 201'$TST_DATAROOT/...' 202or via C function 'tst_dataroot()' provided by libltp: 203 204[source,c] 205------------------------------------------------------------------------------- 206const char *dataroot = tst_dataroot(); 207------------------------------------------------------------------------------- 208 209Datafiles can also be accessed as '$LTPROOT/testcases/data/$TCID/...', 210but '$TST_DATAROOT' and 'tst_dataroot()' are preferred as these can be used 211when running testcases directly in git tree as well as from install 212location. 213 214The path is constructed according to these rules: 215 2161. if '$LTPROOT' is set, return '$LTPROOT/testcases/data/$TCID' 2172. else if 'tst_tmpdir()' was called return '$STARTWD/datafiles' 218 (where '$STARTWD' is initial working directory as recorded by 'tst_tmpdir()') 2193. else return '$CWD/datafiles' 220 221See 'testcases/commands/file/' for example. 222 2232.1.3 Subexecutables 224^^^^^^^^^^^^^^^^^^^^ 225 226If you test needs to execute a binary, place it in the same directory as the 227testcase and name the file starting with '${test_binary_name}_'. Once the 228test is executed by the framework, the path to the directory with all LTP 229binaries is added to the '$PATH' and you can execute it just by its name. 230 231TIP: If you need to execute such test from the LTP tree, you can add path to 232 current directory to '$PATH' manually with: 'PATH="$PATH:$PWD" ./foo01'. 233 2342.2 Writing a test in C 235~~~~~~~~~~~~~~~~~~~~~~~ 236 2372.2.1 Basic test structure 238^^^^^^^^^^^^^^^^^^^^^^^^^^ 239 240Let's start with an example, following code is a simple test for a 'getenv()'. 241 242[source,c] 243------------------------------------------------------------------------------- 244/* 245 * This is test for basic functionality of getenv(). 246 * 247 * - create an env variable and verify that getenv() can get get it 248 * - call getenv() with nonexisting variable name, check that it returns NULL 249 */ 250 251#include "tst_test.h" 252 253#define ENV1 "LTP_TEST_ENV" 254#define ENV2 "LTP_TEST_THIS_DOES_NOT_EXIST" 255#define ENV_VAL "val" 256 257static void setup(void) 258{ 259 if (setenv(ENV1, ENV_VAL, 1)) 260 tst_brk(TBROK | TERRNO, "setenv() failed"); 261} 262 263static void test(void) 264{ 265 char *ret; 266 267 ret = getenv(ENV1); 268 269 if (!ret) { 270 tst_res(TFAIL, "getenv(" ENV1 ") = NULL"); 271 goto next; 272 } 273 274 if (!strcmp(ret, ENV_VAL)) { 275 tst_res(TPASS, "getenv(" ENV1 ") = '"ENV_VAL "'"); 276 } else { 277 tst_res(TFAIL, "getenv(" ENV1 ") = '%s', expected '" 278 ENV_VAL "'", ret); 279 } 280 281next: 282 ret = getenv(ENV2); 283 284 if (ret) 285 tst_res(TFAIL, "getenv(" ENV2 ") = '%s'", ret); 286 else 287 tst_res(TPASS, "getenv(" ENV2 ") = NULL"); 288} 289 290static struct tst_test test = { 291 .test_all = test, 292 .setup = setup, 293}; 294------------------------------------------------------------------------------- 295 296Each test includes the 'tst_test.h' header and must define the 'struct 297tst_test test' structure. 298 299The overall test initialization is done in the 'setup()' function. 300 301The overall cleanup is done in a 'cleanup()' function. Here 'cleanup()' is 302omitted as the test does not have anything to clean up. If cleanup is set in 303the test structure it's called on test exit just before the test library 304cleanup. That especially means that cleanup can be called at any point in a 305test execution. For example even when a test setup step has failed, therefore 306the 'cleanup()' function must be able to cope with unfinished initialization, 307and so on. 308 309The test itself is done in the 'test()' function. The test function must work 310fine if called in a loop. 311 312There are two types of a test function pointers in the test structure. The 313first one is a '.test_all' pointer that is used when test is implemented as a 314single function. Then there is a '.test' function along with the number of 315tests '.tcnt' that allows for more detailed result reporting. If the '.test' 316pointer is set the function is called '.tcnt' times with an integer parameter 317in range of [0, '.tcnt' - 1]. 318 319IMPORTANT: Only one of '.test' and '.test_all' can be set at a time. 320 321Each test has a default timeout set to 300s. The default timeout can be 322overriden by setting '.timeout' in the test structure or by calling 323'tst_set_timeout()' in the test 'setup()'. There are a few testcases whose run 324time may vary arbitrarily, for these timeout can be disabled by setting it to 325-1. 326 327Test can find out how much time (in seconds) is remaining to timeout, 328by calling 'tst_timeout_remaining()'. 329 330A word about the cleanup() callback 331+++++++++++++++++++++++++++++++++++ 332 333There are a few rules that needs to be followed in order to write correct 334cleanup() callback. 335 3361. Free only resources that were initialized. Keep in mind that callback can 337 be executed at any point in the test run. 338 3392. Make sure to free resources in the reverse order they were 340 initialized. (Some of the steps may not depend on others and everything 341 will work if there were swapped but let's keep it in order.) 342 343The first rule may seem complicated at first however, on the contrary, it's 344quite easy. All you have to do is to keep track of what was already 345initialized. For example file descriptors needs to be closed only if they were 346assigned a valid file descriptor. For most of the things you need to create 347extra flag that is set right after successful initialization though. Consider, 348for example, test setup below. 349 350[source,c] 351------------------------------------------------------------------------------- 352static int fd0, fd1, mount_flag; 353 354#define MNTPOINT "mntpoint" 355#define FILE1 "mntpoint/file1" 356#define FILE2 "mntpoint/file2" 357 358static void setup(void) 359{ 360 SAFE_MKDIR(MNTPOINT, 0777); 361 SAFE_MKFS(tst_device->dev, tst_device->fs_type, NULL, NULL); 362 SAFE_MOUNT(tst_device->dev, MNTPOINT, tst_device->fs_type, 0, 0); 363 mount_flag = 1; 364 365 fd0 = SAFE_OPEN(cleanup, FILE1, O_CREAT | O_RDWR, 0666); 366 fd1 = SAFE_OPEN(cleanup, FILE2, O_CREAT | O_RDWR, 0666); 367} 368------------------------------------------------------------------------------- 369 370In this case the 'cleanup()' function may be invoked when any of the 'SAFE_*' 371macros has failed and therefore must be able to work with unfinished 372initialization as well. Since global variables are initialized to zero we can 373just check that fd > 0 before we attempt to close it. The mount function 374requires extra flag to be set after device was successfully mounted. 375 376[source,c] 377------------------------------------------------------------------------------- 378static void cleanup(void) 379{ 380 if (fd1 > 0) 381 SAFE_CLOSE(fd1); 382 383 if (fd0 > 0) 384 SAFE_CLOSE(fd0); 385 386 if (mount_flag && tst_umouont(MNTPOINT)) 387 tst_res(TWARN | TERRNO, "umount(%s)", MNTPOINT); 388} 389------------------------------------------------------------------------------- 390 391IMPORTANT: 'SAFE_MACROS()' used in cleanup *do not* exit the test. Failure 392 only produces a warning and the 'cleanup()' carries on. This is 393 intentional as we want to execute as much 'cleanup()' as possible. 394 395WARNING: Calling tst_brk() in test 'cleanup()' does not exit the test as well 396 and 'TBROK' is converted to 'TWARN'. 397 398NOTE: Creation and removal of the test temporary directory is handled in 399 the test library and the directory is removed recursively. Therefore 400 we do not have to remove files and directories in the test cleanup. 401 4022.2.2 Basic test interface 403^^^^^^^^^^^^^^^^^^^^^^^^^^ 404 405[source,c] 406------------------------------------------------------------------------------- 407void tst_res(int ttype, char *arg_fmt, ...); 408------------------------------------------------------------------------------- 409 410Printf-like function to report test result, it's mostly used with ttype: 411 412|============================== 413| 'TPASS' | Test has passed. 414| 'TFAIL' | Test has failed. 415| 'TINFO' | General message. 416|============================== 417 418The 'ttype' can be combined bitwise with 'TERRNO' or 'TTERRNO' to print 419'errno', 'TST_ERR' respectively. 420 421[source,c] 422------------------------------------------------------------------------------- 423void tst_brk(int ttype, char *arg_fmt, ...); 424------------------------------------------------------------------------------- 425 426Printf-like function to report error and exit the test, it can be used with ttype: 427 428|============================================================ 429| 'TBROK' | Something has failed in test preparation phase. 430| 'TCONF' | Test is not appropriate for current configuration 431 (syscall not implemented, unsupported arch, ...) 432|============================================================ 433 434The 'ttype' can be combined bitwise with 'TERRNO' or 'TTERRNO' to print 435'errno', 'TST_ERR' respectively. 436 437[source,c] 438------------------------------------------------------------------------------- 439const char *tst_strsig(int sig); 440------------------------------------------------------------------------------- 441 442Return the given signal number's corresponding string. 443 444[source,c] 445------------------------------------------------------------------------------- 446const char *tst_strerrno(int err); 447------------------------------------------------------------------------------- 448 449Return the given errno number's corresponding string. Using this function to 450translate 'errno' values to strings is preferred. You should not use the 451'strerror()' function in the testcases. 452 453[source,c] 454------------------------------------------------------------------------------- 455const char *tst_strstatus(int status); 456------------------------------------------------------------------------------- 457 458Returns string describing the status as returned by 'wait()'. 459 460WARNING: This function is not thread safe. 461 462[source,c] 463------------------------------------------------------------------------------- 464void tst_set_timeout(unsigned int timeout); 465------------------------------------------------------------------------------- 466 467Allows for setting timeout per test iteration dymanically in the test setup(), 468the timeout is specified in seconds. There are a few testcases whose runtime 469can vary arbitrarily, these can disable timeouts by setting it to -1. 470 471[source,c] 472------------------------------------------------------------------------------- 473void tst_flush(void); 474------------------------------------------------------------------------------- 475 476Flush output streams, handling errors appropriately. 477 478This function is rarely needed when you have to flush the output streams 479before calling 'fork()' or 'clone()'. Note that the 'SAFE_FORK()' calls this 480function automatically. See 3.4 FILE buffers and fork() for explanation why is 481this needed. 482 4832.2.3 Test temporary directory 484^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 485 486If '.needs_tmpdir' is set to '1' in the 'struct tst_test' unique test 487temporary is created and it's set as the test working directory. Tests *MUST 488NOT* create temporary files outside that directory. 489 490IMPORTANT: Close all file descriptors (that point to files in test temporary 491 directory, even the unlinked ones) either in the 'test()' function 492 or in the test 'cleanup()' otherwise the test may break temporary 493 directory removal on NFS (look for "NFS silly rename"). 494 4952.2.4 Safe macros 496^^^^^^^^^^^^^^^^^ 497 498Safe macros aim to simplify error checking in test preparation. Instead of 499calling system API functions, checking for their return value and aborting the 500test if the operation has failed, you just use corresponding safe macro. 501 502Use them whenever it's possible. 503 504Instead of writing: 505 506[source,c] 507------------------------------------------------------------------------------- 508 fd = open("/dev/null", O_RDONLY); 509 if (fd < 0) 510 tst_brk(TBROK | TERRNO, "opening /dev/null failed"); 511------------------------------------------------------------------------------- 512 513You write just: 514 515[source,c] 516------------------------------------------------------------------------------- 517 fd = SAFE_OPEN("/dev/null", O_RDONLY); 518------------------------------------------------------------------------------- 519 520IMPORTANT: The SAFE_CLOSE() function also sets the passed file descriptor to -1 521 after it's successfully closed. 522 523They can also simplify reading and writing of sysfs files, you can, for 524example, do: 525 526[source,c] 527------------------------------------------------------------------------------- 528 SAFE_FILE_SCANF("/proc/sys/kernel/pid_max", "%lu", &pid_max); 529------------------------------------------------------------------------------- 530 531See 'include/tst_safe_macros.h', 'include/tst_safe_stdio.h' and 532'include/tst_safe_file_ops.h' and 'include/tst_safe_net.h' for a complete list. 533 5342.2.5 Test specific command line options 535^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 536 537[source,c] 538------------------------------------------------------------------------------- 539struct tst_option { 540 char *optstr; 541 char **arg; 542 char *help; 543}; 544------------------------------------------------------------------------------- 545 546Test specific command line parameters can be passed with the 'NULL'-terminated 547array of 'struct tst_option'. The 'optstr' is the command line option i.e. "o" 548or "o:" if option has a parameter. Only short options are supported. The 'arg' 549is where 'optarg' is stored upon match. If option has no parameter it's set to 550non-'NULL' value if option was present. The 'help' is a short help string. 551 552NOTE: The test parameters must not collide with common test parameters defined 553 in the library the currently used ones are +-i+, +-I+, +-C+, and +-h+. 554 555[source,c] 556------------------------------------------------------------------------------- 557int tst_parse_int(const char *str, int *val, int min, int max); 558int tst_parse_float(const char *str, float *val, float min, float max); 559------------------------------------------------------------------------------- 560 561Helpers for parsing the the strings returned in the 'struct tst_option'. 562 563Both return zero on success and 'errno', mostly 'EINVAL' or 'ERANGE', on 564failure. 565 566Both functions are no-op if 'str' is 'NULL'. 567 568The valid range for result includes both 'min' and 'max'. 569 570.Example Usage 571[source,c] 572------------------------------------------------------------------------------- 573#include <limits.h> 574#include "tst_test.h" 575 576static char *str_threads; 577static int threads = 10; 578 579static struct tst_option options[] = { 580 {"t:", &str_threads, "Number of threads (default 10)"}, 581 ... 582 {NULL, NULL, NULL} 583}; 584 585static void setup(void) 586{ 587 if (tst_parse_int(str_threads, &threads, 1, INT_MAX)) 588 tst_brk(TBROK, "Invalid number of threads '%s'", str_threads); 589 590 ... 591} 592 593static void test_threads(void) 594{ 595 ... 596 597 for (i = 0; i < threads; i++) { 598 ... 599 } 600 601 ... 602} 603 604static struct tst_test test = { 605 ... 606 .options = options, 607 ... 608}; 609------------------------------------------------------------------------------- 610 611 6122.2.6 Runtime kernel version detection 613^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 614 615Testcases for newly added kernel functionality require kernel newer than a 616certain version to run. All you need to skip a test on older kernels is to 617set the '.min_kver' string in the 'struct tst_test' to a minimal required 618kernel version, e.g. '.min_kver = "2.6.30"'. 619 620For more complicated operations such as skipping a test for a certain range 621of kernel versions, following functions could be used: 622 623[source,c] 624------------------------------------------------------------------------------- 625int tst_kvercmp(int r1, int r2, int r3); 626 627struct tst_kern_exv { 628 char *dist_name; 629 char *extra_ver; 630}; 631 632int tst_kvercmp2(int r1, int r2, int r3, struct tst_kern_exv *vers); 633------------------------------------------------------------------------------- 634 635These two functions are intended for runtime kernel version detection. They 636parse the output from 'uname()' and compare it to the passed values. 637 638The return value is similar to the 'strcmp()' function, i.e. zero means equal, 639negative value means that the kernel is older than than the expected value and 640positive means that it's newer. 641 642The second function 'tst_kvercmp2()' allows for specifying per-vendor table of 643kernel versions as vendors typically backport fixes to their kernels and the 644test may be relevant even if the kernel version does not suggests so. See 645'testcases/kernel/syscalls/inotify/inotify04.c' for example usage. 646 647WARNING: The shell 'tst_kvercmp' maps the result into unsigned integer - the 648 process exit value. 649 6502.2.7 Fork()-ing 651^^^^^^^^^^^^^^^^ 652 653Be wary that if the test forks and there were messages printed by the 654'tst_*()' interfaces, the data may still be in libc/kernel buffers and these 655*ARE NOT* flushed automatically. 656 657This happens when 'stdout' gets redirected to a file. In this case, the 658'stdout' is not line buffered, but block buffered. Hence after a fork content 659of the buffers will be printed by the parent and each of the children. 660 661To avoid that you should use 'SAFE_FORK()'. 662 663IMPORTANT: You have to set the '.forks_child' flag in the test structure 664 if your testcase forks. 665 6662.2.8 Doing the test in the child process 667^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 668 669Results reported by 'tst_res()' are propagated to the parent test process via 670block of shared memory. 671 672Calling 'tst_brk()' causes child process to exit with non-zero exit value. 673Which means that it's safe to use 'SAFE_*()' macros in the child processes as 674well. 675 676Children that outlive the 'test()' function execution are waited for in the 677test library. Unclean child exit (killed by signal, non-zero exit value, etc.) 678will cause the main test process to exit with 'tst_brk()', which especially 679means that 'TBROK' propagated from a child process will cause the whole test 680to exit with 'TBROK'. 681 682If a test needs a child that segfaults or does anything else that cause it to 683exit uncleanly all you need to do is to wait for such children from the 684'test()' function so that it's reaped before the main test exits the 'test()' 685function. 686 687[source,c] 688------------------------------------------------------------------------------- 689#include "tst_test.h" 690 691void tst_reap_children(void); 692------------------------------------------------------------------------------- 693 694The 'tst_reap_children()' function makes the process wait for all of its 695children and exits with 'tst_brk(TBROK, ...)' if any of them returned 696a non zero exit code. 697 698.Using tst_res() from binaries started by exec() 699[source,c] 700------------------------------------------------------------------------------- 701/* test.c */ 702#define _GNU_SOURCE 703#include <unistd.h> 704#include "tst_test.h" 705 706static void do_test(void) 707{ 708 char *const argv[] = {"test_exec_child", NULL}; 709 char path[4096]; 710 711 if (tst_get_path("test_exec_child", path, sizeof(path))) 712 tst_brk(TCONF, "Couldn't find test_exec_child in $PATH"); 713 714 execve(path, argv, environ); 715 716 tst_res(TBROK | TERRNO, "EXEC!"); 717} 718 719static struct tst_test test = { 720 .test_all = do_test, 721 .child_needs_reinit = 1, 722}; 723 724/* test_exec_child.c */ 725#define TST_NO_DEFAULT_MAIN 726#include "tst_test.h" 727 728int main(void) 729{ 730 tst_reinit(); 731 tst_res(TPASS, "Child passed!"); 732 return 0; 733} 734------------------------------------------------------------------------------- 735 736The 'tst_res()' function can be also used from binaries started by 'exec()', 737the parent test process has to set the '.child_needs_reinit' flag so that the 738library prepares for it and has to make sure the 'LTP_IPC_PATH' environment 739vairiable is passed down, then the very fist thing the program has to call in 740'main()' is 'tst_reinit()' that sets up the IPC. 741 7422.2.9 Fork() and Parent-child synchronization 743^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 744 745As LTP tests are written for Linux, most of the tests involve fork()-ing and 746parent-child process synchronization. LTP includes a checkpoint library that 747provides wait/wake futex based functions. 748 749In order to use checkpoints the '.needs_checkpoints' flag in the 'struct 750tst_test' must be set to '1', this causes the test library to initialize 751checkpoints before the 'test()' function is called. 752 753[source,c] 754------------------------------------------------------------------------------- 755#include "tst_test.h" 756 757TST_CHECKPOINT_WAIT(id) 758 759TST_CHECKPOINT_WAIT2(id, msec_timeout) 760 761TST_CHECKPOINT_WAKE(id) 762 763TST_CHECKPOINT_WAKE2(id, nr_wake) 764 765TST_CHECKPOINT_WAKE_AND_WAIT(id) 766------------------------------------------------------------------------------- 767 768The checkpoint interface provides pair of wake and wait functions. The 'id' is 769unsigned integer which specifies checkpoint to wake/wait for. As a matter of 770fact it's an index to an array stored in a shared memory, so it starts on 771'0' and there should be enough room for at least of hundred of them. 772 773The 'TST_CHECKPOINT_WAIT()' and 'TST_CHECKPOINT_WAIT2()' suspends process 774execution until it's woken up or until timeout is reached. 775 776The 'TST_CHECKPOINT_WAKE()' wakes one process waiting on the checkpoint. 777If no process is waiting the function retries until it success or until 778timeout is reached. 779 780If timeout has been reached process exits with appropriate error message (uses 781'tst_brk()'). 782 783The 'TST_CHECKPOINT_WAKE2()' does the same as 'TST_CHECKPOINT_WAKE()' but can 784be used to wake precisely 'nr_wake' processes. 785 786The 'TST_CHECKPOINT_WAKE_AND_WAIT()' is a shorthand for doing wake and then 787immediately waiting on the same checkpoint. 788 789Child processes created via 'SAFE_FORK()' are ready to use the checkpoint 790synchronization functions, as they inherited the mapped page automatically. 791 792Child processes started via 'exec()', or any other processes not forked from 793the test process must initialize the checkpoint by calling 'tst_reinit()'. 794 795For the details of the interface, look into the 'include/tst_checkpoint.h'. 796 797[source,c] 798------------------------------------------------------------------------------- 799#include "tst_test.h" 800 801/* 802 * Waits for process state change. 803 * 804 * The state is one of the following: 805 * 806 * R - process is running 807 * S - process is sleeping 808 * D - process sleeping uninterruptibly 809 * Z - zombie process 810 * T - process is traced 811 */ 812TST_PROCESS_STATE_WAIT(pid, state) 813------------------------------------------------------------------------------- 814 815The 'TST_PROCESS_STATE_WAIT()' waits until process 'pid' is in requested 816'state'. The call polls +/proc/pid/stat+ to get this information. 817 818It's mostly used with state 'S' which means that process is sleeping in kernel 819for example in 'pause()' or any other blocking syscall. 820 8212.2.10 Signal handlers 822^^^^^^^^^^^^^^^^^^^^^^ 823 824If you need to use signal handlers, keep the code short and simple. Don't 825forget that the signal handler is called asynchronously and can interrupt the 826code execution at any place. 827 828This means that problems arise when global state is changed both from the test 829code and signal handler, which will occasionally lead to: 830 831* Data corruption (data gets into inconsistent state), this may happen, for 832 example, for any operations on 'FILE' objects. 833 834* Deadlock, this happens, for example, if you call 'malloc(2)', 'free(2)', 835 etc. from both the test code and the signal handler at the same time since 836 'malloc' has global lock for it's internal data structures. (Be wary that 837 'malloc(2)' is used by the libc functions internally too.) 838 839* Any other unreproducible and unexpected behavior. 840 841Quite common mistake is to call 'exit(3)' from a signal handler. Note that this 842function is not signal-async-safe as it flushes buffers, etc. If you need to 843exit a test immediately from a signal handler use '_exit(2)' instead. 844 845TIP: See 'man 7 signal' for the list of signal-async-safe functions. 846 847If a signal handler sets a variable, its declaration must be 'volatile', 848otherwise compiler may misoptimize the code. This is because the variable may 849not be changed in the compiler code flow analysis. There is 'sig_atomic_t' 850type defined in C99 but this one *DOES NOT* imply 'volatile' (it's just a 851'typedef' to 'int'). So the correct type for a flag that is changed from a 852signal handler is either 'volatile int' or 'volatile sig_atomic_t'. 853 8542.2.11 Kernel Modules 855^^^^^^^^^^^^^^^^^^^^^ 856 857There are certain cases where the test needs a kernel part and userspace part, 858happily, LTP can build a kernel module and then insert it to the kernel on test 859start for you. See 'testcases/kernel/device-drivers/block' for details. 860 8612.2.11 Useful macros 862^^^^^^^^^^^^^^^^^^^^^ 863 864[source,c] 865------------------------------------------------------------------------------- 866ARRAY_SIZE(arr) 867------------------------------------------------------------------------------- 868 869Returns the size of statically defined array, i.e. 870'(sizeof(arr) / sizeof(*arr))' 871 872[source,c] 873------------------------------------------------------------------------------- 874LTP_ALIGN(x, a) 875------------------------------------------------------------------------------- 876 877Aligns the x to be next multiple of a. The a must be power of 2. 878 8792.2.12 Filesystem type detection 880^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 881 882Some tests are known to fail on certain filesystems (you cannot swap on TMPFS, 883there are unimplemented 'fcntl()' etc.). 884 885If your test needs to be skipped on certain filesystems, use the interface 886below: 887 888[source,c] 889------------------------------------------------------------------------------- 890#include "tst_test.h" 891 892 /* 893 * Unsupported only on NFS. 894 */ 895 if (tst_fs_type(".") == TST_NFS_MAGIC) 896 tst_brk(TCONF, "Test not supported on NFS filesystem"); 897 898 899 /* 900 * Unsupported on NFS, TMPFS and RAMFS 901 */ 902 long type; 903 904 switch ((type = tst_fs_type("."))) { 905 case TST_NFS_MAGIC: 906 case TST_TMPFS_MAGIC: 907 case TST_RAMFS_MAGIC: 908 tst_brk(TCONF, "Test not supported on %s filesystem", 909 tst_fs_type_name(type)); 910 break; 911 } 912------------------------------------------------------------------------------- 913 9142.2.13 Thread-safety in the LTP library 915^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 916 917It is safe to use library 'tst_res()' function in multi-threaded tests. 918 919Only the main thread must return from the 'test()' function to the test 920library and that must be done only after all threads that may call any library 921function has been terminated. That especially means that threads that may call 922'tst_brk()' must terminate before the execution of the 'test()' function 923returns to the library. This is usually done by the main thread joining all 924worker threads at the end of the 'test()' function. Note that the main thread 925will never get to the library code in a case that 'tst_brk()' was called from 926one of the threads since it will sleep at least in 'pthread_join()' on the 927thread that called the 'tst_brk()' till 'exit()' is called by 'tst_brk()'. 928 929The test-supplied cleanup function runs *concurrently* to the rest of the 930threads in a case that cleanup was entered from 'tst_brk()'. Subsequent 931threads entering 'tst_brk()' must be suspended or terminated at the start of 932the the user supplied cleanup function. It may be necessary to stop or exit 933the rest of the threads before the test cleans up as well. For example threads 934that create new files should be stopped before temporary directory is be 935removed. 936 937Following code example shows thread safe cleanup function example using atomic 938increment as a guard. The library calls its cleanup after the execution returns 939from the user supplied cleanup and expects that only one thread returns from 940the user supplied cleanup to the test library. 941 942[source,c] 943------------------------------------------------------------------------------- 944#include "tst_test.h" 945 946static void cleanup(void) 947{ 948 static int flag; 949 950 if (tst_atomic_inc(&flag) != 1) 951 pthread_exit(NULL); 952 953 /* if needed stop the rest of the threads here */ 954 955 ... 956 957 /* then do cleanup work */ 958 959 ... 960 961 /* only one thread returns to the library */ 962} 963------------------------------------------------------------------------------- 964 965 9662.2.14 Testing with a block device 967^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 968 969Some tests needs a block device (inotify tests, syscall 'EROFS' failures, 970etc.). LTP library contains a code to prepare a testing device. 971 972If '.needs_device' flag in the 'struct tst_test' is set the the 'tst_device' 973structure is initialized with a path to a test device and default filesystem 974to be used. 975 976You can also request minimal device size in megabytes by setting 977'.dev_min_size' the device is guaranteed to have at least the requested size 978then. 979 980If '.format_device' flag is set the device is formatted with a filesystem as 981well. You can use '.dev_fs_type' to override the default filesystem type if 982needed and pass additional options to mkfs via '.dev_fs_opts' and 983'.dev_extra_opts' pointers. Note that '.format_device' implies '.needs_device' 984there is no need to set both. 985 986If '.mount_device' is set, the device is mounted at '.mntpoint' which is used 987to pass a directory name that will be created and used as mount destination. 988You can pass additional flags and data to the mount command via '.mnt_flags' 989and '.mnt_data' pointers. Note that '.mount_device' implies '.needs_device' 990and '.format_device' so there is no need to set the later two. 991 992If '.needs_rofs' is set, read-only filesystem is mounted at '.mntpoint' this 993one is supposed to be used for 'EROFS' tests. 994 995If '.all_filesystems' is set the test function is executed for all supported 996filesystems. Supported filesystems are detected based on existence of the 997'mkfs.$fs' helper and on kernel support to mount it. For each supported 998filesystem the 'tst_device.fs_type' is set to the currently tested fs type, if 999'.format_device' is set the device is formatted as well, if '.mount_device' is 1000set it's mounted at '.mntpoint'. Also the test timeout is reset for each 1001execution of the test fuction. This flag is expected to be used for filesystem 1002related syscalls that are at least partly implemented in the filesystem 1003specific code e.g. fallocate(). 1004 1005[source,c] 1006------------------------------------------------------------------------------- 1007#include "tst_test.h" 1008 1009struct tst_device { 1010 const char *dev; 1011 const char *fs_type; 1012}; 1013 1014extern struct tst_device *tst_device; 1015 1016int tst_umount(const char *path); 1017------------------------------------------------------------------------------- 1018 1019In case that 'LTP_DEV' is passed to the test in an environment, the library 1020checks that the file exists and that it's a block device, if 1021'.device_min_size' is set the device size is checked as well. If 'LTP_DEV' 1022wasn't set or if size requirements were not met a temporary file is created 1023and attached to a free loop device. 1024 1025If there is no usable device and loop device couldn't be initialized the test 1026exits with 'TCONF'. 1027 1028The 'tst_umount()' function works exactly as 'umount(2)' but retries several 1029times on 'EBUSY'. This is because various desktop daemons (gvfsd-trash is known 1030for that) may be stupid enough to probe all newly mounted filesystem which 1031results in 'umount(2)' failing with 'EBUSY'. 1032 1033IMPORTANT: All testcases should use 'tst_umount()' instead of 'umount(2)' to 1034 umount filesystems. 1035 10362.2.15 Formatting a device with a filesystem 1037^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1038 1039[source,c] 1040------------------------------------------------------------------------------- 1041#include "tst_test.h" 1042 1043static void setup(void) 1044{ 1045 ... 1046 SAFE_MKFS(tst_device->dev, tst_device->fs_type, NULL, NULL); 1047 ... 1048} 1049------------------------------------------------------------------------------- 1050 1051This function takes a path to a device, filesystem type and an array of extra 1052options passed to mkfs. 1053 1054The fs options 'fs_opts' should either be 'NULL' if there are none, or a 1055'NULL' terminated array of strings such as: 1056+const char *const opts[] = {"-b", "1024", NULL}+. 1057 1058The extra options 'extra_opts' should either be 'NULL' if there are none, or a 1059'NULL' terminated array of strings such as +{"102400", NULL}+; 'extra_opts' 1060will be passed after device name. e.g: +mkfs -t ext4 -b 1024 /dev/sda1 102400+ 1061in this case. 1062 10632.2.16 Verifying a filesystem's free space 1064^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1065 1066Some tests have size requirements for the filesystem's free space. If these 1067requirements are not satisfied, the tests should be skipped. 1068 1069[source,c] 1070------------------------------------------------------------------------------- 1071#include "tst_test.h" 1072 1073int tst_fs_has_free(const char *path, unsigned int size, unsigned int mult); 1074------------------------------------------------------------------------------- 1075 1076The 'tst_fs_has_free()' function returns 1 if there is enough space and 0 if 1077there is not. 1078 1079The 'path' is the pathname of any directory/file within a filesystem. 1080 1081The 'mult' is a multiplier, one of 'TST_BYTES', 'TST_KB', 'TST_MB' or 'TST_GB'. 1082 1083The required free space is calculated by 'size * mult', e.g. 1084'tst_fs_has_free("/tmp/testfile", 64, TST_MB)' will return 1 if the 1085filesystem, which '"/tmp/testfile"' is in, has 64MB free space at least, and 0 1086if not. 1087 10882.2.17 Files, directories and fs limits 1089^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1090 1091Some tests need to know the maximum count of links to a regular file or 1092directory, such as 'rename(2)' or 'linkat(2)' to test 'EMLINK' error. 1093 1094[source,c] 1095------------------------------------------------------------------------------- 1096#include "tst_test.h" 1097 1098int tst_fs_fill_hardlinks(const char *dir); 1099------------------------------------------------------------------------------- 1100 1101Try to get maximum count of hard links to a regular file inside the 'dir'. 1102 1103NOTE: This number depends on the filesystem 'dir' is on. 1104 1105This function uses 'link(2)' to create hard links to a single file until it 1106gets 'EMLINK' or creates 65535 links. If the limit is hit, the maximum number of 1107hardlinks is returned and the 'dir' is filled with hardlinks in format 1108"testfile%i", where i belongs to [0, limit) interval. If no limit is hit or if 1109'link(2)' failed with 'ENOSPC' or 'EDQUOT', zero is returned and previously 1110created files are removed. 1111 1112[source,c] 1113------------------------------------------------------------------------------- 1114#include "tst_test.h" 1115 1116int tst_fs_fill_subdirs(const char *dir); 1117------------------------------------------------------------------------------- 1118 1119Try to get maximum number of subdirectories in directory. 1120 1121NOTE: This number depends on the filesystem 'dir' is on. For current kernel, 1122subdir limit is not available for all filesystems (available for ext2, ext3, 1123minix, sysv and more). If the test runs on some other filesystems, like ramfs, 1124tmpfs, it will not even try to reach the limit and return 0. 1125 1126This function uses 'mkdir(2)' to create directories in 'dir' until it gets 1127'EMLINK' or creates 65535 directories. If the limit is hit, the maximum number 1128of subdirectories is returned and the 'dir' is filled with subdirectories in 1129format "testdir%i", where i belongs to [0, limit - 2) interval (because each 1130newly created dir has two links already - the '.' and the link from parent 1131dir). If no limit is hit or if 'mkdir(2)' failed with 'ENOSPC' or 'EDQUOT', 1132zero is returned and previously created directories are removed. 1133 1134[source,c] 1135------------------------------------------------------------------------------- 1136#include "tst_test.h" 1137 1138int tst_dir_is_empty(const char *dir, int verbose); 1139------------------------------------------------------------------------------- 1140 1141Returns non-zero if directory is empty and zero otherwise. 1142 1143Directory is considered empty if it contains only '.' and '..'. 1144 11452.2.18 Getting an unused PID number 1146^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1147 1148Some tests require a 'PID', which is not used by the OS (does not belong to 1149any process within it). For example, kill(2) should set errno to 'ESRCH' if 1150it's passed such 'PID'. 1151 1152[source,c] 1153------------------------------------------------------------------------------- 1154#include "tst_test.h" 1155 1156pid_t tst_get_unused_pid(void); 1157------------------------------------------------------------------------------- 1158 1159Return a 'PID' value not used by the OS or any process within it. 1160 1161[source,c] 1162------------------------------------------------------------------------------- 1163#include "tst_test.h" 1164 1165int tst_get_free_pids(void); 1166------------------------------------------------------------------------------- 1167 1168Returns number of unused pids in the system. Note that this number may be 1169different once the call returns and should be used only for rough estimates. 1170 11712.2.20 Running executables 1172^^^^^^^^^^^^^^^^^^^^^^^^^^ 1173 1174[source,c] 1175------------------------------------------------------------------------------- 1176#include "tst_test.h" 1177 1178int tst_run_cmd(const char *const argv[], 1179 const char *stdout_path, 1180 const char *stderr_path, 1181 int pass_exit_val); 1182------------------------------------------------------------------------------- 1183 1184'tst_run_cmd' is a wrapper for 'vfork() + execvp()' which provides a way 1185to execute an external program. 1186 1187'argv[]' is a NULL-terminated array of strings starting with the program name 1188which is followed by optional arguments. 1189 1190A non-zero 'pass_exit_val' makes 'tst_run_cmd' return the program exit code to 1191the caller. A zero for 'pass_exit_val' makes 'tst_run_cmd' exit the tests 1192on failure. 1193 1194In case that 'execvp()' has failed and the 'pass_exit_val' flag was set, the 1195return value is '255' if 'execvp()' failed with 'ENOENT' and '254' otherwise. 1196 1197'stdout_path' and 'stderr_path' determine where to redirect the program 1198stdout and stderr I/O streams. 1199 1200.Example 1201[source,c] 1202------------------------------------------------------------------------------- 1203#include "tst_test.h" 1204 1205const char *const cmd[] = { "ls", "-l", NULL }; 1206 1207... 1208 /* Store output of 'ls -l' into log.txt */ 1209 tst_run_cmd(cmd, "log.txt", NULL, 0); 1210... 1211------------------------------------------------------------------------------- 1212 12132.2.21 Measuring elapsed time and helper functions 1214^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1215 1216[source,c] 1217------------------------------------------------------------------------------- 1218#include "tst_timer.h" 1219 1220void tst_timer_check(clockid_t clk_id); 1221 1222void tst_timer_start(clockid_t clk_id); 1223 1224void tst_timer_stop(void); 1225 1226struct timespec tst_timer_elapsed(void); 1227 1228long long tst_timer_elapsed_ms(void); 1229 1230long long tst_timer_elapsed_us(void); 1231 1232int tst_timer_expired_ms(long long ms); 1233------------------------------------------------------------------------------- 1234 1235The 'tst_timer_check()' function checks if specified 'clk_id' is suppored and 1236exits the test with 'TCONF' otherwise. It's expected to be used in test 1237'setup()' before any resources that needs to be cleaned up are initialized, 1238hence it does not include a cleanup function parameter. 1239 1240The 'tst_timer_start()' marks start time and stores the 'clk_id' for further 1241use. 1242 1243The 'tst_timer_stop()' marks the stop time using the same 'clk_id' as last 1244call to 'tst_timer_start()'. 1245 1246The 'tst_timer_elapsed*()' returns time difference between the timer start and 1247last timer stop in several formats and units. 1248 1249The 'tst_timer_expired_ms()' function checks if the timer started by 1250'tst_timer_start()' has been running longer than ms miliseconds. The function 1251returns non-zero if timer has expired and zero otherwise. 1252 1253IMPORTANT: The timer functions use 'clock_gettime()' internally which needs to 1254 be linked with '-lrt' on older glibc. Please do not forget to add 1255 'LDLIBS+=-lrt' in Makefile. 1256 1257[source,c] 1258------------------------------------------------------------------------------- 1259#include "tst_test.h" 1260#include "tst_timer.h" 1261 1262static void setup(void) 1263{ 1264 ... 1265 tst_timer_check(CLOCK_MONOTONIC); 1266 ... 1267} 1268 1269static void run(void) 1270{ 1271 ... 1272 tst_timer_start(CLOCK_MONOTONIC); 1273 ... 1274 while (!tst_timer_expired_ms(5000)) { 1275 ... 1276 } 1277 ... 1278} 1279 1280sturct tst_test test = { 1281 ... 1282 .setup = setup, 1283 .test_all = run, 1284 ... 1285}; 1286------------------------------------------------------------------------------- 1287 1288Expiration timer example usage. 1289 1290[source,c] 1291------------------------------------------------------------------------------- 1292long long tst_timespec_to_us(struct timespec t); 1293long long tst_timespec_to_ms(struct timespec t); 1294 1295struct timeval tst_us_to_timeval(long long us); 1296struct timeval tst_ms_to_timeval(long long ms); 1297 1298int tst_timespec_lt(struct timespec t1, struct timespec t2); 1299 1300struct timespec tst_timespec_add_us(struct timespec t, long long us); 1301 1302struct timespec tst_timespec_diff(struct timespec t1, struct timespec t2); 1303long long tst_timespec_diff_us(struct timespec t1, struct timespec t2); 1304long long tst_timespec_diff_ms(struct timespec t1, struct timespec t2); 1305 1306struct timespec tst_timespec_abs_diff(struct timespec t1, struct timespec t2); 1307long long tst_timespec_abs_diff_us(struct timespec t1, struct timespec t2); 1308long long tst_timespec_abs_diff_ms(struct timespec t1, struct timespec t2); 1309------------------------------------------------------------------------------- 1310 1311The first four functions are simple inline conversion functions. 1312 1313The 'tst_timespec_lt()' function returns non-zero if 't1' is earlier than 1314't2'. 1315 1316The 'tst_timespec_add_us()' function adds 'us' microseconds to the timespec 1317't'. The 'us' is expected to be positive. 1318 1319The 'tst_timespec_diff*()' functions returns difference between two times, the 1320't1' is expected to be later than 't2'. 1321 1322The 'tst_timespec_abs_diff*()' functions returns absolute value of difference 1323between two times. 1324 1325NOTE: All conversions to ms and us rounds the value. 1326 13272.2.22 Datafiles 1328^^^^^^^^^^^^^^^^ 1329 1330[source,c] 1331------------------------------------------------------------------------------- 1332#include "tst_test.h" 1333 1334static const char *const res_files[] = { 1335 "foo", 1336 "bar", 1337 NULL 1338}; 1339 1340static struct tst_test test = { 1341 ... 1342 .resource_files = res_files, 1343 ... 1344} 1345------------------------------------------------------------------------------- 1346 1347If the test needs additional files to be copied to the test temporary 1348directory all you need to do is to list their filenames in the 1349'NULL'-terminated array '.resource_files' in the tst_test structure. 1350 1351When resource files is set test temporary directory is created automatically, 1352there is need to set '.needs_tmpdir' as well. 1353 1354The test library looks for datafiles first, these are either stored in a 1355directory called +datafiles+ in the +$PWD+ at the start of the test or in 1356+$LTPROOT/testcases/data/${test_binary_name}+. If the file is not found the 1357library looks into +$LTPROOT/testcases/bin/+ and to +$PWD+ at the start of the 1358test. This ensures that the testcases can copy the file(s) effortlessly both 1359when test is started from the directory it was compiled in as well as when LTP 1360was installed. 1361 1362The file(s) are copied to the newly created test temporary directory which is 1363set as the test working directory when the 'test()' functions is executed. 1364 13652.2.23 Code path tracing 1366^^^^^^^^^^^^^^^^^^^^^^^^ 1367 1368'tst_res' is a macro, so on when you define a function in one file: 1369 1370[source,c] 1371------------------------------------------------------------------------------- 1372int do_action(int arg) 1373{ 1374 ... 1375 1376 if (ok) { 1377 tst_res(TPASS, "check passed"); 1378 return 0; 1379 } else { 1380 tst_res(TFAIL, "check failed"); 1381 return -1; 1382 } 1383} 1384------------------------------------------------------------------------------- 1385 1386and call it from another file, the file and line reported by 'tst_res' in this 1387function will be from the former file. 1388 1389'TST_TRACE' can make the analysis of such situations easier. It's a macro which 1390inserts a call to 'tst_res(TINFO, ...)' in case its argument evaluates to 1391non-zero. In this call to 'tst_res(TINFO, ...)' the file and line will be 1392expanded using the actual location of 'TST_TRACE'. 1393 1394For example, if this another file contains: 1395 1396[source,c] 1397------------------------------------------------------------------------------- 1398#include "tst_test.h" 1399 1400if (TST_TRACE(do_action(arg))) { 1401 ... 1402} 1403------------------------------------------------------------------------------- 1404 1405the generated output may look similar to: 1406 1407------------------------------------------------------------------------------- 1408common.h:9: FAIL: check failed 1409test.c:8: INFO: do_action(arg) failed 1410------------------------------------------------------------------------------- 1411 14122.2.24 Tainted kernels 1413^^^^^^^^^^^^^^^^^^^^^^ 1414 1415If you need to detect, if a testcase triggers a kernel warning, bug or oops, 1416the following can be used to detect TAINT_W or TAINT_D: 1417 1418[source,c] 1419------------------------------------------------------------------------------- 1420#include "tst_test.h" 1421#include "tst_taint.h" 1422 1423void setup(void) 1424{ 1425 ... 1426 tst_taint_init(TST_TAINT_W | TST_TAINT_D); 1427 ... 1428} 1429... 1430void run(void) 1431{ 1432 ... 1433 if (tst_taint_check() == 0) 1434 tst_res(TPASS, "kernel is not tainted"); 1435 else 1436 tst_res(TFAIL, "kernel is tainted"); 1437} 1438------------------------------------------------------------------------------- 1439 1440You have to call tst_taint_init() with non-zero flags first, preferably during 1441setup(). The function will generate a TCONF if the requested flags are not 1442fully supported on the running kernel, and TBROK if either a zero mask was 1443supplied or if the kernel is already tainted before executing the test. 1444 1445Then you can call tst_taint_check() during run(), which returns 0 or the 1446tainted flags set in /proc/sys/kernel/tainted as specified earlier. 1447 1448Depending on your kernel version, not all tainted-flags will be supported. 1449 1450For reference to tainted kernels, see kernel documentation: 1451Documentation/admin-guide/tainted-kernels.rst or 1452https://www.kernel.org/doc/html/latest/admin-guide/tainted-kernels.html 1453 14542.2.25 Checksums 1455^^^^^^^^^^^^^^^^ 1456 1457CRC32c checksum generation is supported by LTP. In order to use it, the 1458test should include "tst_checksum.h" header, then can call tst_crc32c(). 1459 14602.2.26 Checking kernel for the driver support 1461^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1462 1463Some tests may need specific kernel drivers, either compiled in, or built 1464as a module. If .need_drivers points to a NULL-terminated array of kernel 1465module names these are all checked and the test exits with TCONF on the 1466first missing driver. 1467 1468Since it relies on modprobe command, the check will be skipped if the command 1469itself is not available on the system. 1470 14712.2.27 Saving & restoring /proc|sys values 1472^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1473 1474LTP library can be instructed to save and restore value of specified 1475(/proc|sys) files. This is achieved by initialized tst_test struct 1476field 'save_restore'. It is a NULL terminated array of strings where 1477each string represents a file, whose value is saved at the beginning 1478and restored at the end of the test. Only first line of a specified 1479file is saved and restored. 1480 1481Pathnames can be optionally prefixed to specify how strictly (during 1482'store') are handled files that don't exist: 1483 (no prefix) - test ends with TCONF 1484 '?' - test prints info message and continues 1485 '!' - test ends with TBROK 1486 1487'restore' is always strict and will TWARN if it encounters any error. 1488 1489Example: 1490 1491static const char *save_restore[] = { 1492 "/proc/sys/kernel/core_pattern", 1493 NULL, 1494}; 1495 1496static void setup(void) 1497{ 1498 FILE_PRINTF("/proc/sys/kernel/core_pattern", "/mypath"); 1499} 1500 1501static struct tst_test test = { 1502 ... 1503 .setup = setup, 1504 .save_restore = save_restore, 1505}; 1506 1507 15082.3 Writing a testcase in shell 1509~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1510 1511LTP supports testcases to be written in a portable shell too. 1512 1513There is a shell library modeled closely to the C interface at 1514'testcases/lib/tst_test.sh'. 1515 1516WARNING: All identifiers starting with TST_ or tst_ are reserved for the 1517 test library. 1518 15192.3.1 Basic test interface 1520^^^^^^^^^^^^^^^^^^^^^^^^^^ 1521 1522[source,sh] 1523------------------------------------------------------------------------------- 1524#!/bin/sh 1525# 1526# This is a basic test for true shell buildin 1527# 1528 1529TST_TESTFUNC=do_test 1530. tst_test.sh 1531 1532do_test() 1533{ 1534 true 1535 ret=$? 1536 1537 if [ $ret -eq 0 ]; then 1538 tst_res TPASS "true returned 0" 1539 else 1540 tst_res TFAIL "true returned $ret" 1541 fi 1542} 1543 1544tst_run 1545------------------------------------------------------------------------------- 1546 1547TIP: To execute this test the 'tst_test.sh' library must be in '$PATH'. If you 1548 are executing the test from a git checkout you can run it as 1549 'PATH="$PATH:../../lib" ./foo01.sh' 1550 1551The shell library expects test setup, cleanup and the test function executing 1552the test in the '$TST_SETUP', '$TST_CLEANUP' and '$TST_TESTFUNC' variables. 1553 1554Both '$TST_SETUP' and '$TST_CLEANUP' are optional. 1555 1556The '$TST_TESTFUNC' may be called several times if more than one test 1557iteration was requested by passing right command line options to the test. 1558 1559The '$TST_CLEANUP' may be called even in the middle of the setup and must be 1560able to clean up correctly even in this situation. The easiest solution for 1561this is to keep track of what was initialized and act accordingly in the 1562cleanup. 1563 1564WARNING: Similar to the C library, calling tst_brk() in the $TST_CLEANUP does 1565 not exit the test and 'TBROK' is converted to 'TWARN'. 1566 1567Notice also the 'tst_run' function called at the end of the test that actually 1568starts the test. 1569 1570[source,sh] 1571------------------------------------------------------------------------------- 1572#!/bin/sh 1573# 1574# Example test with tests in separate functions 1575# 1576 1577TST_TESTFUNC=test 1578TST_CNT=2 1579. tst_test.sh 1580 1581test1() 1582{ 1583 tst_res TPASS "Test $1 passed" 1584} 1585 1586test2() 1587{ 1588 tst_res TPASS "Test $1 passed" 1589} 1590 1591tst_run 1592# output: 1593# foo 1 TPASS: Test 1 passed 1594# foo 2 TPASS: Test 2 passed 1595------------------------------------------------------------------------------- 1596 1597If '$TST_CNT' is set, the test library looks if there are functions named 1598'$\{TST_TESTFUNC\}1', ..., '$\{TST_TESTFUNC\}$\{TST_CNT\}' and if these are 1599found they are executed one by one. The test number is passed to it in the '$1'. 1600 1601[source,sh] 1602------------------------------------------------------------------------------- 1603#!/bin/sh 1604# 1605# Example test with tests in a single function 1606# 1607 1608TST_TESTFUNC=do_test 1609TST_CNT=2 1610. tst_test.sh 1611 1612do_test() 1613{ 1614 case $1 in 1615 1) tst_res TPASS "Test $1 passed";; 1616 2) tst_res TPASS "Test $1 passed";; 1617 esac 1618} 1619 1620tst_run 1621# output: 1622# foo 1 TPASS: Test 1 passed 1623# foo 2 TPASS: Test 2 passed 1624------------------------------------------------------------------------------- 1625 1626Otherwise, if '$TST_CNT' is set but there is no '$\{TST_TESTFUNC\}1', etc., 1627the '$TST_TESTFUNC' is executed '$TST_CNT' times and the test number is passed 1628to it in the '$1'. 1629 1630[source,sh] 1631------------------------------------------------------------------------------- 1632#!/bin/sh 1633# 1634# Example test with tests in a single function, using $TST_TEST_DATA and 1635# $TST_TEST_DATA_IFS 1636# 1637 1638TST_TESTFUNC=do_test 1639TST_TEST_DATA="foo:bar:d dd" 1640TST_TEST_DATA_IFS=":" 1641. tst_test.sh 1642 1643do_test() 1644{ 1645 tst_res TPASS "Test $1 passed with data '$2'" 1646} 1647 1648tst_run 1649# output: 1650# foo 1 TPASS: Test 1 passed with data 'foo' 1651# foo 2 TPASS: Test 1 passed with data 'bar' 1652# foo 3 TPASS: Test 1 passed with data 'd dd' 1653------------------------------------------------------------------------------- 1654 1655It's possible to pass data for function with '$TST_TEST_DATA'. Optional 1656'$TST_TEST_DATA_IFS' is used for splitting, default value is space. 1657 1658[source,sh] 1659------------------------------------------------------------------------------- 1660#!/bin/sh 1661# 1662# Example test with tests in a single function, using $TST_TEST_DATA and $TST_CNT 1663# 1664 1665TST_TESTFUNC=do_test 1666TST_CNT=2 1667TST_TEST_DATA="foo bar" 1668. tst_test.sh 1669 1670do_test() 1671{ 1672 case $1 in 1673 1) tst_res TPASS "Test $1 passed with data '$2'";; 1674 2) tst_res TPASS "Test $1 passed with data '$2'";; 1675 esac 1676} 1677 1678tst_run 1679# output: 1680# foo 1 TPASS: Test 1 passed with data 'foo' 1681# foo 2 TPASS: Test 2 passed with data 'foo' 1682# foo 3 TPASS: Test 1 passed with data 'bar' 1683# foo 4 TPASS: Test 2 passed with data 'bar' 1684------------------------------------------------------------------------------- 1685 1686'$TST_TEST_DATA' can be used with '$TST_CNT'. If '$TST_TEST_DATA_IFS' not specified, 1687space as default value is used. Of course, it's possible to use separate functions. 1688 16892.3.2 Library variables 1690^^^^^^^^^^^^^^^^^^^^^^^ 1691 1692Similarily to the C library various checks and preparations can be requested 1693simply by setting right '$TST_NEEDS_FOO'. 1694 1695[options="header"] 1696|============================================================================= 1697| Variable name | Action done 1698| 'TST_NEEDS_ROOT' | Exit the test with 'TCONF' unless executed under root 1699| 'TST_NEEDS_TMPDIR' | Create test temporary directory and cd into it. 1700| 'TST_NEEDS_DEVICE' | Prepare test temporary device, the path to testing 1701 device is stored in '$TST_DEVICE' variable. 1702| 'TST_NEEDS_CMDS' | String with command names that has to be present for 1703 the test (see below). 1704| 'TST_NEEDS_MODULE' | Test module name needed for the test (see below). 1705| 'TST_NEEDS_DRIVERS'| Checks kernel drivers support for the test. 1706|============================================================================= 1707 1708Checking for presence of commands 1709+++++++++++++++++++++++++++++++++ 1710 1711[source,sh] 1712------------------------------------------------------------------------------- 1713#!/bin/sh 1714 1715... 1716 1717TST_NEEDS_CMDS="modinfo modprobe" 1718. tst_test.sh 1719 1720... 1721 1722------------------------------------------------------------------------------- 1723 1724Setting '$TST_NEEDS_CMDS' to a string listing required commands will check for 1725existence each of them and exits the test with 'TCONF' on first misssing. 1726 1727Alternatively the 'tst_test_cmds()' function can be used to do the same on 1728runtime, since sometimes we need to the check at runtime too. 1729 1730'tst_check_cmds()' can be used for requirements just for a particular test 1731as it doesn't exit (it issues 'tst_res TCONF'). Expected usage is: 1732... 1733 1734TST_TESTFUNC=do_test 1735. tst_test.sh 1736 1737do_test() 1738{ 1739 tst_check_cmds cmd || return 1740 cmd --foo 1741 ... 1742} 1743 1744tst_run 1745... 1746 1747Locating kernel modules 1748+++++++++++++++++++++++ 1749 1750The LTP build system can build kernel modules as well, setting 1751'$TST_NEEDS_MODULE' to module name will cause to library to look for the 1752module in a few possible paths. 1753 1754If module was found the path to it will be stored into '$TST_MODPATH' 1755variable, if module wasn't found the test will exit with 'TCONF'. 1756 17572.3.3 Optional command line parameters 1758^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1759 1760[source,sh] 1761------------------------------------------------------------------------------- 1762#!/bin/sh 1763# 1764# Optional test command line parameters 1765# 1766 1767TST_OPTS="af:" 1768TST_USAGE=usage 1769TST_PARSE_ARGS=parse_args 1770TST_TESTFUNC=do_test 1771 1772. tst_test.sh 1773 1774ALTERNATIVE=0 1775MODE="foo" 1776 1777usage() 1778{ 1779 cat << EOF 1780usage: $0 [-a] [-f <foo|bar>] 1781 1782OPTIONS 1783-a Enable support for alternative foo 1784-f Specify foo or bar mode 1785EOF 1786} 1787 1788parse_args() 1789{ 1790 case $1 in 1791 a) ALTERNATIVE=1;; 1792 f) MODE="$2";; 1793 esac 1794} 1795 1796do_test() 1797{ 1798 ... 1799} 1800 1801tst_run 1802------------------------------------------------------------------------------- 1803 1804The 'getopts' string for optional parameters is passed in the '$TST_OPTS' 1805variable. There are a few default parameters that cannot be used by a test, 1806these can be listed with passing help '-h' option to any test. 1807 1808The function that prints the usage is passed in '$TST_USAGE', the help for 1809the options implemented in the library is appended when usage is printed. 1810 1811Lastly the fucntion '$PARSE_ARGS' is called with the option name in the '$1' 1812and, if option has argument, its value in the '$2'. 1813 1814[source,sh] 1815------------------------------------------------------------------------------- 1816#!/bin/sh 1817# 1818# Optional test positional parameters 1819# 1820 1821TST_POS_ARGS=3 1822TST_USAGE=usage 1823TST_TESTFUNC=do_test 1824 1825. tst_test.sh 1826 1827usage() 1828{ 1829 cat << EOF 1830usage: $0 [min] [max] [size] 1831 1832EOF 1833} 1834 1835min="$1" 1836max="$2" 1837size="$3" 1838 1839do_test() 1840{ 1841 ... 1842} 1843 1844tst_run 1845------------------------------------------------------------------------------- 1846 1847You can also request a number of positional parameters by setting the 1848'$TST_POS_ARGS' variable. If you do, these will be available as they were 1849passed directly to the script in '$1', '$2', ..., '$n'. 1850 18512.3.4 Usefull library functions 1852^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1853 1854Retrieving configuration variables 1855++++++++++++++++++++++++++++++++++ 1856 1857You may need to retrieve configuration values such as PAGESIZE, there is 1858'getconf' but as some system may not have it, you are advised to use 1859'tst_getconf' instead. Note that it implements subset of 'getconf' 1860system variables used by the testcases only. 1861 1862[source,sh] 1863------------------------------------------------------------------------------- 1864# retrieve PAGESIZE 1865pagesize=`tst_getconf PAGESIZE` 1866------------------------------------------------------------------------------- 1867 1868Sleeping for subsecond intervals 1869++++++++++++++++++++++++++++++++ 1870 1871Albeit there is a sleep command available basically everywhere not all 1872implementations can support sleeping for less than one second. And most of the 1873time sleeping for a second is too much. Therefore LTP includes 'tst_sleep' 1874that can sleep for defined amount of seconds, milliseconds or microseconds. 1875 1876[source,sh] 1877------------------------------------------------------------------------------- 1878# sleep for 100 milliseconds 1879tst_sleep 100ms 1880------------------------------------------------------------------------------- 1881 1882Retry a function in limited time 1883++++++++++++++++++++++++++++++++ 1884 1885Sometimes LTP test needs retrying a function for many times to get success. 1886This achievement makes that possible via keeping it retrying if the return 1887value of the function is NOT as we expected. After exceeding a limited time, 1888test will break from the retries immediately. 1889 1890[source,c] 1891------------------------------------------------------------------------------- 1892# retry function in 1 second 1893TST_RETRY_FUNC(FUNC, EXPECTED_RET) 1894 1895# retry function in N second 1896TST_RETRY_FN_EXP_BACKOFF(FUNC, EXPECTED_RET, N) 1897------------------------------------------------------------------------------- 1898 1899[source,sh] 1900------------------------------------------------------------------------------- 1901# retry function in 1 second 1902TST_RETRY_FUNC "FUNC arg1 arg2 ..." "EXPECTED_RET" 1903 1904# retry function in N second 1905TST_RETRY_FN_EXP_BACKOFF "FUNC arg1 arg2 ..." "EXPECTED_RET" "N" 1906------------------------------------------------------------------------------- 1907 1908Checking for integers 1909+++++++++++++++++++++ 1910 1911[source,sh] 1912------------------------------------------------------------------------------- 1913# returns zero if passed an integer parameter, non-zero otherwise 1914tst_is_int "$FOO" 1915------------------------------------------------------------------------------- 1916 1917Obtaining random numbers 1918++++++++++++++++++++++++ 1919 1920There is no '$RANDOM' in portable shell, use 'tst_random' instead. 1921 1922[source,sh] 1923------------------------------------------------------------------------------- 1924# get random integer between 0 and 1000 (including 0 and 1000) 1925tst_random 0 1000 1926------------------------------------------------------------------------------- 1927 1928Formatting device with a filesystem 1929+++++++++++++++++++++++++++++++++++ 1930 1931The 'tst_mkfs' helper will format device with the filesystem. 1932 1933[source,sh] 1934------------------------------------------------------------------------------- 1935# format test device with ext2 1936tst_mkfs ext2 $TST_DEVICE 1937------------------------------------------------------------------------------- 1938 1939Umounting filesystems 1940+++++++++++++++++++++ 1941 1942The 'tst_umount' helper is a safe way to umount a filesystem. 1943 1944If the path passed to the function is not mounted (present in '/proc/mounts') 1945it's noop. 1946 1947Otherwise it retries to umount the filesystem a few times on a failure, which 1948is a workaround since there are a daemons dumb enough to probe all newly 1949mounted filesystems, which prevents them from umounting shortly after they 1950were mounted. 1951 1952Running commands as different user with 'su' 1953++++++++++++++++++++++++++++++++++++++++++++ 1954 1955While some distributions retain paths added to +$PATH+ when doing 1956+su user -c "command"+ this does not work at least in Debian. If you want to 1957run LTP binaries as a different user you must use 'tst_su' instead which sets 1958up +$PATH+ and the runs the command. 1959 1960.Run test child binary as a test user 1961[source,sh] 1962------------------------------------------------------------------------------- 1963#!/bin/sh 1964TCID=foo01 1965. test.sh 1966 1967tst_su testusr foo01_child 1968if [ $? -ne 0 ]; then 1969 tst_resm TFAIL "foo failed" 1970else 1971 tst_resm TPASS "foo passed" 1972fi 1973------------------------------------------------------------------------------- 1974 1975ROD and ROD_SILENT 1976++++++++++++++++++ 1977 1978These functions supply the 'SAFE_MACROS' used in C although they work and are 1979named differently. 1980 1981[source,sh] 1982------------------------------------------------------------------------------- 1983ROD_SILENT command arg1 arg2 ... 1984 1985# is shorthand for: 1986 1987command arg1 arg2 ... > /dev/null 2>&1 1988if [ $? -ne 0 ]; then 1989 tst_brkm TBROK "..." 1990fi 1991 1992 1993ROD command arg1 arg2 ... 1994 1995# is shorthand for: 1996 1997ROD arg1 arg2 ... 1998if [ $? -ne 0 ]; then 1999 tst_brkm TBROK "..." 2000fi 2001------------------------------------------------------------------------------- 2002 2003WARNING: Keep in mind that output redirection (to a file) happens in the 2004 caller rather than in the ROD function and cannot be checked for 2005 write errors by the ROD function. 2006 2007As a matter of a fact doing +ROD echo a > /proc/cpuinfo+ would work just fine 2008since the 'ROD' function will only get the +echo a+ part that will run just 2009fine. 2010 2011[source,sh] 2012------------------------------------------------------------------------------- 2013# Redirect output to a file with ROD 2014ROD echo foo \> bar 2015------------------------------------------------------------------------------- 2016 2017Note the '>' is escaped with '\', this causes that the '>' and filename are 2018passed to the 'ROD' function as parameters and the 'ROD' function contains 2019code to split '$@' on '>' and redirects the output to the file. 2020 2021EXPECT_PASS and EXPECT_FAIL 2022+++++++++++++++++++++++++++ 2023 2024[source,sh] 2025------------------------------------------------------------------------------- 2026EXPECT_PASS command arg1 arg2 ... [ \> file ] 2027EXPECT_FAIL command arg1 arg2 ... [ \> file ] 2028------------------------------------------------------------------------------- 2029 2030'EXPECT_PASS' calls 'tst_resm TPASS' if the command exited with 0 exit code, 2031and 'tst_resm TFAIL' otherwise. 'EXPECT_FAIL' does vice versa. 2032 2033Output redirection rules are the same as for the 'ROD' function. In addition 2034to that, 'EXPECT_FAIL' always redirects the command's stderr to '/dev/null'. 2035 2036tst_kvcmp 2037+++++++++ 2038 2039This command compares the currently running kernel version given conditions 2040with syntax similar to the shell test command. 2041 2042[source,sh] 2043------------------------------------------------------------------------------- 2044# Exit the test if kernel version is older or equal to 2.6.8 2045if tst_kvcmp -le 2.6.8; then 2046 tst_brk TCONF "Kernel newer than 2.6.8 is needed" 2047fi 2048 2049# Exit the test if kernel is newer than 3.8 and older than 4.0.1 2050if tst_kvcmp -gt 3.8 -a -lt 4.0.1; then 2051 tst_brk TCONF "Kernel must be older than 3.8 or newer than 4.0.1" 2052fi 2053------------------------------------------------------------------------------- 2054 2055[options="header"] 2056|======================================================================= 2057| expression | description 2058| -eq kver | Returns true if kernel version is equal 2059| -ne kver | Returns true if kernel version is not equal 2060| -gt kver | Returns true if kernel version is greater 2061| -ge kver | Returns true if kernel version is greater or equal 2062| -lt kver | Returns true if kernel version is lesser 2063| -le kver | Returns true if kernel version is lesser or equal 2064| -a | Does logical and between two expressions 2065| -o | Does logical or between two expressions 2066|======================================================================= 2067 2068The format for kernel version has to either be with one dot e.g. '2.6' or with 2069two dots e.g. '4.8.1'. 2070 2071.tst_fs_has_free 2072[source,sh] 2073------------------------------------------------------------------------------- 2074#!/bin/sh 2075 2076... 2077 2078# whether current directory has 100MB free space at least. 2079if ! tst_fs_has_free . 100MB; then 2080 tst_brkm TCONF "Not enough free space" 2081fi 2082 2083... 2084------------------------------------------------------------------------------- 2085 2086The 'tst_fs_has_free' shell interface returns 0 if the specified free space is 2087satisfied, 1 if not, and 2 on error. 2088 2089The second argument supports suffixes kB, MB and GB, the default unit is Byte. 2090 2091.tst_retry 2092[source,sh] 2093------------------------------------------------------------------------------- 2094#!/bin/sh 2095 2096... 2097 2098# Retry ping command three times 2099tst_retry "ping -c 1 127.0.0.1" 2100 2101if [ $? -ne 0 ]; then 2102 tst_resm TFAIL "Failed to ping 127.0.0.1" 2103else 2104 tst_resm TPASS "Successfully pinged 127.0.0.1" 2105fi 2106 2107... 2108------------------------------------------------------------------------------- 2109 2110The 'tst_retry' function allows you to retry a command after waiting small 2111amount of time until it succeeds or until given amount of retries has been 2112reached (default is three attempts). 2113 21142.3.5 Restarting daemons 2115^^^^^^^^^^^^^^^^^^^^^^^^ 2116 2117Restarting system daemons is a complicated task for two reasons. 2118 2119* There are different init systems 2120 (SysV init, systemd, etc...) 2121 2122* Daemon names are not unified between distributions 2123 (apache vs httpd, cron vs crond, various syslog variations) 2124 2125To solve these problems LTP has 'testcases/lib/daemonlib.sh' library that 2126provides functions to start/stop/query daemons as well as variables that store 2127correct daemon name. 2128 2129.Supported operations 2130|============================================================================== 2131| start_daemon() | Starts daemon, name is passed as first parameter. 2132| stop_daemon() | Stops daemon, name is passed as first parameter. 2133| restart_daemon() | Restarts daemon, name is passed as first parameter. 2134| status_daemon() | Detect daemon status (exit code: 0: running, 1: not running). 2135|============================================================================== 2136 2137.Variables with detected names 2138|============================================================================== 2139| CROND_DAEMON | Cron daemon name (cron, crond). 2140| SYSLOG_DAEMON | Syslog daemon name (syslog, syslog-ng, rsyslog). 2141|============================================================================== 2142 2143.Cron daemon restart example 2144[source,sh] 2145------------------------------------------------------------------------------- 2146#!/bin/sh 2147# 2148# Cron daemon restart example 2149# 2150TCID=cron01 2151TST_COUNT=1 2152. test.sh 2153. daemonlib.sh 2154 2155... 2156 2157restart_daemon $CROND_DAEMON 2158 2159... 2160 2161tst_exit 2162------------------------------------------------------------------------------- 2163 21642.3.6 Access to the checkpoint interface 2165~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2166 2167The shell library provides an implementation of the checkpoint interface 2168compatible with the C version. All TST_CHECKPOINT_* functions are available. 2169 2170In order to initialize checkpoints '$TST_NEEDS_CHECKPOINTS' must be set to '1' 2171before the inclusion of 'test.sh': 2172 2173[source,sh] 2174------------------------------------------------------------------------------- 2175#!/bin/sh 2176 2177TST_NEEDS_CHECKPOINTS=1 2178. test.sh 2179------------------------------------------------------------------------------- 2180 2181Since both the implementations are compatible, it's also possible to start 2182a child binary process from a shell test and synchronize with it. This process 2183must have checkpoints initialized by calling tst_reinit()'. 2184 21853. Common problems 2186------------------ 2187 2188This chapter describes common problems/misuses and less obvious design patters 2189(quirks) in UNIX interfaces. Read it carefully :) 2190 21913.1 umask() 2192~~~~~~~~~~~ 2193 2194I've been hit by this one several times already... When you create files 2195with 'open()' or 'creat()' etc, the mode specified as the last parameter *is 2196not* the mode the file is created with. The mode depends on current 'umask()' 2197settings which may clear some of the bits. If your test depends on specific 2198file permissions you need either to change umask to 0 or 'chmod()' the file 2199afterwards or use SAFE_TOUCH() that does the 'chmod()' for you. 2200 22013.2 access() 2202~~~~~~~~~~~ 2203 2204If 'access(some_file, W_OK)' is executed by root, it will return success even 2205if the file doesn't have write permission bits set (the same holds for R_OK 2206too). For sysfs files you can use 'open()' as a workaround to check file 2207read/write permissions. It might not work for other filesystems, for these you 2208have to use 'stat()', 'lstat()' or 'fstat()'. 2209 22103.3 umount() EBUSY 2211~~~~~~~~~~~~~~~~~~ 2212 2213Various desktop daemons (gvfsd-trash is known for that) may be stupid enough 2214to probe all newly mounted filesystem which results in 'umount(2)' failing 2215with 'EBUSY'; use 'tst_umount()' described in 2.2.19 that retries in this case 2216instead of plain 'umount(2)'. 2217 22183.4 FILE buffers and fork() 2219~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2220 2221Be vary that if a process calls 'fork(2)' the child process inherits open 2222descriptors as well as copy of the parent memory so especially if there are 2223any open 'FILE' buffers with a data in them they may be written both by the 2224parent and children resulting in corrupted/duplicated data in the resulting 2225files. 2226 2227Also open 'FILE' streams are flushed and closed at 'exit(3)' so if your 2228program works with 'FILE' streams, does 'fork(2)', and the child may end up 2229calling 'exit(3)' you will likely end up with corrupted files. 2230 2231The solution to this problem is either simply call 'fflush(NULL)' that flushes 2232all open output 'FILE' streams just before doing 'fork(2)'. You may also use 2233'_exit(2)' in child processes which does not flush 'FILE' buffers and also 2234skips 'atexit(3)' callbacks. 2235 22364. Test Contribution Checklist 2237------------------------------ 2238 22391. Test compiles and runs fine (check with -i 10 too) 22402. Checkpatch does not report any errors 22413. The runtest entires are in place 22424. Test files are added into corresponding .gitignore files 22435. Patches apply over the latest git 2244 2245 22464.1 About .gitignore files 2247~~~~~~~~~~~~~~~~~~~~~~~~~~ 2248 2249There are numerous '.gitignore' files in the LTP tree. Usually there is a 2250'.gitignore' file per a group of tests. The reason for this setup is simple. 2251It's easier to maintain a '.gitignore' file per directory with tests, rather 2252than having single file in the project root directory. This way, we don't have 2253to update all the gitignore files when moving directories, and they get deleted 2254automatically when a directory with tests is removed. 2255