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 64You can either try to run the testcases on Debian which has '/bin/sh' pointing 65to 'dash' by default or install 'dash' on your favorite distribution and use 66it to run the tests. If your distribution lacks 'dash' package you can always 67compile it from http://gondor.apana.org.au/~herbert/dash/files/[source]. 68 69Debian also has nice devscript 70https://anonscm.debian.org/cgit/collab-maint/devscripts.git/tree/scripts/checkbashisms.pl[checkbashism.pl] 71that can be used to check for non-portable shell code. 72 73Here are some common sense style rules for shell 74 75* Keep lines under 80 chars 76 77* Use tabs for indentation 78 79* Keep things simple, avoid unnecessary subshells 80 81* Don't do confusing things (i.e. don't name your functions like common shell 82 commands, etc.) 83 84* Quote variables 85 86* Be consistent 87 881.4 Commenting code 89~~~~~~~~~~~~~~~~~~~ 90 91Comments can sometimes save you day but they can easily do more harm than 92good. There has been several cases where comments and actual implementation 93were drifting slowly apart which yielded into API misuses and hard to find 94bugs. Remember there is only one thing worse than no documentation, wrong 95documentation. 96 97Generally everybody should write code that is obvious (which unfortunately 98isn't always possible). If there is a code that needs to be commented keep it 99short and to the point. Never ever comment the obvious. 100 101In case of LTP testcases it's customary to add a paragraph with highlevel test 102description somewhere at the beginning of the file (usually right under the GPL 103header). This helps other people to understand the overall goal of the test 104before they dive into the technical details. 105 1061.5 Backwards compatibility 107~~~~~~~~~~~~~~~~~~~~~~~~~~~ 108 109LTP test should be as backward compatible as possible. Think of an enterprise 110distributions with long term support (more than five years since the initial 111release) or of an embedded platform that needs to use several years old 112toolchain supplied by the manufacturer. 113 114Therefore LTP test for more current features should be able to cope with older 115systems. It should at least compile fine and if it's not appropriate for the 116configuration it should return 'TCONF' (see test interface description below). 117 118There are several types of checks we use: 119 120The *configure script* is usually used to detect availability of a function 121declarations in system headers. It's used to disable tests at compile time. 122 123We also have runtime kernel version detection that can be used to disable 124tests at runtime. 125 126Checking the *errno* value is another type of runtime check. Most of the 127syscalls returns either 'EINVAL' or 'ENOSYS' when syscall was not implemented 128or was disabled upon kernel compilation. 129 130Sometimes it also makes sense to define a few macros instead of creating 131configure test. One example are Linux specific POSIX clock ids in 132'include/lapi/posix_clocks.h'. 133 1341.6 Dealing with messed up legacy code 135~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 136 137LTP contains a lot of old and messy code and we are cleaning it up as fast as 138we can but despite the efforts there is still a lot. If you start modifying 139old or a messed up testcase and your changes are more complicated than simple 140typo fixes you should do a cleanup first (in a separate patch). It's easier to 141review the changes if you separate the formatting fixes from the changes that 142affects the test behavior. 143 144The same goes for moving files. If you need a rename or move file do it in a 145separate patch. 146 1471.7 License 148~~~~~~~~~~~ 149 150Code contributed to LTP should be licensed under GPLv2+ (GNU GPL version 2 or 151any later version). 152 1532. Writing a testcase 154--------------------- 155 1562.1 LTP Structure 157~~~~~~~~~~~~~~~~~ 158 159The structure of LTP is quite simple. Each test is a binary written either in 160portable shell or C. The test gets a configuration via environment variables 161and/or command line parameters, it prints additional information into the 162stdout and reports overall success/failure via the exit value. 163 164Tests are generally placed under the 'testcases/' directory. Everything that 165is a syscall or (slightly confusingly) libc syscall wrapper goes under 166'testcases/kernel/syscalls/'. Then there is 'testcases/open_posix_testsuite' 167which is a well maintained fork of the upstream project that has been dead 168since 2005 and also a number of directories with tests for more specific 169features. 170 1712.1.1 Runtest Files 172^^^^^^^^^^^^^^^^^^^ 173 174The list of tests to be executed is stored in runtest files under the 175'runtest/' directory. The default set of runtest files to be executed is 176stored in 'scenario_groups/default'. When you add a test you should add 177corresponding entries into some runtest file(s) as well. 178 179For syscall tests (these placed under 'testcases/kernel/syscalls/') use 180'runtest/syscalls' file, for kernel related tests for memory management we 181have 'runtest/mm', etc. 182 183IMPORTANT: The runtest files should have one entry per a test. Creating a 184 wrapper that runs all your tests and adding it as a single test 185 into runtest file is strongly discouraged. 186 1872.1.2 Datafiles 188^^^^^^^^^^^^^^^ 189 190If your test needs datafiles to work, these should be put into a subdirectory 191named 'datafiles' and installed into the 'testcases/data/$TCID' directory (to 192do that you have to add 'INSTALL_DIR := testcases/data/TCID' into the 193'datafiles/Makefile'). 194 195You can obtain path to datafiles via $LTP_DATAROOT provided by test.sh 196'$LTP_DATAROOT/...' 197or via C function 'tst_dataroot()' provided by libltp: 198 199[source,c] 200------------------------------------------------------------------------------- 201const char *dataroot = tst_dataroot(); 202------------------------------------------------------------------------------- 203 204Datafiles can also be accessed as '$LTPROOT/testcases/data/$TCID/...', 205but '$LTP_DATAROOT' and 'tst_dataroot()' are preferred as these can be used 206when running testcases directly in git tree as well as from install 207location. 208 209The path is constructed according to these rules: 210 2111. if '$LTPROOT' is set, return '$LTPROOT/testcases/data/$TCID' 2122. else if 'tst_tmpdir()' was called return '$STARTWD/datafiles' 213 (where '$STARTWD' is initial working directory as recorded by 'tst_tmdir()') 2143. else return '$CWD/datafiles' 215 216See 'testcases/commands/ade/ldd/ldd01' for example. 217 2182.1.3 Subexecutables 219^^^^^^^^^^^^^^^^^^^^ 220 221If you test needs to execute a binary, place it in the same directory as the 222testcase and name the file starting with testname_ ('.tid' see below). 223Once the test is executed by the framework, the path to the directory with all 224LTP binaries is added to the '$PATH' and you can execute it just by its name. 225 226TIP: If you need to execute such test from the LTP tree, you can add path to 227 current directory to '$PATH' manually with: 'PATH="$PATH:$PWD" ./foo01'. 228 2292.2 Writing a test in C 230~~~~~~~~~~~~~~~~~~~~~~~ 231 2322.2.1 Basic test structure 233^^^^^^^^^^^^^^^^^^^^^^^^^^ 234 235Let's start with an example, following code is a simple test for a 'getenv()'. 236 237[source,c] 238------------------------------------------------------------------------------- 239/* 240 * This is test for basic functionality of getenv(). 241 * 242 * - create an env variable and verify that getenv() can get get it 243 * - call getenv() with nonexisting variable name, check that it returns NULL 244 */ 245 246#include "tst_test.h" 247 248#define ENV1 "LTP_TEST_ENV" 249#define ENV2 "LTP_TEST_THIS_DOES_NOT_EXIST" 250#define ENV_VAL "val" 251 252static void setup(void) 253{ 254 if (setenv(ENV1, ENV_VAL, 1)) 255 tst_brk(TBROK | TERRNO, "setenv() failed"); 256} 257 258static void test(void) 259{ 260 char *ret; 261 262 ret = getenv(ENV1); 263 264 if (!ret) { 265 tst_res(TFAIL, "getenv(" ENV1 ") = NULL"); 266 goto next; 267 } 268 269 if (!strcmp(ret, ENV_VAL)) { 270 tst_res(TPASS, "getenv(" ENV1 ") = '"ENV_VAL "'"); 271 } else { 272 tst_res(TFAIL, "getenv(" ENV1 ") = '%s', expected '" 273 ENV_VAL "'", ret); 274 } 275 276next: 277 ret = getenv(ENV2); 278 279 if (ret) 280 tst_res(TFAIL, "getenv(" ENV2 ") = '%s'", ret); 281 else 282 tst_res(TPASS, "getenv(" ENV2 ") = NULL"); 283} 284 285static struct tst_test test = { 286 .tid = "getenv01", 287 .test_all = test, 288 .setup = setup, 289}; 290------------------------------------------------------------------------------- 291 292Each test includes the 'tst_test.h' header and must define the 'struct 293tst_test test' structure. 294 295The '.tid' defines test name (usually syscall/libcall name + number). The name 296is used in the test results as well as a base for temporary directory name if 297temporary directory is needed. In most of the cases it's the same as test 298filename without the extension. 299 300The overall test initialization is done in the 'setup()' function. 301 302The overall cleanup is done in a 'cleanup()' function. Here 'cleanup()' is 303omitted as the test does not have anything to clean up. If cleanup is set in 304the test structure it's called on test exit just before the test library 305cleanup. That especially means that cleanup can be called at any point in a 306test execution. For example even when a test setup step has failed, therefore 307the 'cleanup()' function must be able to cope with unfinished initialization, 308and so on. 309 310The test itself is done in the 'test()' function. The test function must work 311fine if called in a loop. 312 313There are two types of a test function pointers in the test structure. The 314first one is a '.test_all' pointer that is used when test is implemented as a 315single function. Then there is a '.test' function along with the number of 316tests '.tcnt' that allows for more detailed result reporting. If the '.test' 317pointer is set the function is called '.tcnt' times with an integer parameter 318in range of [0, '.tcnt' - 1]. 319 320IMPORTANT: Only one of '.test' and '.test_all' can be set at a time. 321 322A word about the cleanup() callback 323+++++++++++++++++++++++++++++++++++ 324 325There are a few rules that needs to be followed in order to write correct 326cleanup() callback. 327 3281. Free only resources that were initialized. Keep in mind that callback can 329 be executed at any point in the test run. 330 3312. Make sure to free resources in the reverse order they were 332 initialized. (Some of the steps may not depend on others and everything 333 will work if there were swapped but let's keep it in order.) 334 3353. Avoid using SAFE_MACROS() in cleanup if you want the cleanup to carry on 336 when a cleanup step has failed. 337 338The first rule may seem complicated at first however, on the contrary, it's 339quite easy. All you have to do is to keep track of what was already 340initialized. For example file descriptors needs to be closed only if they were 341assigned a valid file descriptor. For most of the things you need to create 342extra flag that is set right after successful initialization though. Consider, 343for example, test setup below. 344 345[source,c] 346------------------------------------------------------------------------------- 347static int fd0, fd1, mount_flag; 348 349#define MNTPOINT "mntpoint" 350#define FILE1 "mntpoint/file1" 351#define FILE2 "mntpoint/file2" 352 353static void setup(void) 354{ 355 SAFE_MKDIR(MNTPOINT, 0777); 356 SAFE_MKFS(tst_device->dev, tst_device->fs_type, NULL, NULL); 357 SAFE_MOUNT(tst_device->dev, MNTPOINT, tst_device->fs_type, 0, 0); 358 mount_flag = 1; 359 360 fd0 = SAFE_OPEN(cleanup, FILE1, O_CREAT | O_RDWR, 0666); 361 fd1 = SAFE_OPEN(cleanup, FILE2, O_CREAT | O_RDWR, 0666); 362} 363------------------------------------------------------------------------------- 364 365In this case the 'cleanup()' function may be invoked when any of the 'SAFE_*' 366macros has failed and therefore must be able to work with unfinished 367initialization as well. Since global variables are initialized to zero we can 368just check that fd > 0 before we attempt to close it. The mount function 369requires extra flag to be set after device was successfully mounted. 370 371[source,c] 372------------------------------------------------------------------------------- 373static void cleanup(void) 374{ 375 if (fd1 > 0 && close(fd1)) 376 tst_res(TWARN | TERRNO, "close(fd1)"); 377 378 if (fd0 > 0 && close(fd0)) 379 tst_res(TWARN | TERRNO, "close(fd0)"); 380 381 if (mount_flag && tst_umouont(MNTPOINT)) 382 tst_res(TBROK | TERRNO, "umount(%s)", MNTPOINT); 383} 384------------------------------------------------------------------------------- 385 386NOTE: Creation and removal of the test temporary directory is handled in 387 the test library and the directory is removed recursively. Therefore 388 we do not have to remove files and directories in the test cleanup. 389 3902.2.2 Basic test interface 391^^^^^^^^^^^^^^^^^^^^^^^^^^ 392 393[source,c] 394------------------------------------------------------------------------------- 395void tst_res(int ttype, char *arg_fmt, ...); 396------------------------------------------------------------------------------- 397 398Printf-like function to report test result, it's mostly used with ttype: 399 400|============================== 401| 'TPASS' | Test has passed. 402| 'TFAIL' | Test has failed. 403| 'TINFO' | General message. 404|============================== 405 406The 'ttype' can be combined bitwise with 'TERRNO' or 'TTERRNO' to print 407'errno', 'TEST_ERRNO' respectively. 408 409[source,c] 410------------------------------------------------------------------------------- 411void tst_brk(int ttype, char *arg_fmt, ...); 412------------------------------------------------------------------------------- 413 414Printf-like function to report error and exit the test, it can be used with ttype: 415 416|============================================================ 417| 'TBROK' | Something has failed in test preparation phase. 418| 'TCONF' | Test is not appropriate for current configuration 419 (syscall not implemented, unsupported arch, ...) 420|============================================================ 421 422The 'ttype' can be combined bitwise with 'TERRNO' or 'TTERRNO' to print 423'errno', 'TEST_ERRNO' respectively. 424 425[source,c] 426------------------------------------------------------------------------------- 427const char *tst_strsig(int sig); 428------------------------------------------------------------------------------- 429 430Return the given signal number's corresponding string. 431 432[source,c] 433------------------------------------------------------------------------------- 434const char *tst_strerrno(int err); 435------------------------------------------------------------------------------- 436 437Return the given errno number's corresponding string. Using this function to 438translate 'errno' values to strings is preferred. You should not use the 439'strerror()' function in the testcases. 440 441 4422.2.3 Test temporary directory 443^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 444 445If '.needs_tmpdir' is set to '1' in the 'struct tst_test' unique test 446temporary is created and it's set as the test working directory. Tests *MUST 447NOT* create temporary files outside that directory. 448 449IMPORTANT: Close all file descriptors (that point to files in test temporary 450 directory, even the unlinked ones) either in the 'test()' function 451 or in the test 'cleanup()' otherwise the test may break temporary 452 directory removal on NFS (look for "NFS silly rename"). 453 454[[2.2.4]] 4552.2.4 Safe macros 456^^^^^^^^^^^^^^^^^ 457 458Safe macros aim to simplify error checking in test preparation. Instead of 459calling system API functions, checking for their return value and aborting the 460test if the operation has failed, you just use corresponding safe macro. 461 462Use them whenever it's possible. 463 464Instead of writing: 465 466[source,c] 467------------------------------------------------------------------------------- 468 fd = open("/dev/null", O_RDONLY); 469 if (fd < 0) 470 tst_brk(TBROK | TERRNO, "opening /dev/null failed"); 471------------------------------------------------------------------------------- 472 473You write just: 474 475[source,c] 476------------------------------------------------------------------------------- 477 fd = SAFE_OPEN("/dev/null", O_RDONLY); 478------------------------------------------------------------------------------- 479 480IMPORTANT: The SAFE_CLOSE() function also sets the passed file descriptor to -1 481 after it's successfully closed. 482 483They can also simplify reading and writing of sysfs files, you can, for 484example, do: 485 486[source,c] 487------------------------------------------------------------------------------- 488 SAFE_FILE_SCANF("/proc/sys/kernel/pid_max", "%lu", &pid_max); 489------------------------------------------------------------------------------- 490 491See 'include/tst_safe_macros.h', 'include/tst_safe_stdio.h' and 492'include/tst_safe_file_ops.h' and 'include/tst_safe_net.h' for a complete list. 493 4942.2.5 Test specific command line options 495^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 496 497[source,c] 498------------------------------------------------------------------------------- 499struct tst_option { 500 char *optstr; 501 char **arg; 502 char *help; 503}; 504------------------------------------------------------------------------------- 505 506Test specific command line parameters can be passed with the 'NULL'-terminated 507array of 'struct tst_option'. The 'optstr' is the command line option i.e. "o" 508or "o:" if option has a parameter. Only short options are supported. The 'arg' 509is where 'optarg' is stored upon match. If option has no parameter it's set to 510non-'NULL' value if option was present. The 'help' is a short help string. 511 512NOTE: The test parameters must not collide with common test parameters defined 513 in the library the currently used ones are +-i+, +-I+, +-C+, and +-h+. 514 5152.2.6 Runtime kernel version detection 516^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 517 518Testcases for newly added kernel functionality require kernel newer than a 519certain version to run. All you need to skip a test on older kernels is to 520set the '.min_kver' string in the 'struct tst_test' to a minimal required 521kernel version, e.g. '.min_kver = "2.6.30"'. 522 523For more complicated operations such as skipping a test for a certain range 524of kernel versions, following functions could be used: 525 526[source,c] 527------------------------------------------------------------------------------- 528int tst_kvercmp(int r1, int r2, int r3); 529 530struct tst_kern_exv { 531 char *dist_name; 532 char *extra_ver; 533}; 534 535int tst_kvercmp2(int r1, int r2, int r3, struct tst_kern_exv *vers); 536------------------------------------------------------------------------------- 537 538These two functions are intended for runtime kernel version detection. They 539parse the output from 'uname()' and compare it to the passed values. 540 541The return value is similar to the 'strcmp()' function, i.e. zero means equal, 542negative value means that the kernel is older than than the expected value and 543positive means that it's newer. 544 545The second function 'tst_kvercmp2()' allows for specifying per-vendor table of 546kernel versions as vendors typically backport fixes to their kernels and the 547test may be relevant even if the kernel version does not suggests so. See 548'testcases/kernel/syscalls/inotify/inotify04.c' for example usage. 549 5502.2.7 Fork()-ing 551^^^^^^^^^^^^^^^^ 552 553Be wary that if the test forks and there were messages printed by the 554'tst_*()' interfaces, the data may still be in libc/kernel buffers and these 555*ARE NOT* flushed automatically. 556 557This happens when 'stdout' gets redirected to a file. In this case, the 558'stdout' is not line buffered, but block buffered. Hence after a fork content 559of the buffers will be printed by the parent and each of the children. 560 561To avoid that you should use 'SAFE_FORK()'. 562 563IMPORTANT: You have to set the '.forks_child' flag in the test structure 564 if your testcase forks. 565 566[[2.2.8]] 5672.2.8 Doing the test in the child process 568^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 569 570Results reported by 'tst_res()' are propagated to the parent test process via 571block of shared memory. 572 573Calling 'tst_brk()' causes child process to exit with non-zero exit value. 574Which means that it's safe to use 'SAFE_*()' macros in the child processes as 575well. 576 577Children that outlive the 'test()' function execution are waited for in the 578test library. Unclean child exit (killed by signal, non-zero exit value, etc.) 579will cause the main test process to exit with 'tst_brk()', which especially 580means that 'TBROK' propagated from a child process will cause the whole test 581to exit with 'TBROK'. 582 583If a test needs a child that segfaults or does anything else that cause it to 584exit uncleanly all you need to do is to wait for such children from the 585'test()' function so that it's reaped before the main test exits the 'test()' 586function. 587 5882.2.9 Fork() and Parent-child synchronization 589^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 590 591As LTP tests are written for Linux, most of the tests involve fork()-ing and 592parent-child process synchronization. LTP includes a checkpoint library that 593provides wait/wake futex based functions. 594 595In order to use checkpoints the '.needs_checkpoints' flag in the 'struct 596tst_test' must be set to '1', this causes the test library to initialize 597checkpoints before the 'test()' function is called. 598 599[source,c] 600------------------------------------------------------------------------------- 601#include "tst_test.h" 602 603TST_CHECKPOINT_WAIT(id) 604 605TST_CHECKPOINT_WAKE(id) 606 607TST_CHECKPOINT_WAKE2(id, nr_wake) 608 609TST_CHECKPOINT_WAKE_AND_WAIT(id) 610------------------------------------------------------------------------------- 611 612The checkpoint interface provides pair of wake and wait functions. The 'id' is 613unsigned integer which specifies checkpoint to wake/wait for. As a matter of 614fact it's an index to an array stored in a shared memory, so it starts on 615'0' and there should be enough room for at least of hundred of them. 616 617The 'TST_CHECKPOINT_WAIT()' suspends process execution until it's woken 618up or until timeout is reached. 619 620The 'TST_CHECKPOINT_WAKE()' wakes one process waiting on the checkpoint. 621If no process is waiting the function retries until it success or until 622timeout is reached. 623 624If timeout has been reached process exits with appropriate error message (uses 625'tst_brk()'). 626 627The 'TST_CHECKPOINT_WAKE2()' does the same as 'TST_CHECKPOINT_WAKE()' but can 628be used to wake precisely 'nr_wake' processes. 629 630The 'TST_CHECKPOINT_WAKE_AND_WAIT()' is a shorthand for doing wake and then 631immediately waiting on the same checkpoint. 632 633Child processes created via 'SAFE_FORK()' are ready to use the checkpoint 634synchronization functions, as they inherited the mapped page automatically. 635 636Child processes started via 'exec()', or any other processes not forked from 637the test process must initialize the checkpoint by calling 'tst_reinit()'. 638 639For the details of the interface, look into the 'include/tst_checkpoint.h'. 640 641[source,c] 642------------------------------------------------------------------------------- 643#include "tst_test.h" 644 645/* 646 * Waits for process state change. 647 * 648 * The state is one of the following: 649 * 650 * R - process is running 651 * S - process is sleeping 652 * D - process sleeping uninterruptibly 653 * Z - zombie process 654 * T - process is traced 655 */ 656TST_PROCESS_STATE_WAIT(pid, state) 657------------------------------------------------------------------------------- 658 659The 'TST_PROCESS_STATE_WAIT()' waits until process 'pid' is in requested 660'state'. The call polls +/proc/pid/stat+ to get this information. 661 662It's mostly used with state 'S' which means that process is sleeping in kernel 663for example in 'pause()' or any other blocking syscall. 664 6652.2.10 Signal handlers 666^^^^^^^^^^^^^^^^^^^^^^ 667 668If you need to use signal handlers, keep the code short and simple. Don't 669forget that the signal handler is called asynchronously and can interrupt the 670code execution at any place. 671 672This means that problems arise when global state is changed both from the test 673code and signal handler, which will occasionally lead to: 674 675* Data corruption (data gets into inconsistent state), this may happen, for 676 example, for any operations on 'FILE' objects. 677 678* Deadlock, this happens, for example, if you call 'malloc(2)', 'free(2)', 679 etc. from both the test code and the signal handler at the same time since 680 'malloc' has global lock for it's internal data structures. (Be wary that 681 'malloc(2)' is used by the libc functions internally too.) 682 683* Any other unreproducible and unexpected behavior. 684 685Quite common mistake is to call 'exit(3)' from a signal handler. Note that this 686function is not signal-async-safe as it flushes buffers, etc. If you need to 687exit a test immediately from a signal handler use '_exit(2)' instead. 688 689TIP: See 'man 7 signal' for the list of signal-async-safe functions. 690 691If a signal handler sets a variable, its declaration must be 'volatile', 692otherwise compiler may misoptimize the code. This is because the variable may 693not be changed in the compiler code flow analysis. There is 'sig_atomic_t' 694type defined in C99 but this one *DOES NOT* imply 'volatile' (it's just a 695'typedef' to 'int'). So the correct type for a flag that is changed from a 696signal handler is either 'volatile int' or 'volatile sig_atomic_t'. 697 6982.2.11 Kernel Modules 699^^^^^^^^^^^^^^^^^^^^^ 700 701There are certain cases where the test needs a kernel part and userspace part, 702happily, LTP can build a kernel module and then insert it to the kernel on test 703start for you. See 'testcases/kernel/device-drivers/block' for details. 704 7052.2.11 Useful macros 706^^^^^^^^^^^^^^^^^^^^^ 707 708[source,c] 709------------------------------------------------------------------------------- 710ARRAY_SIZE(arr) 711------------------------------------------------------------------------------- 712 713Returns the size of statically defined array, i.e. 714'(sizeof(arr) / sizeof(*arr))' 715 716[source,c] 717------------------------------------------------------------------------------- 718LTP_ALIGN(x, a) 719------------------------------------------------------------------------------- 720 721Aligns the x to be next multiple of a. The a must be power of 2. 722 7232.2.12 Filesystem type detection 724^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 725 726Some tests are known to fail on certain filesytems (you cannot swap on TMPFS, 727there are unimplemented 'fcntl()' etc.). 728 729If your test needs to be skipped on certain filesystems, use the interface 730below: 731 732[source,c] 733------------------------------------------------------------------------------- 734#include "tst_test.h" 735 736 /* 737 * Unsupported only on NFS. 738 */ 739 if (tst_fs_type(".") == TST_NFS_MAGIC) 740 tst_brk(TCONF, "Test not supported on NFS filesystem"); 741 742 743 /* 744 * Unsupported on NFS, TMPFS and RAMFS 745 */ 746 long type; 747 748 switch ((type = tst_fs_type("."))) { 749 case TST_NFS_MAGIC: 750 case TST_TMPFS_MAGIC: 751 case TST_RAMFS_MAGIC: 752 tst_brk(TCONF, "Test not supported on %s filesystem", 753 tst_fs_type_name(type)); 754 break; 755 } 756------------------------------------------------------------------------------- 757 7582.2.13 Thread-safety in the LTP library 759^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 760 761It is safe to use library 'tst_res()' function in multi-threaded tests. 762 763Only the main thread must return from the 'test()' function to the test 764library and that must be done only after all threads that may call any library 765function has been terminated. That especially means that threads that may call 766'tst_brk()' must terminate before the execution of the 'test()' function 767returns to the library. This is usually done by the main thread joining all 768worker threads at the end of the 'test()' function. Note that the main thread 769will never get to the library code in a case that 'tst_brk()' was called from 770one of the threads since it will sleep at least in 'pthread_join()' on the 771thread that called the 'tst_brk()' till 'exit()' is called by 'tst_brk()'. 772 773The test-supplied cleanup function runs *concurrently* to the rest of the 774threads in a case that cleanup was entered from 'tst_brk()'. Subsequent 775threads entering 'tst_brk()' must be suspended or terminated at the start of 776the the user supplied cleanup function. It may be necessary to stop or exit 777the rest of the threads before the test cleans up as well. For example threads 778that create new files should be stopped before temporary directory is be 779removed. 780 781Following code example shows thread safe cleanup function example using atomic 782increment as a guard. The library calls its cleanup after the execution returns 783from the user supplied cleanup and expects that only one thread returns from 784the user supplied cleanup to the test library. 785 786[source,c] 787------------------------------------------------------------------------------- 788#include "tst_test.h" 789 790static void cleanup(void) 791{ 792 static int flag; 793 794 if (tst_atomic_inc(&flag) != 1) 795 pthread_exit(NULL); 796 797 /* if needed stop the rest of the threads here */ 798 799 ... 800 801 /* then do cleanup work */ 802 803 ... 804 805 /* only one thread returns to the library */ 806} 807------------------------------------------------------------------------------- 808 809 8102.2.14 Testing with a block device 811^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 812 813Some tests needs a block device (inotify tests, syscall 'EROFS' failures, 814etc.). LTP library contains a code to prepare a testing device. 815 816If '.needs_device' flag in the 'struct tst_test' is set the the 'tst_device' 817structure is initialized with a path to a test device and default filesystem 818to be used. 819 820[source,c] 821------------------------------------------------------------------------------- 822#include "tst_test.h" 823 824struct tst_device { 825 const char *dev; 826 const char *fs_type; 827}; 828 829extern struct tst_device *tst_device; 830 831int tst_umount(const char *path); 832------------------------------------------------------------------------------- 833 834In case that 'LTP_DEV' is passed to the test in an environment, the library 835checks that the file exists and that it's a block device. Otherwise a 836temporary file is created and attached to a free loop device. 837 838If there is no usable device and loop device couldn't be initialized the test 839exits with 'TCONF'. 840 841The 'tst_umount()' function works exactly as 'umount(2)' but retries several 842times on 'EBUSY'. This is because various desktop daemons (gvfsd-trash is known 843for that) may be stupid enough to probe all newly mounted filesystem which 844results in 'umount(2)' failing with 'EBUSY'. 845 846IMPORTANT: All testcases should use 'tst_umount()' instead of 'umount(2)' to 847 umount filesystems. 848 8492.2.15 Formatting a device with a filesystem 850^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 851 852[source,c] 853------------------------------------------------------------------------------- 854#include "tst_test.h" 855 856static void setup(void) 857{ 858 ... 859 SAFE_MKFS(tst_device->dev, tst_device->fs_type, NULL, NULL); 860 ... 861} 862------------------------------------------------------------------------------- 863 864This function takes a path to a device, filesystem type and an array of extra 865options passed to mkfs. 866 867The fs options 'fs_opts' should either be 'NULL' if there are none, or a 868'NULL' terminated array of strings such as: 869+const char *const opts[] = {"-b", "1024", NULL}+. 870 871The extra option 'extra_opt' should either be 'NULL' if there is none, or a 872string such as '"102400"'; 'extra_opt' will be passed after device name. e.g: 873+mkfs -t ext4 -b 1024 /dev/sda1 102400+ in this case. 874 8752.2.16 Verifying a filesystem's free space 876^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 877 878Some tests have size requirements for the filesystem's free space. If these 879requirements are not satisfied, the tests should be skipped. 880 881[source,c] 882------------------------------------------------------------------------------- 883#include "tst_test.h" 884 885int tst_fs_has_free(const char *path, unsigned int size, unsigned int mult); 886------------------------------------------------------------------------------- 887 888The 'tst_fs_has_free()' function returns 1 if there is enough space and 0 if 889there is not. 890 891The 'path' is the pathname of any directory/file within a filesystem. 892 893The 'mult' is a multiplier, one of 'TST_BYTES', 'TST_KB', 'TST_MB' or 'TST_GB'. 894 895The required free space is calculated by 'size * mult', e.g. 896'tst_fs_has_free("/tmp/testfile", 64, TST_MB)' will return 1 if the 897filesystem, which '"/tmp/testfile"' is in, has 64MB free space at least, and 0 898if not. 899 9002.2.17 Files, directories and fs limits 901^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 902 903Some tests need to know the maximum count of links to a regular file or 904directory, such as 'rename(2)' or 'linkat(2)' to test 'EMLINK' error. 905 906[source,c] 907------------------------------------------------------------------------------- 908#include "tst_test.h" 909 910int tst_fs_fill_hardlinks(const char *dir); 911------------------------------------------------------------------------------- 912 913Try to get maximum count of hard links to a regular file inside the 'dir'. 914 915NOTE: This number depends on the filesystem 'dir' is on. 916 917This function uses 'link(2)' to create hard links to a single file until it 918gets 'EMLINK' or creates 65535 links. If the limit is hit, the maximum number of 919hardlinks is returned and the 'dir' is filled with hardlinks in format 920"testfile%i", where i belongs to [0, limit) interval. If no limit is hit or if 921'link(2)' failed with 'ENOSPC' or 'EDQUOT', zero is returned and previously 922created files are removed. 923 924[source,c] 925------------------------------------------------------------------------------- 926#include "tst_test.h" 927 928int tst_fs_fill_subdirs(const char *dir); 929------------------------------------------------------------------------------- 930 931Try to get maximum number of subdirectories in directory. 932 933NOTE: This number depends on the filesystem 'dir' is on. For current kernel, 934subdir limit is not available for all filesystems (available for ext2, ext3, 935minix, sysv and more). If the test runs on some other filesystems, like ramfs, 936tmpfs, it will not even try to reach the limit and return 0. 937 938This function uses 'mkdir(2)' to create directories in 'dir' until it gets 939'EMLINK' or creates 65535 directories. If the limit is hit, the maximum number 940of subdirectories is returned and the 'dir' is filled with subdirectories in 941format "testdir%i", where i belongs to [0, limit - 2) interval (because each 942newly created dir has two links already - the '.' and the link from parent 943dir). If no limit is hit or if 'mkdir(2)' failed with 'ENOSPC' or 'EDQUOT', 944zero is returned and previously created directories are removed. 945 946[source,c] 947------------------------------------------------------------------------------- 948#include "tst_test.h" 949 950int tst_dir_is_empty(const char *dir, int verbose); 951------------------------------------------------------------------------------- 952 953Returns non-zero if directory is empty and zero otherwise. 954 955Directory is considered empty if it contains only '.' and '..'. 956 9572.2.18 Getting an unused PID number 958^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 959 960Some tests require a 'PID', which is not used by the OS (does not belong to 961any process within it). For example, kill(2) should set errno to 'ESRCH' if 962it's passed such 'PID'. 963 964[source,c] 965------------------------------------------------------------------------------- 966#include "tst_test.h" 967 968pid_t tst_get_unused_pid(void); 969------------------------------------------------------------------------------- 970 971Return a 'PID' value not used by the OS or any process within it. 972 973[source,c] 974------------------------------------------------------------------------------- 975#include "tst_test.h" 976 977int tst_get_free_pids(void); 978------------------------------------------------------------------------------- 979 980Returns number of unused pids in the system. Note that this number may be 981different once the call returns and should be used only for rough estimates. 982 9832.2.20 Running executables 984^^^^^^^^^^^^^^^^^^^^^^^^^^ 985 986[source,c] 987------------------------------------------------------------------------------- 988#include "tst_test.h" 989 990int tst_run_cmd(const char *const argv[], 991 const char *stdout_path, 992 const char *stderr_path, 993 int pass_exit_val); 994------------------------------------------------------------------------------- 995 996'tst_run_cmd' is a wrapper for 'vfork() + execvp()' which provides a way 997to execute an external program. 998 999'argv[]' is a NULL-terminated array of strings starting with the program name 1000which is followed by optional arguments. 1001 1002A non-zero 'pass_exit_val' makes 'tst_run_cmd' return the program exit code to 1003the caller. A zero for 'pass_exit_val' makes 'tst_run_cmd' exit the tests 1004on failure. 1005 1006In case that 'execvp()' has failed and the 'pass_exit_val' flag was set, the 1007return value is '255' if 'execvp()' failed with 'ENOENT' and '254' otherwise. 1008 1009'stdout_path' and 'stderr_path' determine where to redirect the program 1010stdout and stderr I/O streams. 1011 1012.Example 1013[source,c] 1014------------------------------------------------------------------------------- 1015#include "tst_test.h" 1016 1017const char *const cmd[] = { "ls", "-l", NULL }; 1018 1019... 1020 /* Store output of 'ls -l' into log.txt */ 1021 tst_run_cmd(cmd, "log.txt", NULL, 0); 1022... 1023------------------------------------------------------------------------------- 1024 10252.2.21 Measuring elapsed time and helper functions 1026^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1027 1028[source,c] 1029------------------------------------------------------------------------------- 1030#include "tst_test.h" 1031 1032void tst_timer_check(clockid_t clk_id); 1033 1034void tst_timer_start(clockid_t clk_id); 1035 1036void tst_timer_stop(void); 1037 1038struct timespec tst_timer_elapsed(void); 1039 1040long long tst_timer_elapsed_ms(void); 1041 1042long long tst_timer_elapsed_us(void); 1043------------------------------------------------------------------------------- 1044 1045The 'tst_timer_check()' function checks if specified 'clk_id' is suppored and 1046exits the test with 'TCONF' otherwise. It's expected to be used in test 1047'setup()' before any resources that needs to be cleaned up are initialized, 1048hence it does not include a cleanup function parameter. 1049 1050The 'tst_timer_start()' marks start time and stores the 'clk_id' for further 1051use. 1052 1053The 'tst_timer_stop()' marks the stop time using the same 'clk_id' as last 1054call to 'tst_timer_start()'. 1055 1056The 'tst_timer_elapsed*()' returns time difference between the timer start and 1057last timer stop in several formats and units. 1058 1059IMPORTANT: The timer functions use 'clock_gettime()' internally which needs to 1060 be linked with '-lrt' on older glibc. Please do not forget to add 1061 'LDLIBS+=-lrt' in Makefile. 1062 1063[source,c] 1064------------------------------------------------------------------------------- 1065long long tst_timespec_to_us(struct timespec t); 1066long long tst_timespec_to_ms(struct timespec t); 1067 1068struct timeval tst_us_to_timeval(long long us); 1069struct timeval tst_ms_to_timeval(long long ms); 1070 1071int tst_timespec_lt(struct timespec t1, struct timespec t2); 1072 1073struct timespec tst_timespec_add_us(struct timespec t, long long us); 1074 1075struct timespec tst_timespec_diff(struct timespec t1, struct timespec t2); 1076long long tst_timespec_diff_us(struct timespec t1, struct timespec t2); 1077long long tst_timespec_diff_ms(struct timespec t1, struct timespec t2); 1078 1079struct timespec tst_timespec_abs_diff(struct timespec t1, struct timespec t2); 1080long long tst_timespec_abs_diff_us(struct timespec t1, struct timespec t2); 1081long long tst_timespec_abs_diff_ms(struct timespec t1, struct timespec t2); 1082------------------------------------------------------------------------------- 1083 1084The first four functions are simple inline conversion functions. 1085 1086The 'tst_timespec_lt()' function returns non-zero if 't1' is earlier than 1087't2'. 1088 1089The 'tst_timespec_add_us()' function adds 'us' microseconds to the timespec 1090't'. The 'us' is expected to be positive. 1091 1092The 'tst_timespec_diff*()' functions returns difference between two times, the 1093't1' is expected to be later than 't2'. 1094 1095The 'tst_timespec_abs_diff*()' functions returns absolute value of difference 1096between two times. 1097 1098NOTE: All conversions to ms and us rounds the value. 1099 11002.2.22 Datafiles 1101^^^^^^^^^^^^^^^^ 1102 1103[source,c] 1104------------------------------------------------------------------------------- 1105#include "tst_test.h" 1106 1107static const char *const res_files[] = { 1108 "foo", 1109 "bar", 1110 NULL 1111}; 1112 1113static struct tst_test test = { 1114 ... 1115 .resource_files = res_files, 1116 ... 1117} 1118------------------------------------------------------------------------------- 1119 1120If the test needs additional files to be copied to the test temporary 1121directory all you need to do is to list their filenames in the 1122'NULL'-terminated array '.resource_files' in the tst_test structure. 1123 1124When resource files is set test temporary directory is created automatically, 1125there is need to set '.needs_tmpdir' as well. 1126 1127The test library looks for datafiles first, these are either stored in a 1128directory called +datafiles+ in the +$PWD+ at the start of the test or in 1129+$LTPROOT/testcases/data/$tid+. If the file is not found the library looks 1130into +$LTPROOT/testcases/bin/+ and to +$PWD+ at the start of the test. This 1131ensures that the testcases can copy the file(s) effortlessly both when test is 1132started from the directory it was compiled in as well as when LTP was 1133installed. 1134 1135The file(s) are copied to the newly created test temporary directory which is 1136set as the test working directory when the 'test()' functions is executed. 1137 11382.3 Writing a testcase in shell 1139~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1140 1141LTP supports testcases to be written in a portable shell too. 1142 1143There is a shell library modeled closely to the C interface (the source is 1144located at 'testcases/lib/test.sh') and is installed to the same directory as 1145the rest of the LTP test binaries. 1146 1147WARNING: All identifiers starting with TST_ or tst_ are reserved for the 1148 'test.sh' library. 1149 11502.3.1 Basic shell test structure 1151^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1152 1153[source,sh] 1154------------------------------------------------------------------------------- 1155#!/bin/sh 1156# 1157# This is a basic test for true shell buildin 1158# 1159 1160TCID=true01 1161TST_TOTAL=1 1162. test.sh 1163 1164true 1165ret=$? 1166 1167if [ $ret -eq 0 ]; then 1168 tst_resm TPASS "true returned 0" 1169else 1170 tst_resm TFAIL "true returned $ret" 1171fi 1172 1173tst_exit 1174------------------------------------------------------------------------------- 1175 1176TIP: To execute this test the 'test.sh' library must be in '$PATH'. If you are 1177 executing the test from a git checkout you can run it as 1178 'PATH="$PATH:../../lib" ./foo01.sh' 1179 1180WARNING: Do not forget to add the 'tst_exit' at the end of the test, 1181 otherwise the test return value would be the return value of last 1182 executed command. 1183 11842.3.2 Basic test interface 1185^^^^^^^^^^^^^^^^^^^^^^^^^^ 1186 1187Following functions similar to the LTP C interface are available. 1188 1189* tst_resm() 1190* tst_brkm() 1191* tst_exit() 1192* tst_require_root() 1193* tst_tmpdir() 1194* tst_rmdir() 1195* tst_fs_has_free() 1196* tst_mkfs() 1197* tst_acquire_device() 1198* tst_release_device() 1199 1200There is one more function called 'tst_check_cmds()' that gets unspecified 1201number of parameters and asserts that each parameter is a name of an 1202executable in '$PATH' and exits the test with 'TCONF' on first missing. 1203 1204tst_sleep 1205+++++++++ 1206 1207Albeit there is a sleep command available basically everywhere not all 1208implementations can support sleeping for less than one second. And most of the 1209time sleeping for a second is too much. Therefore LTP includes 'tst_sleep' 1210that can sleep for defined amount of seconds, milliseconds or microseconds. 1211 1212[source,sh] 1213------------------------------------------------------------------------------- 1214# sleep for 100 milliseconds 1215tst_sleep 100ms 1216------------------------------------------------------------------------------- 1217 1218tst_random 1219+++++++++ 1220 1221There is no $RANDOM in portable shell, use tst_random instead. 1222 1223[source,sh] 1224------------------------------------------------------------------------------- 1225# get random integer between 0 and 1000 (including 0 and 1000) 1226tst_random 0 1000 1227------------------------------------------------------------------------------- 1228 1229ROD and ROD_SILENT 1230++++++++++++++++++ 1231 1232These functions supply the 'SAFE_MACROS' used in C although they work and are 1233named differently. 1234 1235[source,sh] 1236------------------------------------------------------------------------------- 1237ROD_SILENT command arg1 arg2 ... 1238 1239# is shorthand for: 1240 1241command arg1 arg2 ... > /dev/null 2>&1 1242if [ $? -ne 0 ]; then 1243 tst_brkm TBROK "..." 1244fi 1245 1246 1247 1248ROD command arg1 arg2 ... 1249 1250# is shorthand for: 1251 1252ROD arg1 arg2 ... 1253if [ $? -ne 0 ]; then 1254 tst_brkm TBROK "..." 1255fi 1256------------------------------------------------------------------------------- 1257 1258WARNING: Keep in mind that output redirection (to a file) happens in the 1259 caller rather than in the ROD function and cannot be checked for 1260 write errors by the ROD function. 1261 1262As a matter of a fact doing +ROD echo a > /proc/cpuinfo+ would work just fine 1263since the 'ROD' function will only get the +echo a+ part that will run just 1264fine. 1265 1266[source,sh] 1267------------------------------------------------------------------------------- 1268# Redirect output to a file with ROD 1269ROD echo foo \> bar 1270------------------------------------------------------------------------------- 1271 1272Note the '>' is escaped with '\', this causes that the '>' and filename are 1273passed to the 'ROD' function as parameters and the 'ROD' function contains 1274code to split '$@' on '>' and redirects the output to the file. 1275 1276.tst_fs_has_free 1277[source,sh] 1278------------------------------------------------------------------------------- 1279#!/bin/sh 1280 1281... 1282 1283# whether current directory has 100MB free space at least. 1284if ! tst_fs_has_free . 100MB; then 1285 tst_brkm TCONF "Not enough free space" 1286fi 1287 1288... 1289------------------------------------------------------------------------------- 1290 1291The 'tst_fs_has_free' shell interface returns 0 if the specified free space is 1292satisfied, 1 if not, and 2 on error. 1293 1294The second argument supports suffixes kB, MB and GB, the default unit is Byte. 1295 1296.tst_retry 1297[source,sh] 1298------------------------------------------------------------------------------- 1299#!/bin/sh 1300 1301... 1302 1303# Retry ping command three times 1304tst_retry "ping -c 1 127.0.0.1" 1305 1306if [ $? -ne 0 ]; then 1307 tst_resm TFAIL "Failed to ping 127.0.0.1" 1308else 1309 tst_resm TPASS "Successfully pinged 127.0.0.1" 1310fi 1311 1312... 1313------------------------------------------------------------------------------- 1314 1315The 'tst_retry' function allows you to retry a command after waiting small 1316amount of time until it succeeds or until given amount of retries has been 1317reached (default is three attempts). 1318 13192.3.3 Cleanup 1320^^^^^^^^^^^^^ 1321 1322Due to differences between C and shell, the cleanup callback is done using a 1323'TST_CLEANUP' shell variable that, if not empty, is evaluated before the test 1324exits (either after calling 'tst_exit()' or 'tst_brkm()'). See example below. 1325 1326[source,sh] 1327------------------------------------------------------------------------------- 1328#!/bin/sh 1329# 1330# Test cleanup example 1331# 1332 1333TCID=true01 1334TST_TOTAL=1 1335. test.sh 1336 1337cleanup() 1338{ 1339 tst_rmdir 1340} 1341 1342tst_tmpdir 1343TST_CLEANUP=cleanup 1344 1345# Do the test here 1346 1347tst_exit 1348------------------------------------------------------------------------------- 1349 13502.3.4 Restarting daemons 1351^^^^^^^^^^^^^^^^^^^^^^^^ 1352 1353Restarting system daemons is a complicated task for two reasons. 1354 1355* There are different init systems 1356 (SysV init, systemd, etc...) 1357 1358* Daemon names are not unified between distributions 1359 (apache vs httpd, cron vs crond, various syslog variations) 1360 1361To solve these problems LTP has 'testcases/lib/daemonlib.sh' library that 1362provides functions to start/stop/query daemons as well as variables that store 1363correct daemon name. 1364 1365.Supported operations 1366|============================================================================== 1367| start_daemon() | Starts daemon, name is passed as first parameter. 1368| stop_daemon() | Stops daemon, name is passed as first parameter. 1369| restart_daemon() | Restarts daemon, name is passed as first parameter. 1370| status_daemon() | Returns daemon status, TODO: what is return value? 1371|============================================================================== 1372 1373.Variables with detected names 1374|============================================================================== 1375| CROND_DAEMON | Cron daemon name (cron, crond). 1376| SYSLOG_DAEMON | Syslog daemon name (syslog, syslog-ng, rsyslog). 1377|============================================================================== 1378 1379.Cron daemon restart example 1380[source,sh] 1381------------------------------------------------------------------------------- 1382#!/bin/sh 1383# 1384# Cron daemon restart example 1385# 1386TCID=cron01 1387TST_COUNT=1 1388. test.sh 1389. daemonlib.sh 1390 1391... 1392 1393restart_daemon $CROND_DAEMON 1394 1395... 1396 1397tst_exit 1398------------------------------------------------------------------------------- 1399 14002.3.5 $PATH and su 1401~~~~~~~~~~~~~~~~~~ 1402 1403While some distributions retain paths added to +$PATH+ when doing 1404+su user -c "command"+ this does not work at least in Debian. If you want to 1405run LTP binaries as a different user you must use 'tst_su' instead which sets 1406up +$PATH+ and the runs the command. 1407 1408.Run test child binary as a test user 1409[source,sh] 1410------------------------------------------------------------------------------- 1411#!/bin/sh 1412TCID=foo01 1413. test.sh 1414 1415tst_su testusr foo01_child 1416if [ $? -ne 0 ]; then 1417 tst_resm TFAIL "foo failed" 1418else 1419 tst_resm TPASS "foo passed" 1420fi 1421------------------------------------------------------------------------------- 1422 14232.3.6 Access to the checkpoint interface 1424^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1425 1426The shell library provides an implementation of the checkpoint interface 1427compatible with the C version. All TST_CHECKPOINT_* functions are available. 1428 1429In order to initialize checkpoints '$TST_NEEDS_CHECKPOINTS' must be set to '1' 1430before the inclusion of 'test.sh': 1431 1432[source,sh] 1433------------------------------------------------------------------------------- 1434#!/bin/sh 1435 1436TST_NEEDS_CHECKPOINTS=1 1437. test.sh 1438------------------------------------------------------------------------------- 1439 1440Since both the implementations are compatible, it's also possible to start 1441a child binary process from a shell test and synchronize with it. This process 1442must have checkpoints initialized by calling tst_reinit()'. 1443 14443. Common problems 1445------------------ 1446 1447This chapter describes common problems/misuses and less obvious design patters 1448(quirks) in UNIX interfaces. Read it carefully :) 1449 14503.1 umask() 1451~~~~~~~~~~~ 1452 1453I've been hit by this one several times already... When you create files 1454with 'open()' or 'creat()' etc, the mode specified as the last parameter *is 1455not* the mode the file is created with. The mode depends on current 'umask()' 1456settings which may clear some of the bits. If your test depends on specific 1457file permissions you need either to change umask to 0 or 'chmod()' the file 1458afterwards or use SAFE_TOUCH() that does the 'chmod()' for you. 1459 14603.2 access() 1461~~~~~~~~~~~ 1462 1463If 'access(some_file, W_OK)' is executed by root, it will return success even 1464if the file doesn't have write permission bits set (the same holds for R_OK 1465too). For sysfs files you can use 'open()' as a workaround to check file 1466read/write permissions. It might not work for other filesystems, for these you 1467have to use 'stat()', 'lstat()' or 'fstat()'. 1468 14693.3 umount() EBUSY 1470~~~~~~~~~~~~~~~~~~ 1471 1472Various desktop daemons (gvfsd-trash is known for that) may be stupid enough 1473to probe all newly mounted filesystem which results in 'umount(2)' failing 1474with 'EBUSY'; use 'tst_umount()' described in 2.2.19 that retries in this case 1475instead of plain 'umount(2)'. 1476 14773.4 FILE buffers and fork() 1478~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1479 1480Be vary that if a process calls 'fork(2)' the child process inherits open 1481descriptors as well as copy of the parent memory so especially if there are 1482any open 'FILE' buffers with a data in them they may be written both by the 1483parent and children resulting in corrupted/duplicated data in the resulting 1484files. 1485 1486Also open 'FILE' streams are flushed and closed at 'exit(3)' so if your 1487program works with 'FILE' streams, does 'fork(2)', and the child may end up 1488calling 'exit(3)' you will likely end up with corrupted files. 1489 1490The solution to this problem is either simply call 'fflush(NULL)' that flushes 1491all open output 'FILE' streams just before doing 'fork(2)'. You may also use 1492'_exit(2)' in child processes which does not flush 'FILE' buffers and also 1493skips 'atexit(3)' callbacks. 1494 14954. Test Contribution Checklist 1496------------------------------ 1497 14981. Test compiles and runs fine (check with -i 10 too) 14992. Checkpatch does not report any errors 15003. The runtest entires are in place 15014. Test files are added into corresponding .gitignore files 15025. Patches apply over the latest git 1503 1504 15054.1 About .gitignore files 1506~~~~~~~~~~~~~~~~~~~~~~~~~~ 1507 1508There are numerous '.gitignore' files in the LTP tree. Usually there is a 1509'.gitignore' file per a group of tests. The reason for this setup is simple. 1510It's easier to maintain a '.gitignore' file per directory with tests, rather 1511than having single file in the project root directory. This way, we don't have 1512to update all the gitignore files when moving directories, and they get deleted 1513automatically when a directory with tests is removed. 1514