| LTP Test Writing Guidelines |
| =========================== |
| |
| This document describes LTP guidelines and LTP test interface and is intended |
| for anybody who want to write or modify a LTP testcase. It's not a definitive |
| guide and it's not, by any means, a substitute for common sense. |
| |
| 1. General Rules |
| ---------------- |
| |
| 1.1 Simplicity |
| ~~~~~~~~~~~~~~ |
| |
| For all it's worth keep the testcases simple or better as simple as possible. |
| The kernel and libc are tricky beasts and the complexity imposed by their |
| interfaces is quite high. Concentrate on the interface you want to test and |
| follow the UNIX philosophy. It's a good idea to make the test as |
| self-contained as possible too (it should not depend on tools or libraries |
| that are not widely available). |
| |
| Do not reinvent the wheel! |
| |
| * Use LTP standard interface |
| * Do not add custom PASS/FAIL reporting functions |
| * Do not write Makefiles from scratch, |
| use LTP build system instead, etc. |
| * ... |
| |
| 1.2 Code duplication |
| ~~~~~~~~~~~~~~~~~~~~ |
| |
| Copy & paste is a good servant but very poor master. If you are about to copy a |
| large part of the code from one testcase to another, think what would happen if |
| you find bug in the code that has been copied all around the tree. What about |
| moving it to a library instead? |
| |
| The same goes for short but complicated parts, whenever you are about to copy & |
| paste a syscall wrapper that packs arguments accordingly to machine |
| architecture or similarly complicated code, put it into a header instead. |
| |
| 1.3 Coding style |
| ~~~~~~~~~~~~~~~~ |
| |
| 1.3.1 C coding style |
| ^^^^^^^^^^^^^^^^^^^^ |
| |
| LTP adopted Linux kernel coding style. If you aren't familiar with its rules |
| locate 'linux/Documentation/CodingStyle' in the kernel sources and read it, |
| it's a well written introduction. |
| |
| There is also a checkpatch (see 'linux/scripts/checkpatch.pl') script that can |
| be used to check your patches before the submission. |
| |
| NOTE: If checkpatch does not report any problems, the code still may be wrong |
| as the tool only looks for common mistakes. |
| |
| 1.3.2 Shell coding style |
| ^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| When writing testcases in shell write in *portable shell* only, it's a good |
| idea to try to run the test using alternative shell (alternative to bash, for |
| example dash) too. |
| |
| *Portable shell* means Shell Command Language as defined by POSIX with a |
| exception of few widely used extensions, namely 'local' keyword used inside of |
| functions and '-o' and '-a' test parameters (that are marked as obsolete in |
| POSIX). |
| |
| You can either try to run the testcases on Debian which has '/bin/sh' pointing |
| to 'dash' by default or install 'dash' on your favorite distribution and use |
| it to run the tests. If your distribution lacks 'dash' package you can always |
| compile it from http://gondor.apana.org.au/~herbert/dash/files/[source]. |
| |
| Debian also has nice devscript |
| https://salsa.debian.org/debian/devscripts/raw/master/scripts/checkbashisms.pl[checkbashism.pl] |
| that can be used to check for non-portable shell code. |
| |
| Here are some common sense style rules for shell |
| |
| * Keep lines under 80 chars |
| |
| * Use tabs for indentation |
| |
| * Keep things simple, avoid unnecessary subshells |
| |
| * Don't do confusing things (i.e. don't name your functions like common shell |
| commands, etc.) |
| |
| * Quote variables |
| |
| * Be consistent |
| |
| 1.4 Commenting code |
| ~~~~~~~~~~~~~~~~~~~ |
| |
| Comments can sometimes save you day but they can easily do more harm than |
| good. There has been several cases where comments and actual implementation |
| were drifting slowly apart which yielded into API misuses and hard to find |
| bugs. Remember there is only one thing worse than no documentation, wrong |
| documentation. |
| |
| Generally everybody should write code that is obvious (which unfortunately |
| isn't always possible). If there is a code that needs to be commented keep it |
| short and to the point. Never ever comment the obvious. |
| |
| In case of LTP testcases it's customary to add a paragraph with highlevel test |
| description somewhere at the beginning of the file (usually right under the GPL |
| header). This helps other people to understand the overall goal of the test |
| before they dive into the technical details. |
| |
| 1.5 Backwards compatibility |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| LTP test should be as backward compatible as possible. Think of an enterprise |
| distributions with long term support (more than five years since the initial |
| release) or of an embedded platform that needs to use several years old |
| toolchain supplied by the manufacturer. |
| |
| Therefore LTP test for more current features should be able to cope with older |
| systems. It should at least compile fine and if it's not appropriate for the |
| configuration it should return 'TCONF' (see test interface description below). |
| |
| There are several types of checks we use: |
| |
| The *configure script* is usually used to detect availability of a function |
| declarations in system headers. It's used to disable tests at compile time. |
| |
| We also have runtime kernel version detection that can be used to disable |
| tests at runtime. |
| |
| Checking the *errno* value is another type of runtime check. Most of the |
| syscalls returns either 'EINVAL' or 'ENOSYS' when syscall was not implemented |
| or was disabled upon kernel compilation. |
| |
| Sometimes it also makes sense to define a few macros instead of creating |
| configure test. One example are Linux specific POSIX clock ids in |
| 'include/lapi/posix_clocks.h'. |
| |
| 1.6 Dealing with messed up legacy code |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| LTP contains a lot of old and messy code and we are cleaning it up as fast as |
| we can but despite the efforts there is still a lot. If you start modifying |
| old or a messed up testcase and your changes are more complicated than simple |
| typo fixes you should do a cleanup first (in a separate patch). It's easier to |
| review the changes if you separate the formatting fixes from the changes that |
| affects the test behavior. |
| |
| The same goes for moving files. If you need a rename or move file do it in a |
| separate patch. |
| |
| 1.7 License |
| ~~~~~~~~~~~ |
| |
| Code contributed to LTP should be licensed under GPLv2+ (GNU GPL version 2 or |
| any later version). Use `SPDX-License-Identifier: GPL-2.0-or-later`. |
| |
| 2. Writing a testcase |
| --------------------- |
| |
| 2.1 LTP Structure |
| ~~~~~~~~~~~~~~~~~ |
| |
| The structure of LTP is quite simple. Each test is a binary written either in |
| portable shell or C. The test gets a configuration via environment variables |
| and/or command line parameters, it prints additional information into the |
| stdout and reports overall success/failure via the exit value. |
| |
| Tests are generally placed under the 'testcases/' directory. Everything that |
| is a syscall or (slightly confusingly) libc syscall wrapper goes under |
| 'testcases/kernel/syscalls/'. Then there is 'testcases/open_posix_testsuite' |
| which is a well maintained fork of the upstream project that has been dead |
| since 2005 and also a number of directories with tests for more specific |
| features. |
| |
| 2.1.1 Runtest Files |
| ^^^^^^^^^^^^^^^^^^^ |
| |
| The list of tests to be executed is stored in runtest files under the |
| 'runtest/' directory. The default set of runtest files to be executed is |
| stored in 'scenario_groups/default'. When you add a test you should add |
| corresponding entries into some runtest file(s) as well. |
| |
| For syscall tests (these placed under 'testcases/kernel/syscalls/') use |
| 'runtest/syscalls' file, for kernel related tests for memory management we |
| have 'runtest/mm', etc. |
| |
| IMPORTANT: The runtest files should have one entry per a test. Creating a |
| wrapper that runs all your tests and adding it as a single test |
| into runtest file is strongly discouraged. |
| |
| 2.1.2 Datafiles |
| ^^^^^^^^^^^^^^^ |
| |
| If your test needs datafiles to work, these should be put into a subdirectory |
| named 'datafiles' and installed into the 'testcases/data/$TCID' directory (to |
| do that you have to add 'INSTALL_DIR := testcases/data/TCID' into the |
| 'datafiles/Makefile'). |
| |
| You can obtain path to datafiles via $TST_DATAROOT provided by test.sh |
| '$TST_DATAROOT/...' |
| or via C function 'tst_dataroot()' provided by libltp: |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| const char *dataroot = tst_dataroot(); |
| ------------------------------------------------------------------------------- |
| |
| Datafiles can also be accessed as '$LTPROOT/testcases/data/$TCID/...', |
| but '$TST_DATAROOT' and 'tst_dataroot()' are preferred as these can be used |
| when running testcases directly in git tree as well as from install |
| location. |
| |
| The path is constructed according to these rules: |
| |
| 1. if '$LTPROOT' is set, return '$LTPROOT/testcases/data/$TCID' |
| 2. else if 'tst_tmpdir()' was called return '$STARTWD/datafiles' |
| (where '$STARTWD' is initial working directory as recorded by 'tst_tmpdir()') |
| 3. else return '$CWD/datafiles' |
| |
| See 'testcases/commands/file/' for example. |
| |
| 2.1.3 Subexecutables |
| ^^^^^^^^^^^^^^^^^^^^ |
| |
| If you test needs to execute a binary, place it in the same directory as the |
| testcase and name the file starting with '${test_binary_name}_'. Once the |
| test is executed by the framework, the path to the directory with all LTP |
| binaries is added to the '$PATH' and you can execute it just by its name. |
| |
| TIP: If you need to execute such test from the LTP tree, you can add path to |
| current directory to '$PATH' manually with: 'PATH="$PATH:$PWD" ./foo01'. |
| |
| 2.2 Writing a test in C |
| ~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| 2.2.1 Basic test structure |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| Let's start with an example, following code is a simple test for a 'getenv()'. |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| /* |
| * This is test for basic functionality of getenv(). |
| * |
| * - create an env variable and verify that getenv() can get get it |
| * - call getenv() with nonexisting variable name, check that it returns NULL |
| */ |
| |
| #include "tst_test.h" |
| |
| #define ENV1 "LTP_TEST_ENV" |
| #define ENV2 "LTP_TEST_THIS_DOES_NOT_EXIST" |
| #define ENV_VAL "val" |
| |
| static void setup(void) |
| { |
| if (setenv(ENV1, ENV_VAL, 1)) |
| tst_brk(TBROK | TERRNO, "setenv() failed"); |
| } |
| |
| static void test(void) |
| { |
| char *ret; |
| |
| ret = getenv(ENV1); |
| |
| if (!ret) { |
| tst_res(TFAIL, "getenv(" ENV1 ") = NULL"); |
| goto next; |
| } |
| |
| if (!strcmp(ret, ENV_VAL)) { |
| tst_res(TPASS, "getenv(" ENV1 ") = '"ENV_VAL "'"); |
| } else { |
| tst_res(TFAIL, "getenv(" ENV1 ") = '%s', expected '" |
| ENV_VAL "'", ret); |
| } |
| |
| next: |
| ret = getenv(ENV2); |
| |
| if (ret) |
| tst_res(TFAIL, "getenv(" ENV2 ") = '%s'", ret); |
| else |
| tst_res(TPASS, "getenv(" ENV2 ") = NULL"); |
| } |
| |
| static struct tst_test test = { |
| .test_all = test, |
| .setup = setup, |
| }; |
| ------------------------------------------------------------------------------- |
| |
| Each test includes the 'tst_test.h' header and must define the 'struct |
| tst_test test' structure. |
| |
| The overall test initialization is done in the 'setup()' function. |
| |
| The overall cleanup is done in a 'cleanup()' function. Here 'cleanup()' is |
| omitted as the test does not have anything to clean up. If cleanup is set in |
| the test structure it's called on test exit just before the test library |
| cleanup. That especially means that cleanup can be called at any point in a |
| test execution. For example even when a test setup step has failed, therefore |
| the 'cleanup()' function must be able to cope with unfinished initialization, |
| and so on. |
| |
| The test itself is done in the 'test()' function. The test function must work |
| fine if called in a loop. |
| |
| There are two types of a test function pointers in the test structure. The |
| first one is a '.test_all' pointer that is used when test is implemented as a |
| single function. Then there is a '.test' function along with the number of |
| tests '.tcnt' that allows for more detailed result reporting. If the '.test' |
| pointer is set the function is called '.tcnt' times with an integer parameter |
| in range of [0, '.tcnt' - 1]. |
| |
| IMPORTANT: Only one of '.test' and '.test_all' can be set at a time. |
| |
| Each test has a default timeout set to 300s. The default timeout can be |
| overridden by setting '.timeout' in the test structure or by calling |
| 'tst_set_timeout()' in the test 'setup()'. There are a few testcases whose run |
| time may vary arbitrarily, for these timeout can be disabled by setting it to |
| -1. |
| |
| Test can find out how much time (in seconds) is remaining to timeout, |
| by calling 'tst_timeout_remaining()'. |
| |
| A word about the cleanup() callback |
| +++++++++++++++++++++++++++++++++++ |
| |
| There are a few rules that needs to be followed in order to write correct |
| cleanup() callback. |
| |
| 1. Free only resources that were initialized. Keep in mind that callback can |
| be executed at any point in the test run. |
| |
| 2. Make sure to free resources in the reverse order they were |
| initialized. (Some of the steps may not depend on others and everything |
| will work if there were swapped but let's keep it in order.) |
| |
| The first rule may seem complicated at first however, on the contrary, it's |
| quite easy. All you have to do is to keep track of what was already |
| initialized. For example file descriptors needs to be closed only if they were |
| assigned a valid file descriptor. For most of the things you need to create |
| extra flag that is set right after successful initialization though. Consider, |
| for example, test setup below. |
| |
| We also prefer cleaning up resources that would otherwise be released on the |
| program exit. There are two main reasons for this decision. Resources such as |
| file descriptors and mmaped memory could block umounting a block device in |
| cases where the test library has mounted a filesystem for the test temporary |
| directory. Not freeing allocated memory would upset static analysis and tools |
| such as valgrind and produce false-positives when checking for leaks in the |
| libc and other low level libraries. |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| static int fd0, fd1, mount_flag; |
| |
| #define MNTPOINT "mntpoint" |
| #define FILE1 "mntpoint/file1" |
| #define FILE2 "mntpoint/file2" |
| |
| static void setup(void) |
| { |
| SAFE_MKDIR(MNTPOINT, 0777); |
| SAFE_MKFS(tst_device->dev, tst_device->fs_type, NULL, NULL); |
| SAFE_MOUNT(tst_device->dev, MNTPOINT, tst_device->fs_type, 0, 0); |
| mount_flag = 1; |
| |
| fd0 = SAFE_OPEN(cleanup, FILE1, O_CREAT | O_RDWR, 0666); |
| fd1 = SAFE_OPEN(cleanup, FILE2, O_CREAT | O_RDWR, 0666); |
| } |
| ------------------------------------------------------------------------------- |
| |
| In this case the 'cleanup()' function may be invoked when any of the 'SAFE_*' |
| macros has failed and therefore must be able to work with unfinished |
| initialization as well. Since global variables are initialized to zero we can |
| just check that fd > 0 before we attempt to close it. The mount function |
| requires extra flag to be set after device was successfully mounted. |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| static void cleanup(void) |
| { |
| if (fd1 > 0) |
| SAFE_CLOSE(fd1); |
| |
| if (fd0 > 0) |
| SAFE_CLOSE(fd0); |
| |
| if (mount_flag && tst_umouont(MNTPOINT)) |
| tst_res(TWARN | TERRNO, "umount(%s)", MNTPOINT); |
| } |
| ------------------------------------------------------------------------------- |
| |
| IMPORTANT: 'SAFE_MACROS()' used in cleanup *do not* exit the test. Failure |
| only produces a warning and the 'cleanup()' carries on. This is |
| intentional as we want to execute as much 'cleanup()' as possible. |
| |
| WARNING: Calling tst_brk() in test 'cleanup()' does not exit the test as well |
| and 'TBROK' is converted to 'TWARN'. |
| |
| NOTE: Creation and removal of the test temporary directory is handled in |
| the test library and the directory is removed recursively. Therefore |
| we do not have to remove files and directories in the test cleanup. |
| |
| 2.2.2 Basic test interface |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| void tst_res(int ttype, char *arg_fmt, ...); |
| ------------------------------------------------------------------------------- |
| |
| Printf-like function to report test result, it's mostly used with ttype: |
| |
| |============================== |
| | 'TPASS' | Test has passed. |
| | 'TFAIL' | Test has failed. |
| | 'TINFO' | General message. |
| |============================== |
| |
| The 'ttype' can be combined bitwise with 'TERRNO' or 'TTERRNO' to print |
| 'errno', 'TST_ERR' respectively. |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| void tst_brk(int ttype, char *arg_fmt, ...); |
| ------------------------------------------------------------------------------- |
| |
| Printf-like function to report error and exit the test, it can be used with ttype: |
| |
| |============================================================ |
| | 'TBROK' | Something has failed in test preparation phase. |
| | 'TCONF' | Test is not appropriate for current configuration |
| (syscall not implemented, unsupported arch, ...) |
| |============================================================ |
| |
| The 'ttype' can be combined bitwise with 'TERRNO' or 'TTERRNO' to print |
| 'errno', 'TST_ERR' respectively. |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| const char *tst_strsig(int sig); |
| ------------------------------------------------------------------------------- |
| |
| Return the given signal number's corresponding string. |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| const char *tst_strerrno(int err); |
| ------------------------------------------------------------------------------- |
| |
| Return the given errno number's corresponding string. Using this function to |
| translate 'errno' values to strings is preferred. You should not use the |
| 'strerror()' function in the testcases. |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| const char *tst_strstatus(int status); |
| ------------------------------------------------------------------------------- |
| |
| Returns string describing the status as returned by 'wait()'. |
| |
| WARNING: This function is not thread safe. |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| void tst_set_timeout(unsigned int timeout); |
| ------------------------------------------------------------------------------- |
| |
| Allows for setting timeout per test iteration dynamically in the test setup(), |
| the timeout is specified in seconds. There are a few testcases whose runtime |
| can vary arbitrarily, these can disable timeouts by setting it to -1. |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| void tst_flush(void); |
| ------------------------------------------------------------------------------- |
| |
| Flush output streams, handling errors appropriately. |
| |
| This function is rarely needed when you have to flush the output streams |
| before calling 'fork()' or 'clone()'. Note that the 'SAFE_FORK()' calls this |
| function automatically. See 3.4 FILE buffers and fork() for explanation why is |
| this needed. |
| |
| 2.2.3 Test temporary directory |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| If '.needs_tmpdir' is set to '1' in the 'struct tst_test' unique test |
| temporary is created and it's set as the test working directory. Tests *MUST |
| NOT* create temporary files outside that directory. The flag is not needed to |
| be set when use these flags: '.all_filesystems', '.format_device', '.mntpoint', |
| '.mount_device' '.needs_checkpoints', '.needs_device', '.resource_file' |
| (these flags imply creating temporary directory). |
| |
| IMPORTANT: Close all file descriptors (that point to files in test temporary |
| directory, even the unlinked ones) either in the 'test()' function |
| or in the test 'cleanup()' otherwise the test may break temporary |
| directory removal on NFS (look for "NFS silly rename"). |
| |
| 2.2.4 Safe macros |
| ^^^^^^^^^^^^^^^^^ |
| |
| Safe macros aim to simplify error checking in test preparation. Instead of |
| calling system API functions, checking for their return value and aborting the |
| test if the operation has failed, you just use corresponding safe macro. |
| |
| Use them whenever it's possible. |
| |
| Instead of writing: |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| fd = open("/dev/null", O_RDONLY); |
| if (fd < 0) |
| tst_brk(TBROK | TERRNO, "opening /dev/null failed"); |
| ------------------------------------------------------------------------------- |
| |
| You write just: |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| fd = SAFE_OPEN("/dev/null", O_RDONLY); |
| ------------------------------------------------------------------------------- |
| |
| IMPORTANT: The SAFE_CLOSE() function also sets the passed file descriptor to -1 |
| after it's successfully closed. |
| |
| They can also simplify reading and writing of sysfs files, you can, for |
| example, do: |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| SAFE_FILE_SCANF("/proc/sys/kernel/pid_max", "%lu", &pid_max); |
| ------------------------------------------------------------------------------- |
| |
| See 'include/tst_safe_macros.h', 'include/tst_safe_stdio.h' and |
| 'include/tst_safe_file_ops.h' and 'include/tst_safe_net.h' for a complete list. |
| |
| 2.2.5 Test specific command line options |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| struct tst_option { |
| char *optstr; |
| char **arg; |
| char *help; |
| }; |
| ------------------------------------------------------------------------------- |
| |
| Test specific command line parameters can be passed with the 'NULL'-terminated |
| array of 'struct tst_option'. The 'optstr' is the command line option i.e. "o" |
| or "o:" if option has a parameter. Only short options are supported. The 'arg' |
| is where 'optarg' is stored upon match. If option has no parameter it's set to |
| non-'NULL' value if option was present. The 'help' is a short help string. |
| |
| NOTE: The test parameters must not collide with common test parameters defined |
| in the library the currently used ones are +-i+, +-I+, +-C+, and +-h+. |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| int tst_parse_int(const char *str, int *val, int min, int max); |
| int tst_parse_float(const char *str, float *val, float min, float max); |
| ------------------------------------------------------------------------------- |
| |
| Helpers for parsing the strings returned in the 'struct tst_option'. |
| |
| Both return zero on success and 'errno', mostly 'EINVAL' or 'ERANGE', on |
| failure. |
| |
| Both functions are no-op if 'str' is 'NULL'. |
| |
| The valid range for result includes both 'min' and 'max'. |
| |
| .Example Usage |
| [source,c] |
| ------------------------------------------------------------------------------- |
| #include <limits.h> |
| #include "tst_test.h" |
| |
| static char *str_threads; |
| static int threads = 10; |
| |
| static struct tst_option options[] = { |
| {"t:", &str_threads, "Number of threads (default 10)"}, |
| ... |
| {NULL, NULL, NULL} |
| }; |
| |
| static void setup(void) |
| { |
| if (tst_parse_int(str_threads, &threads, 1, INT_MAX)) |
| tst_brk(TBROK, "Invalid number of threads '%s'", str_threads); |
| |
| ... |
| } |
| |
| static void test_threads(void) |
| { |
| ... |
| |
| for (i = 0; i < threads; i++) { |
| ... |
| } |
| |
| ... |
| } |
| |
| static struct tst_test test = { |
| ... |
| .options = options, |
| ... |
| }; |
| ------------------------------------------------------------------------------- |
| |
| |
| 2.2.6 Runtime kernel version detection |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| Testcases for newly added kernel functionality require kernel newer than a |
| certain version to run. All you need to skip a test on older kernels is to |
| set the '.min_kver' string in the 'struct tst_test' to a minimal required |
| kernel version, e.g. '.min_kver = "2.6.30"'. |
| |
| For more complicated operations such as skipping a test for a certain range |
| of kernel versions, following functions could be used: |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| int tst_kvercmp(int r1, int r2, int r3); |
| |
| struct tst_kern_exv { |
| char *dist_name; |
| char *extra_ver; |
| }; |
| |
| int tst_kvercmp2(int r1, int r2, int r3, struct tst_kern_exv *vers); |
| ------------------------------------------------------------------------------- |
| |
| These two functions are intended for runtime kernel version detection. They |
| parse the output from 'uname()' and compare it to the passed values. |
| |
| The return value is similar to the 'strcmp()' function, i.e. zero means equal, |
| negative value means that the kernel is older than than the expected value and |
| positive means that it's newer. |
| |
| The second function 'tst_kvercmp2()' allows for specifying per-vendor table of |
| kernel versions as vendors typically backport fixes to their kernels and the |
| test may be relevant even if the kernel version does not suggests so. See |
| 'testcases/kernel/syscalls/inotify/inotify04.c' for example usage. |
| |
| WARNING: The shell 'tst_kvercmp' maps the result into unsigned integer - the |
| process exit value. |
| |
| 2.2.7 Fork()-ing |
| ^^^^^^^^^^^^^^^^ |
| |
| Be wary that if the test forks and there were messages printed by the |
| 'tst_*()' interfaces, the data may still be in libc/kernel buffers and these |
| *ARE NOT* flushed automatically. |
| |
| This happens when 'stdout' gets redirected to a file. In this case, the |
| 'stdout' is not line buffered, but block buffered. Hence after a fork content |
| of the buffers will be printed by the parent and each of the children. |
| |
| To avoid that you should use 'SAFE_FORK()'. |
| |
| IMPORTANT: You have to set the '.forks_child' flag in the test structure |
| if your testcase forks. |
| |
| 2.2.8 Doing the test in the child process |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| Results reported by 'tst_res()' are propagated to the parent test process via |
| block of shared memory. |
| |
| Calling 'tst_brk()' causes child process to exit with non-zero exit value. |
| Which means that it's safe to use 'SAFE_*()' macros in the child processes as |
| well. |
| |
| Children that outlive the 'test()' function execution are waited for in the |
| test library. Unclean child exit (killed by signal, non-zero exit value, etc.) |
| will cause the main test process to exit with 'tst_brk()', which especially |
| means that 'TBROK' propagated from a child process will cause the whole test |
| to exit with 'TBROK'. |
| |
| If a test needs a child that segfaults or does anything else that cause it to |
| exit uncleanly all you need to do is to wait for such children from the |
| 'test()' function so that it's reaped before the main test exits the 'test()' |
| function. |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| #include "tst_test.h" |
| |
| void tst_reap_children(void); |
| ------------------------------------------------------------------------------- |
| |
| The 'tst_reap_children()' function makes the process wait for all of its |
| children and exits with 'tst_brk(TBROK, ...)' if any of them returned |
| a non zero exit code. |
| |
| .Using 'tst_res()' from binaries started by 'exec()' |
| [source,c] |
| ------------------------------------------------------------------------------- |
| /* test.c */ |
| #define _GNU_SOURCE |
| #include <unistd.h> |
| #include "tst_test.h" |
| |
| static void do_test(void) |
| { |
| char *const argv[] = {"test_exec_child", NULL}; |
| char path[4096]; |
| |
| if (tst_get_path("test_exec_child", path, sizeof(path))) |
| tst_brk(TCONF, "Couldn't find test_exec_child in $PATH"); |
| |
| execve(path, argv, environ); |
| |
| tst_res(TBROK | TERRNO, "EXEC!"); |
| } |
| |
| static struct tst_test test = { |
| .test_all = do_test, |
| .child_needs_reinit = 1, |
| }; |
| |
| /* test_exec_child.c */ |
| #define TST_NO_DEFAULT_MAIN |
| #include "tst_test.h" |
| |
| int main(void) |
| { |
| tst_reinit(); |
| tst_res(TPASS, "Child passed!"); |
| return 0; |
| } |
| ------------------------------------------------------------------------------- |
| |
| The 'tst_res()' function can be also used from binaries started by 'exec()', |
| the parent test process has to set the '.child_needs_reinit' flag so that the |
| library prepares for it and has to make sure the 'LTP_IPC_PATH' environment |
| variable is passed down, then the very fist thing the program has to call in |
| 'main()' is 'tst_reinit()' that sets up the IPC. |
| |
| 2.2.9 Fork() and Parent-child synchronization |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| As LTP tests are written for Linux, most of the tests involve fork()-ing and |
| parent-child process synchronization. LTP includes a checkpoint library that |
| provides wait/wake futex based functions. |
| |
| In order to use checkpoints the '.needs_checkpoints' flag in the 'struct |
| tst_test' must be set to '1', this causes the test library to initialize |
| checkpoints before the 'test()' function is called. |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| #include "tst_test.h" |
| |
| TST_CHECKPOINT_WAIT(id) |
| |
| TST_CHECKPOINT_WAIT2(id, msec_timeout) |
| |
| TST_CHECKPOINT_WAKE(id) |
| |
| TST_CHECKPOINT_WAKE2(id, nr_wake) |
| |
| TST_CHECKPOINT_WAKE_AND_WAIT(id) |
| ------------------------------------------------------------------------------- |
| |
| The checkpoint interface provides pair of wake and wait functions. The 'id' is |
| unsigned integer which specifies checkpoint to wake/wait for. As a matter of |
| fact it's an index to an array stored in a shared memory, so it starts on |
| '0' and there should be enough room for at least of hundred of them. |
| |
| The 'TST_CHECKPOINT_WAIT()' and 'TST_CHECKPOINT_WAIT2()' suspends process |
| execution until it's woken up or until timeout is reached. |
| |
| The 'TST_CHECKPOINT_WAKE()' wakes one process waiting on the checkpoint. |
| If no process is waiting the function retries until it success or until |
| timeout is reached. |
| |
| If timeout has been reached process exits with appropriate error message (uses |
| 'tst_brk()'). |
| |
| The 'TST_CHECKPOINT_WAKE2()' does the same as 'TST_CHECKPOINT_WAKE()' but can |
| be used to wake precisely 'nr_wake' processes. |
| |
| The 'TST_CHECKPOINT_WAKE_AND_WAIT()' is a shorthand for doing wake and then |
| immediately waiting on the same checkpoint. |
| |
| Child processes created via 'SAFE_FORK()' are ready to use the checkpoint |
| synchronization functions, as they inherited the mapped page automatically. |
| |
| Child processes started via 'exec()', or any other processes not forked from |
| the test process must initialize the checkpoint by calling 'tst_reinit()'. |
| |
| For the details of the interface, look into the 'include/tst_checkpoint.h'. |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| #include "tst_test.h" |
| |
| /* |
| * Waits for process state change. |
| * |
| * The state is one of the following: |
| * |
| * R - process is running |
| * S - process is sleeping |
| * D - process sleeping uninterruptibly |
| * Z - zombie process |
| * T - process is traced |
| */ |
| TST_PROCESS_STATE_WAIT(pid, state) |
| ------------------------------------------------------------------------------- |
| |
| The 'TST_PROCESS_STATE_WAIT()' waits until process 'pid' is in requested |
| 'state'. The call polls +/proc/pid/stat+ to get this information. |
| |
| It's mostly used with state 'S' which means that process is sleeping in kernel |
| for example in 'pause()' or any other blocking syscall. |
| |
| 2.2.10 Signals and signal handlers |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| If you need to use signal handlers, keep the code short and simple. Don't |
| forget that the signal handler is called asynchronously and can interrupt the |
| code execution at any place. |
| |
| This means that problems arise when global state is changed both from the test |
| code and signal handler, which will occasionally lead to: |
| |
| * Data corruption (data gets into inconsistent state), this may happen, for |
| example, for any operations on 'FILE' objects. |
| |
| * Deadlock, this happens, for example, if you call 'malloc(2)', 'free(2)', |
| etc. from both the test code and the signal handler at the same time since |
| 'malloc' has global lock for it's internal data structures. (Be wary that |
| 'malloc(2)' is used by the libc functions internally too.) |
| |
| * Any other unreproducible and unexpected behavior. |
| |
| Quite common mistake is to call 'exit(3)' from a signal handler. Note that this |
| function is not signal-async-safe as it flushes buffers, etc. If you need to |
| exit a test immediately from a signal handler use '_exit(2)' instead. |
| |
| TIP: See 'man 7 signal' for the list of signal-async-safe functions. |
| |
| If a signal handler sets a variable, its declaration must be 'volatile', |
| otherwise compiler may misoptimize the code. This is because the variable may |
| not be changed in the compiler code flow analysis. There is 'sig_atomic_t' |
| type defined in C99 but this one *DOES NOT* imply 'volatile' (it's just a |
| 'typedef' to 'int'). So the correct type for a flag that is changed from a |
| signal handler is either 'volatile int' or 'volatile sig_atomic_t'. |
| |
| If a crash (e.g. triggered by signal SIGSEGV) is expected in testing, you |
| can avoid creation of core files by calling tst_no_corefile() function. |
| This takes effect for process (and its children) which invoked it, unless |
| they subsequently modify RLIMIT_CORE. |
| |
| Note that LTP library will reap any processes that test didn't reap itself, |
| and report any non-zero exit code as failure. |
| |
| 2.2.11 Kernel Modules |
| ^^^^^^^^^^^^^^^^^^^^^ |
| |
| There are certain cases where the test needs a kernel part and userspace part, |
| happily, LTP can build a kernel module and then insert it to the kernel on test |
| start for you. See 'testcases/kernel/device-drivers/block' for details. |
| |
| 2.2.12 Useful macros |
| ^^^^^^^^^^^^^^^^^^^^^ |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| ARRAY_SIZE(arr) |
| ------------------------------------------------------------------------------- |
| |
| Returns the size of statically defined array, i.e. |
| '(sizeof(arr) / sizeof(*arr))' |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| LTP_ALIGN(x, a) |
| ------------------------------------------------------------------------------- |
| |
| Aligns the x to be next multiple of a. The a must be power of 2. |
| |
| 2.2.13 Filesystem type detection |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| Some tests are known to fail on certain filesystems (you cannot swap on TMPFS, |
| there are unimplemented 'fcntl()' etc.). |
| |
| If your test needs to be skipped on certain filesystems, use the interface |
| below: |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| #include "tst_test.h" |
| |
| /* |
| * Unsupported only on NFS. |
| */ |
| if (tst_fs_type(".") == TST_NFS_MAGIC) |
| tst_brk(TCONF, "Test not supported on NFS filesystem"); |
| |
| |
| /* |
| * Unsupported on NFS, TMPFS and RAMFS |
| */ |
| long type; |
| |
| switch ((type = tst_fs_type("."))) { |
| case TST_NFS_MAGIC: |
| case TST_TMPFS_MAGIC: |
| case TST_RAMFS_MAGIC: |
| tst_brk(TCONF, "Test not supported on %s filesystem", |
| tst_fs_type_name(type)); |
| break; |
| } |
| ------------------------------------------------------------------------------- |
| |
| 2.2.14 Thread-safety in the LTP library |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| It is safe to use library 'tst_res()' function in multi-threaded tests. |
| |
| Only the main thread must return from the 'test()' function to the test |
| library and that must be done only after all threads that may call any library |
| function has been terminated. That especially means that threads that may call |
| 'tst_brk()' must terminate before the execution of the 'test()' function |
| returns to the library. This is usually done by the main thread joining all |
| worker threads at the end of the 'test()' function. Note that the main thread |
| will never get to the library code in a case that 'tst_brk()' was called from |
| one of the threads since it will sleep at least in 'pthread_join()' on the |
| thread that called the 'tst_brk()' till 'exit()' is called by 'tst_brk()'. |
| |
| The test-supplied cleanup function runs *concurrently* to the rest of the |
| threads in a case that cleanup was entered from 'tst_brk()'. Subsequent |
| threads entering 'tst_brk()' must be suspended or terminated at the start of |
| the user supplied cleanup function. It may be necessary to stop or exit |
| the rest of the threads before the test cleans up as well. For example threads |
| that create new files should be stopped before temporary directory is be |
| removed. |
| |
| Following code example shows thread safe cleanup function example using atomic |
| increment as a guard. The library calls its cleanup after the execution returns |
| from the user supplied cleanup and expects that only one thread returns from |
| the user supplied cleanup to the test library. |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| #include "tst_test.h" |
| |
| static void cleanup(void) |
| { |
| static int flag; |
| |
| if (tst_atomic_inc(&flag) != 1) |
| pthread_exit(NULL); |
| |
| /* if needed stop the rest of the threads here */ |
| |
| ... |
| |
| /* then do cleanup work */ |
| |
| ... |
| |
| /* only one thread returns to the library */ |
| } |
| ------------------------------------------------------------------------------- |
| |
| |
| 2.2.15 Testing with a block device |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| Some tests needs a block device (inotify tests, syscall 'EROFS' failures, |
| etc.). LTP library contains a code to prepare a testing device. |
| |
| If '.needs_device' flag in the 'struct tst_test' is set the 'tst_device' |
| structure is initialized with a path to a test device and default filesystem |
| to be used. |
| |
| You can also request minimal device size in megabytes by setting |
| '.dev_min_size' the device is guaranteed to have at least the requested size |
| then. |
| |
| If '.format_device' flag is set the device is formatted with a filesystem as |
| well. You can use '.dev_fs_type' to override the default filesystem type if |
| needed and pass additional options to mkfs via '.dev_fs_opts' and |
| '.dev_extra_opts' pointers. Note that '.format_device' implies '.needs_device' |
| there is no need to set both. |
| |
| If '.mount_device' is set, the device is mounted at '.mntpoint' which is used |
| to pass a directory name that will be created and used as mount destination. |
| You can pass additional flags and data to the mount command via '.mnt_flags' |
| and '.mnt_data' pointers. Note that '.mount_device' implies '.needs_device' |
| and '.format_device' so there is no need to set the later two. |
| |
| If '.needs_rofs' is set, read-only filesystem is mounted at '.mntpoint' this |
| one is supposed to be used for 'EROFS' tests. |
| |
| If '.all_filesystems' is set the test function is executed for all supported |
| filesystems. Supported filesystems are detected based on existence of the |
| 'mkfs.$fs' helper and on kernel support to mount it. For each supported |
| filesystem the 'tst_device.fs_type' is set to the currently tested fs type, if |
| '.format_device' is set the device is formatted as well, if '.mount_device' is |
| set it's mounted at '.mntpoint'. Also the test timeout is reset for each |
| execution of the test function. This flag is expected to be used for filesystem |
| related syscalls that are at least partly implemented in the filesystem |
| specific code e.g. fallocate(). |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| #include "tst_test.h" |
| |
| struct tst_device { |
| const char *dev; |
| const char *fs_type; |
| }; |
| |
| extern struct tst_device *tst_device; |
| |
| int tst_umount(const char *path); |
| ------------------------------------------------------------------------------- |
| |
| In case that 'LTP_DEV' is passed to the test in an environment, the library |
| checks that the file exists and that it's a block device, if |
| '.device_min_size' is set the device size is checked as well. If 'LTP_DEV' |
| wasn't set or if size requirements were not met a temporary file is created |
| and attached to a free loop device. |
| |
| If there is no usable device and loop device couldn't be initialized the test |
| exits with 'TCONF'. |
| |
| The 'tst_umount()' function works exactly as 'umount(2)' but retries several |
| times on 'EBUSY'. This is because various desktop daemons (gvfsd-trash is known |
| for that) may be stupid enough to probe all newly mounted filesystem which |
| results in 'umount(2)' failing with 'EBUSY'. |
| |
| IMPORTANT: All testcases should use 'tst_umount()' instead of 'umount(2)' to |
| umount filesystems. |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| #include "tst_test.h" |
| |
| int tst_find_free_loopdev(const char *path, size_t path_len); |
| ------------------------------------------------------------------------------- |
| |
| This function finds a free loopdev and returns the free loopdev minor (-1 for no |
| free loopdev). If path is non-NULL, it will be filled with free loopdev path. |
| If you want to use a customized loop device, we can call tst_find_free_loopdev |
| (NULL, 0) in tests to get a free minor number and then mknod. |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| #include "tst_test.h" |
| |
| unsigned long tst_dev_bytes_written(const char *dev); |
| ------------------------------------------------------------------------------- |
| |
| This function reads test block device stat file (/sys/block/<device>/stat) and |
| returns the bytes written since the last invocation of this function. To avoid |
| FS deferred IO metadata/cache interference, we suggest doing "syncfs" before the |
| tst_dev_bytes_written first invocation. And an inline function named tst_dev_sync |
| is created for that intention. |
| |
| 2.2.16 Formatting a device with a filesystem |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| #include "tst_test.h" |
| |
| static void setup(void) |
| { |
| ... |
| SAFE_MKFS(tst_device->dev, tst_device->fs_type, NULL, NULL); |
| ... |
| } |
| ------------------------------------------------------------------------------- |
| |
| This function takes a path to a device, filesystem type and an array of extra |
| options passed to mkfs. |
| |
| The fs options 'fs_opts' should either be 'NULL' if there are none, or a |
| 'NULL' terminated array of strings such as: |
| +const char *const opts[] = {"-b", "1024", NULL}+. |
| |
| The extra options 'extra_opts' should either be 'NULL' if there are none, or a |
| 'NULL' terminated array of strings such as +{"102400", NULL}+; 'extra_opts' |
| will be passed after device name. e.g: +mkfs -t ext4 -b 1024 /dev/sda1 102400+ |
| in this case. |
| |
| 2.2.17 Verifying a filesystem's free space |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| Some tests have size requirements for the filesystem's free space. If these |
| requirements are not satisfied, the tests should be skipped. |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| #include "tst_test.h" |
| |
| int tst_fs_has_free(const char *path, unsigned int size, unsigned int mult); |
| ------------------------------------------------------------------------------- |
| |
| The 'tst_fs_has_free()' function returns 1 if there is enough space and 0 if |
| there is not. |
| |
| The 'path' is the pathname of any directory/file within a filesystem. |
| |
| The 'mult' is a multiplier, one of 'TST_BYTES', 'TST_KB', 'TST_MB' or 'TST_GB'. |
| |
| The required free space is calculated by 'size * mult', e.g. |
| 'tst_fs_has_free("/tmp/testfile", 64, TST_MB)' will return 1 if the |
| filesystem, which '"/tmp/testfile"' is in, has 64MB free space at least, and 0 |
| if not. |
| |
| 2.2.18 Files, directories and fs limits |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| Some tests need to know the maximum count of links to a regular file or |
| directory, such as 'rename(2)' or 'linkat(2)' to test 'EMLINK' error. |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| #include "tst_test.h" |
| |
| int tst_fs_fill_hardlinks(const char *dir); |
| ------------------------------------------------------------------------------- |
| |
| Try to get maximum count of hard links to a regular file inside the 'dir'. |
| |
| NOTE: This number depends on the filesystem 'dir' is on. |
| |
| This function uses 'link(2)' to create hard links to a single file until it |
| gets 'EMLINK' or creates 65535 links. If the limit is hit, the maximum number of |
| hardlinks is returned and the 'dir' is filled with hardlinks in format |
| "testfile%i", where i belongs to [0, limit) interval. If no limit is hit or if |
| 'link(2)' failed with 'ENOSPC' or 'EDQUOT', zero is returned and previously |
| created files are removed. |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| #include "tst_test.h" |
| |
| int tst_fs_fill_subdirs(const char *dir); |
| ------------------------------------------------------------------------------- |
| |
| Try to get maximum number of subdirectories in directory. |
| |
| NOTE: This number depends on the filesystem 'dir' is on. For current kernel, |
| subdir limit is not available for all filesystems (available for ext2, ext3, |
| minix, sysv and more). If the test runs on some other filesystems, like ramfs, |
| tmpfs, it will not even try to reach the limit and return 0. |
| |
| This function uses 'mkdir(2)' to create directories in 'dir' until it gets |
| 'EMLINK' or creates 65535 directories. If the limit is hit, the maximum number |
| of subdirectories is returned and the 'dir' is filled with subdirectories in |
| format "testdir%i", where i belongs to [0, limit - 2) interval (because each |
| newly created dir has two links already - the '.' and the link from parent |
| dir). If no limit is hit or if 'mkdir(2)' failed with 'ENOSPC' or 'EDQUOT', |
| zero is returned and previously created directories are removed. |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| #include "tst_test.h" |
| |
| int tst_dir_is_empty(const char *dir, int verbose); |
| ------------------------------------------------------------------------------- |
| |
| Returns non-zero if directory is empty and zero otherwise. |
| |
| Directory is considered empty if it contains only '.' and '..'. |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| #include "tst_test.h" |
| |
| int tst_fill_fd(int fd, char pattern, size_t bs, size_t bcount); |
| ------------------------------------------------------------------------------- |
| |
| Fill a file with specified pattern using file descriptor. |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| #include "tst_test.h" |
| |
| int tst_fill_file(const char *path, char pattern, size_t bs, size_t bcount); |
| ------------------------------------------------------------------------------- |
| |
| Creates/overwrites a file with specified pattern using file path. |
| |
| 2.2.19 Getting an unused PID number |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| Some tests require a 'PID', which is not used by the OS (does not belong to |
| any process within it). For example, kill(2) should set errno to 'ESRCH' if |
| it's passed such 'PID'. |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| #include "tst_test.h" |
| |
| pid_t tst_get_unused_pid(void); |
| ------------------------------------------------------------------------------- |
| |
| Return a 'PID' value not used by the OS or any process within it. |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| #include "tst_test.h" |
| |
| int tst_get_free_pids(void); |
| ------------------------------------------------------------------------------- |
| |
| Returns number of unused pids in the system. Note that this number may be |
| different once the call returns and should be used only for rough estimates. |
| |
| 2.2.20 Running executables |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| #include "tst_test.h" |
| |
| int tst_run_cmd(const char *const argv[], |
| const char *stdout_path, |
| const char *stderr_path, |
| int pass_exit_val); |
| ------------------------------------------------------------------------------- |
| |
| 'tst_run_cmd' is a wrapper for 'vfork() + execvp()' which provides a way |
| to execute an external program. |
| |
| 'argv[]' is a NULL-terminated array of strings starting with the program name |
| which is followed by optional arguments. |
| |
| A non-zero 'pass_exit_val' makes 'tst_run_cmd' return the program exit code to |
| the caller. A zero for 'pass_exit_val' makes 'tst_run_cmd' exit the tests |
| on failure. |
| |
| In case that 'execvp()' has failed and the 'pass_exit_val' flag was set, the |
| return value is '255' if 'execvp()' failed with 'ENOENT' and '254' otherwise. |
| |
| 'stdout_path' and 'stderr_path' determine where to redirect the program |
| stdout and stderr I/O streams. |
| |
| .Example |
| [source,c] |
| ------------------------------------------------------------------------------- |
| #include "tst_test.h" |
| |
| const char *const cmd[] = { "ls", "-l", NULL }; |
| |
| ... |
| /* Store output of 'ls -l' into log.txt */ |
| tst_run_cmd(cmd, "log.txt", NULL, 0); |
| ... |
| ------------------------------------------------------------------------------- |
| |
| 2.2.21 Measuring elapsed time and helper functions |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| #include "tst_timer.h" |
| |
| void tst_timer_check(clockid_t clk_id); |
| |
| void tst_timer_start(clockid_t clk_id); |
| |
| void tst_timer_stop(void); |
| |
| struct timespec tst_timer_elapsed(void); |
| |
| long long tst_timer_elapsed_ms(void); |
| |
| long long tst_timer_elapsed_us(void); |
| |
| int tst_timer_expired_ms(long long ms); |
| ------------------------------------------------------------------------------- |
| |
| The 'tst_timer_check()' function checks if specified 'clk_id' is suppored and |
| exits the test with 'TCONF' otherwise. It's expected to be used in test |
| 'setup()' before any resources that needs to be cleaned up are initialized, |
| hence it does not include a cleanup function parameter. |
| |
| The 'tst_timer_start()' marks start time and stores the 'clk_id' for further |
| use. |
| |
| The 'tst_timer_stop()' marks the stop time using the same 'clk_id' as last |
| call to 'tst_timer_start()'. |
| |
| The 'tst_timer_elapsed*()' returns time difference between the timer start and |
| last timer stop in several formats and units. |
| |
| The 'tst_timer_expired_ms()' function checks if the timer started by |
| 'tst_timer_start()' has been running longer than ms milliseconds. The function |
| returns non-zero if timer has expired and zero otherwise. |
| |
| IMPORTANT: The timer functions use 'clock_gettime()' internally which needs to |
| be linked with '-lrt' on older glibc. Please do not forget to add |
| 'LDLIBS+=-lrt' in Makefile. |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| #include "tst_test.h" |
| #include "tst_timer.h" |
| |
| static void setup(void) |
| { |
| ... |
| tst_timer_check(CLOCK_MONOTONIC); |
| ... |
| } |
| |
| static void run(void) |
| { |
| ... |
| tst_timer_start(CLOCK_MONOTONIC); |
| ... |
| while (!tst_timer_expired_ms(5000)) { |
| ... |
| } |
| ... |
| } |
| |
| struct tst_test test = { |
| ... |
| .setup = setup, |
| .test_all = run, |
| ... |
| }; |
| ------------------------------------------------------------------------------- |
| |
| Expiration timer example usage. |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| long long tst_timespec_to_us(struct timespec t); |
| long long tst_timespec_to_ms(struct timespec t); |
| |
| struct timeval tst_us_to_timeval(long long us); |
| struct timeval tst_ms_to_timeval(long long ms); |
| |
| int tst_timespec_lt(struct timespec t1, struct timespec t2); |
| |
| struct timespec tst_timespec_add_us(struct timespec t, long long us); |
| |
| struct timespec tst_timespec_diff(struct timespec t1, struct timespec t2); |
| long long tst_timespec_diff_us(struct timespec t1, struct timespec t2); |
| long long tst_timespec_diff_ms(struct timespec t1, struct timespec t2); |
| |
| struct timespec tst_timespec_abs_diff(struct timespec t1, struct timespec t2); |
| long long tst_timespec_abs_diff_us(struct timespec t1, struct timespec t2); |
| long long tst_timespec_abs_diff_ms(struct timespec t1, struct timespec t2); |
| ------------------------------------------------------------------------------- |
| |
| The first four functions are simple inline conversion functions. |
| |
| The 'tst_timespec_lt()' function returns non-zero if 't1' is earlier than |
| 't2'. |
| |
| The 'tst_timespec_add_us()' function adds 'us' microseconds to the timespec |
| 't'. The 'us' is expected to be positive. |
| |
| The 'tst_timespec_diff*()' functions returns difference between two times, the |
| 't1' is expected to be later than 't2'. |
| |
| The 'tst_timespec_abs_diff*()' functions returns absolute value of difference |
| between two times. |
| |
| NOTE: All conversions to ms and us rounds the value. |
| |
| 2.2.22 Datafiles |
| ^^^^^^^^^^^^^^^^ |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| #include "tst_test.h" |
| |
| static const char *const res_files[] = { |
| "foo", |
| "bar", |
| NULL |
| }; |
| |
| static struct tst_test test = { |
| ... |
| .resource_files = res_files, |
| ... |
| } |
| ------------------------------------------------------------------------------- |
| |
| If the test needs additional files to be copied to the test temporary |
| directory all you need to do is to list their filenames in the |
| 'NULL'-terminated array '.resource_files' in the tst_test structure. |
| |
| When resource files is set test temporary directory is created automatically, |
| there is need to set '.needs_tmpdir' as well. |
| |
| The test library looks for datafiles first, these are either stored in a |
| directory called +datafiles+ in the +$PWD+ at the start of the test or in |
| +$LTPROOT/testcases/data/${test_binary_name}+. If the file is not found the |
| library looks into +$LTPROOT/testcases/bin/+ and to +$PWD+ at the start of the |
| test. This ensures that the testcases can copy the file(s) effortlessly both |
| when test is started from the directory it was compiled in as well as when LTP |
| was installed. |
| |
| The file(s) are copied to the newly created test temporary directory which is |
| set as the test working directory when the 'test()' functions is executed. |
| |
| 2.2.23 Code path tracing |
| ^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| 'tst_res' is a macro, so on when you define a function in one file: |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| int do_action(int arg) |
| { |
| ... |
| |
| if (ok) { |
| tst_res(TPASS, "check passed"); |
| return 0; |
| } else { |
| tst_res(TFAIL, "check failed"); |
| return -1; |
| } |
| } |
| ------------------------------------------------------------------------------- |
| |
| and call it from another file, the file and line reported by 'tst_res' in this |
| function will be from the former file. |
| |
| 'TST_TRACE' can make the analysis of such situations easier. It's a macro which |
| inserts a call to 'tst_res(TINFO, ...)' in case its argument evaluates to |
| non-zero. In this call to 'tst_res(TINFO, ...)' the file and line will be |
| expanded using the actual location of 'TST_TRACE'. |
| |
| For example, if this another file contains: |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| #include "tst_test.h" |
| |
| if (TST_TRACE(do_action(arg))) { |
| ... |
| } |
| ------------------------------------------------------------------------------- |
| |
| the generated output may look similar to: |
| |
| ------------------------------------------------------------------------------- |
| common.h:9: FAIL: check failed |
| test.c:8: INFO: do_action(arg) failed |
| ------------------------------------------------------------------------------- |
| |
| 2.2.24 Tainted kernels |
| ^^^^^^^^^^^^^^^^^^^^^^ |
| |
| If you need to detect, if a testcase triggers a kernel warning, bug or oops, |
| the following can be used to detect TAINT_W or TAINT_D: |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| #include "tst_test.h" |
| #include "tst_taint.h" |
| |
| void setup(void) |
| { |
| ... |
| tst_taint_init(TST_TAINT_W | TST_TAINT_D); |
| ... |
| } |
| ... |
| void run(void) |
| { |
| ... |
| if (tst_taint_check() == 0) |
| tst_res(TPASS, "kernel is not tainted"); |
| else |
| tst_res(TFAIL, "kernel is tainted"); |
| } |
| ------------------------------------------------------------------------------- |
| |
| You have to call tst_taint_init() with non-zero flags first, preferably during |
| setup(). The function will generate a TCONF if the requested flags are not |
| fully supported on the running kernel, and TBROK if either a zero mask was |
| supplied or if the kernel is already tainted before executing the test. |
| |
| Then you can call tst_taint_check() during run(), which returns 0 or the |
| tainted flags set in /proc/sys/kernel/tainted as specified earlier. |
| |
| Depending on your kernel version, not all tainted-flags will be supported. |
| |
| For reference to tainted kernels, see kernel documentation: |
| Documentation/admin-guide/tainted-kernels.rst or |
| https://www.kernel.org/doc/html/latest/admin-guide/tainted-kernels.html |
| |
| 2.2.25 Checksums |
| ^^^^^^^^^^^^^^^^ |
| |
| CRC32c checksum generation is supported by LTP. In order to use it, the |
| test should include "tst_checksum.h" header, then can call tst_crc32c(). |
| |
| 2.2.26 Checking kernel for the driver support |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| Some tests may need specific kernel drivers, either compiled in, or built |
| as a module. If .need_drivers points to a NULL-terminated array of kernel |
| module names these are all checked and the test exits with TCONF on the |
| first missing driver. |
| |
| Since it relies on modprobe command, the check will be skipped if the command |
| itself is not available on the system. |
| |
| 2.2.27 Saving & restoring /proc|sys values |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| LTP library can be instructed to save and restore value of specified |
| (/proc|sys) files. This is achieved by initialized tst_test struct |
| field 'save_restore'. It is a NULL terminated array of strings where |
| each string represents a file, whose value is saved at the beginning |
| and restored at the end of the test. Only first line of a specified |
| file is saved and restored. |
| |
| Pathnames can be optionally prefixed to specify how strictly (during |
| 'store') are handled errors: |
| |
| * (no prefix) - test ends with TCONF, if file doesn't exist |
| * '?' - test prints info message and continues, |
| if file doesn't exist or open/read fails |
| * '!' - test ends with TBROK, if file doesn't exist |
| |
| 'restore' is always strict and will TWARN if it encounters any error. |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| static const char *save_restore[] = { |
| "/proc/sys/kernel/core_pattern", |
| NULL, |
| }; |
| |
| static void setup(void) |
| { |
| FILE_PRINTF("/proc/sys/kernel/core_pattern", "/mypath"); |
| } |
| |
| static struct tst_test test = { |
| ... |
| .setup = setup, |
| .save_restore = save_restore, |
| }; |
| ------------------------------------------------------------------------------- |
| |
| 2.2.28 Parsing kernel .config |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| Generally testcases should attempt to autodetect as much kernel features as |
| possible based on the currently running kernel. We do have tst_check_driver() |
| to check if functionality that could be compiled as kernel module is present |
| on the system, disabled syscalls can be detected by checking for 'ENOSYS' |
| errno etc. |
| |
| However in rare cases core kernel features couldn't be detected based on the |
| kernel userspace API and we have to resort to kernel .config parsing. |
| |
| For this cases the test should set the 'NULL' terminated needs_kconfig array |
| of kernel config options required for the test. The config option can be |
| specified either as plain "CONFIG_FOO" in which case it's sufficient for the |
| test continue if it's set to any value (typically =y or =m). Or with a value |
| as "CONFIG_FOO=bar" in which case the value has to match as well. The test is |
| aborted with 'TCONF' if any of the required options were not set. |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| #include "tst_test.h" |
| |
| static const char *kconfigs[] = { |
| "CONFIG_X86_INTEL_UMIP", |
| NULL |
| }; |
| |
| static struct tst_test test = { |
| ... |
| .needs_kconfigs = kconfigs, |
| ... |
| }; |
| ------------------------------------------------------------------------------- |
| |
| 2.2.29 Changing the Wall Clock Time during test execution |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| There are some tests that, for different reasons, might need to change the |
| system-wide clock time. Whenever this happens, it is imperative that the clock |
| is restored, at the end of test's execution, taking in consideration the amount |
| of time elapsed during that test. |
| |
| In order for that to happen, struct tst_test has a variable called |
| "restore_wallclock" that should be set to "1" so LTP knows it should: (1) |
| initialize a monotonic clock during test setup phase and (2) use that monotonic |
| clock to fix the system-wide clock time at the test cleanup phase. |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| #include "tst_test.h" |
| |
| static void setup(void) |
| { |
| ... |
| } |
| |
| static void run(void) |
| { |
| ... |
| } |
| |
| struct tst_test test = { |
| ... |
| .setup = setup, |
| .test_all = run, |
| .restore_wallclock = 1, |
| ... |
| }; |
| ------------------------------------------------------------------------------- |
| |
| 2.2.30 Testing similar syscalls in one test |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| In some cases kernel has several very similar syscalls that do either the same |
| or very similar job. This is most noticeable on i386 where we commonly have |
| two or three syscall versions. That is because i386 was first platform that |
| Linux was developed on and because of that most mistakes in API happened there |
| as well. However this is not limited to i386 at all, it's quite common that |
| version two syscall has added missing flags parameters or so. |
| |
| In such cases it does not make much sense to copy&paste the test code over and |
| over, rather than that the test library provides support for test variants. |
| The idea behind test variants is simple, we run the test several times each |
| time with different syscall variant. |
| |
| The implementation consist of test_variant integer that, if set, denotes number |
| of test variants. The test is then forked and executed test_variant times each |
| time with different value in global tst_variant variable. |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| #include "tst_test.h" |
| |
| static int do_foo(void) |
| { |
| switch (tst_variant) { |
| case 0: |
| return foo(); |
| case 1: |
| return syscall(__NR_foo); |
| } |
| |
| return -1; |
| } |
| |
| static void run(void) |
| { |
| ... |
| |
| TEST(do_foo); |
| |
| ... |
| } |
| |
| static void setup(void) |
| { |
| switch (tst_variant) { |
| case 0: |
| tst_res(TINFO, "Testing foo variant 1"); |
| break; |
| case 1: |
| tst_res(TINFO, "Testing foo variant 2"); |
| break; |
| } |
| } |
| |
| struct tst_test test = { |
| ... |
| .setup = setup, |
| .test_all = run, |
| .test_variants = 2, |
| ... |
| }; |
| ------------------------------------------------------------------------------- |
| |
| 2.2.31 Guarded buffers |
| ^^^^^^^^^^^^^^^^^^^^^^ |
| |
| The test library supports guarded buffers, which are buffers allocated so |
| that: |
| |
| * The end of the buffer is followed by a PROT_NONE page |
| |
| * The remainder of the page before the buffer is filled with random canary |
| data |
| |
| Which means that the any access after the buffer will yield a Segmentation |
| fault or EFAULT depending on if the access happened in userspace or the kernel |
| respectively. The canary before the buffer will also catch any write access |
| outside of the buffer. |
| |
| The purpose of the patch is to catch off-by-one bugs which happens when |
| buffers and structures are passed to syscalls. New tests should allocate |
| guarded buffers for all data passed to the tested syscall which are passed by |
| a pointer. |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| #include "tst_test.h" |
| |
| static struct foo *foo_ptr; |
| static struct iovec *iov; |
| static void *buf_ptr; |
| static char *id; |
| ... |
| |
| static void run(void) |
| { |
| ... |
| |
| foo_ptr->bar = 1; |
| foo_ptr->buf = buf_ptr; |
| |
| ... |
| } |
| |
| static void setup(void) |
| { |
| ... |
| |
| id = tst_strdup(string); |
| |
| ... |
| } |
| |
| static struct tst_test test = { |
| ... |
| .bufs = (struct tst_buffers []) { |
| {&foo_ptr, .size = sizeof(*foo_ptr)}, |
| {&buf_ptr, .size = BUF_SIZE}, |
| {&iov, .iov_sizes = (int[]){128, 32, -1}, |
| {} |
| } |
| }; |
| ------------------------------------------------------------------------------- |
| |
| Guarded buffers can be allocated on runtime in a test setup() by a |
| 'tst_alloc()' or by 'tst_strdup()' as well as by filling up the .bufs array in |
| the tst_test structure. |
| |
| So far the tst_test structure supports allocating either a plain buffer by |
| setting up the size or struct iovec, which is allocated recursively including |
| the individual buffers as described by an '-1' terminated array of buffer |
| sizes. |
| |
| 2.2.32 Adding and removing capabilities |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| Some tests may require the presence or absence of particular |
| capabilities. Using the API provided by 'tst_capability.h' the test author can |
| try to ensure that some capabilities are either present or absent during the |
| test. |
| |
| For example; below we try to create a raw socket, which requires |
| CAP_NET_ADMIN. During setup we should be able to do it, then during run it |
| should be impossible. The LTP capability library will check before setup that |
| we have this capability, then after setup it will drop it. |
| |
| [source,c] |
| -------------------------------------------------------------------------------- |
| #include "tst_test.h" |
| #include "tst_capability.h" |
| #include "tst_safe_net.h" |
| |
| #include "lapi/socket.h" |
| |
| static void run(void) |
| { |
| TEST(socket(AF_INET, SOCK_RAW, 1)); |
| if (TST_RET > -1) { |
| tst_res(TFAIL, "Created raw socket"); |
| } else if (TST_ERR != EPERM) { |
| tst_res(TBROK | TTERRNO, |
| "Failed to create socket for wrong reason"); |
| } else { |
| tst_res(TPASS | TTERRNO, "Didn't create raw socket"); |
| } |
| } |
| |
| static void setup(void) |
| { |
| TEST(socket(AF_INET, SOCK_RAW, 1)); |
| if (TST_RET < 0) |
| tst_brk(TCONF | TTERRNO, "We don't have CAP_NET_RAW to begin with"); |
| |
| SAFE_CLOSE(TST_RET); |
| } |
| |
| static struct tst_test test = { |
| .setup = setup, |
| .test_all = run, |
| .caps = (struct tst_cap []) { |
| TST_CAP(TST_CAP_REQ, CAP_NET_RAW), |
| TST_CAP(TST_CAP_DROP, CAP_NET_RAW), |
| {} |
| }, |
| }; |
| -------------------------------------------------------------------------------- |
| |
| Look at the test struct at the bottom. We have filled in the 'caps' field with |
| a NULL terminated array containing two 'tst_cap' structs. 'TST_CAP_REQ' |
| actions are executed before setup and 'TST_CAP_DROP' are executed after |
| setup. This means it is possible to both request and drop a capability. |
| |
| [source,c] |
| -------------------------------------------------------------------------------- |
| static struct tst_test test = { |
| .test_all = run, |
| .caps = (struct tst_cap []) { |
| TST_CAP(TST_CAP_REQ, CAP_NET_RAW), |
| TST_CAP(TST_CAP_DROP, CAP_SYS_ADMIN), |
| {} |
| }, |
| }; |
| -------------------------------------------------------------------------------- |
| |
| Here we request 'CAP_NET_RAW', but drop 'CAP_SYS_ADMIN'. If the capability is |
| in the permitted set, but not the effective set, the library will try to |
| permit it. If it is not in the permitted set, then it will fail with 'TCONF'. |
| |
| This API does not require 'libcap' to be installed. However it has limited |
| features relative to 'libcap'. It only tries to add or remove capabilities |
| from the effective set. This means that tests which need to spawn child |
| processes may have difficulties ensuring the correct capabilities are |
| available to the children (see the capabilities (7) manual pages). |
| |
| However a lot of problems can be solved by using 'tst_cap_action(struct |
| tst_cap *cap)' directly which can be called at any time. This also helps if |
| you wish to drop a capability at the begining of setup. |
| |
| 2.2.33 Reproducing race-conditions |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| If a bug is caused by two tasks in the kernel racing and you wish to create a |
| regression test (or bug-fix validation test) then the 'tst_fuzzy_sync.h' |
| library should be used. |
| |
| It allows you to specify, in your code, two race windows. One window in each |
| thread's loop (triggering a race usually requires many iterations). These |
| windows show fuzzy-sync where the race can happen. They don't need to be |
| exact, hence the 'fuzzy' part. If the race condition is not immediately |
| triggered then the library will begin experimenting with different timings. |
| |
| [source,c] |
| -------------------------------------------------------------------------------- |
| #include "tst_fuzzy_sync.h" |
| |
| static struct tst_fzsync_pair fzsync_pair; |
| |
| static void setup(void) |
| { |
| tst_fzsync_pair_init(&fzsync_pair); |
| } |
| |
| static void cleanup(void) |
| { |
| tst_fzsync_pair_cleanup(&fzsync_pair); |
| } |
| |
| static void *thread_b(void *arg) |
| { |
| while (tst_fzsync_run_b(&fzsync_pair)) { |
| |
| tst_fzsync_start_race_b(&fzsync_pair); |
| |
| /* This is the race window for thread B */ |
| |
| tst_fzsync_end_race_b(&fzsync_pair); |
| } |
| |
| return arg; |
| } |
| |
| static void thread_a(void) |
| { |
| tst_fzsync_pair_reset(&fzsync_pair, thread_b); |
| |
| while (tst_fzsync_run_a(&fzsync_pair)) { |
| |
| tst_fzsync_start_race_a(&fzsync_pair); |
| |
| /* This is the race window for thread A */ |
| |
| tst_fzsync_end_race_a(&fzsync_pair); |
| } |
| } |
| |
| static struct tst_test test = { |
| .test_all = thread_a, |
| .setup = setup, |
| .cleanup = cleanup, |
| }; |
| -------------------------------------------------------------------------------- |
| |
| Above is a minimal template for a test using fuzzy-sync. In a simple case, you |
| just need to put the bits you want to race inbetween 'start_race' and |
| 'end_race'. Meanwhile, any setup you need to do per-iteration goes outside the |
| windows. |
| |
| Fuzzy sync synchronises 'run_a' and 'run_b', which act as barriers, so that |
| neither thread can progress until the other has caught up with it. There is |
| also the 'pair_wait' function which can be used to add barriers in other |
| locations. Of course 'start/end_race_a/b' are also a barriers. |
| |
| The library decides how long the test should run for based on the timeout |
| specified by the user plus some other heuristics. |
| |
| For full documentation see the comments in 'include/tst_fuzzy_sync.h'. |
| |
| 2.3 Writing a testcase in shell |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| LTP supports testcases to be written in a portable shell too. |
| |
| There is a shell library modeled closely to the C interface at |
| 'testcases/lib/tst_test.sh'. |
| |
| WARNING: All identifiers starting with TST_ or tst_ are reserved for the |
| test library. |
| |
| 2.3.1 Basic test interface |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| [source,sh] |
| ------------------------------------------------------------------------------- |
| #!/bin/sh |
| # SPDX-License-Identifier: GPL-2.0-or-later |
| # This is a basic test for true shell builtin |
| |
| TST_TESTFUNC=do_test |
| . tst_test.sh |
| |
| do_test() |
| { |
| true |
| ret=$? |
| |
| if [ $ret -eq 0 ]; then |
| tst_res TPASS "true returned 0" |
| else |
| tst_res TFAIL "true returned $ret" |
| fi |
| } |
| |
| tst_run |
| ------------------------------------------------------------------------------- |
| |
| TIP: To execute this test the 'tst_test.sh' library must be in '$PATH'. If you |
| are executing the test from a git checkout you can run it as |
| 'PATH="$PATH:../../lib" ./foo01.sh' |
| |
| The shell library expects test setup, cleanup and the test function executing |
| the test in the '$TST_SETUP', '$TST_CLEANUP' and '$TST_TESTFUNC' variables. |
| |
| Both '$TST_SETUP' and '$TST_CLEANUP' are optional. |
| |
| The '$TST_TESTFUNC' may be called several times if more than one test |
| iteration was requested by passing right command line options to the test. |
| |
| The '$TST_CLEANUP' may be called even in the middle of the setup and must be |
| able to clean up correctly even in this situation. The easiest solution for |
| this is to keep track of what was initialized and act accordingly in the |
| cleanup. |
| |
| WARNING: Similar to the C library, calling tst_brk() in the $TST_CLEANUP does |
| not exit the test and 'TBROK' is converted to 'TWARN'. |
| |
| Notice also the 'tst_run' function called at the end of the test that actually |
| starts the test. |
| |
| [source,sh] |
| ------------------------------------------------------------------------------- |
| #!/bin/sh |
| # SPDX-License-Identifier: GPL-2.0-or-later |
| # Example test with tests in separate functions |
| |
| TST_TESTFUNC=test |
| TST_CNT=2 |
| . tst_test.sh |
| |
| test1() |
| { |
| tst_res TPASS "Test $1 passed" |
| } |
| |
| test2() |
| { |
| tst_res TPASS "Test $1 passed" |
| } |
| |
| tst_run |
| # output: |
| # foo 1 TPASS: Test 1 passed |
| # foo 2 TPASS: Test 2 passed |
| ------------------------------------------------------------------------------- |
| |
| If '$TST_CNT' is set, the test library looks if there are functions named |
| '$\{TST_TESTFUNC\}1', ..., '$\{TST_TESTFUNC\}$\{TST_CNT\}' and if these are |
| found they are executed one by one. The test number is passed to it in the '$1'. |
| |
| [source,sh] |
| ------------------------------------------------------------------------------- |
| #!/bin/sh |
| # SPDX-License-Identifier: GPL-2.0-or-later |
| # Example test with tests in a single function |
| |
| TST_TESTFUNC=do_test |
| TST_CNT=2 |
| . tst_test.sh |
| |
| do_test() |
| { |
| case $1 in |
| 1) tst_res TPASS "Test $1 passed";; |
| 2) tst_res TPASS "Test $1 passed";; |
| esac |
| } |
| |
| tst_run |
| # output: |
| # foo 1 TPASS: Test 1 passed |
| # foo 2 TPASS: Test 2 passed |
| ------------------------------------------------------------------------------- |
| |
| Otherwise, if '$TST_CNT' is set but there is no '$\{TST_TESTFUNC\}1', etc., |
| the '$TST_TESTFUNC' is executed '$TST_CNT' times and the test number is passed |
| to it in the '$1'. |
| |
| [source,sh] |
| ------------------------------------------------------------------------------- |
| #!/bin/sh |
| # SPDX-License-Identifier: GPL-2.0-or-later |
| # Example test with tests in a single function, using $TST_TEST_DATA and |
| # $TST_TEST_DATA_IFS |
| |
| TST_TESTFUNC=do_test |
| TST_TEST_DATA="foo:bar:d dd" |
| TST_TEST_DATA_IFS=":" |
| . tst_test.sh |
| |
| do_test() |
| { |
| tst_res TPASS "Test $1 passed with data '$2'" |
| } |
| |
| tst_run |
| # output: |
| # foo 1 TPASS: Test 1 passed with data 'foo' |
| # foo 2 TPASS: Test 1 passed with data 'bar' |
| # foo 3 TPASS: Test 1 passed with data 'd dd' |
| ------------------------------------------------------------------------------- |
| |
| It's possible to pass data for function with '$TST_TEST_DATA'. Optional |
| '$TST_TEST_DATA_IFS' is used for splitting, default value is space. |
| |
| [source,sh] |
| ------------------------------------------------------------------------------- |
| #!/bin/sh |
| # SPDX-License-Identifier: GPL-2.0-or-later |
| # Example test with tests in a single function, using $TST_TEST_DATA and $TST_CNT |
| |
| TST_TESTFUNC=do_test |
| TST_CNT=2 |
| TST_TEST_DATA="foo bar" |
| . tst_test.sh |
| |
| do_test() |
| { |
| case $1 in |
| 1) tst_res TPASS "Test $1 passed with data '$2'";; |
| 2) tst_res TPASS "Test $1 passed with data '$2'";; |
| esac |
| } |
| |
| tst_run |
| # output: |
| # foo 1 TPASS: Test 1 passed with data 'foo' |
| # foo 2 TPASS: Test 2 passed with data 'foo' |
| # foo 3 TPASS: Test 1 passed with data 'bar' |
| # foo 4 TPASS: Test 2 passed with data 'bar' |
| ------------------------------------------------------------------------------- |
| |
| '$TST_TEST_DATA' can be used with '$TST_CNT'. If '$TST_TEST_DATA_IFS' not specified, |
| space as default value is used. Of course, it's possible to use separate functions. |
| |
| 2.3.2 Library environment variables for shell |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| Similarily to the C library various checks and preparations can be requested |
| simply by setting right '$TST_NEEDS_FOO'. |
| |
| [options="header"] |
| |============================================================================= |
| | Variable name | Action done |
| | 'TST_NEEDS_ROOT' | Exit the test with 'TCONF' unless executed under root |
| | 'TST_NEEDS_TMPDIR' | Create test temporary directory and cd into it. |
| | 'TST_NEEDS_DEVICE' | Prepare test temporary device, the path to testing |
| device is stored in '$TST_DEVICE' variable. |
| The option implies 'TST_NEEDS_TMPDIR'. |
| | 'TST_NEEDS_CMDS' | String with command names that has to be present for |
| the test (see below). |
| | 'TST_NEEDS_MODULE' | Test module name needed for the test (see below). |
| | 'TST_NEEDS_DRIVERS'| Checks kernel drivers support for the test. |
| | 'TST_TIMEOUT' | Maximum timeout set for the test in sec. Must be int >= 1, |
| or -1 (special value to disable timeout), default is 300. |
| Variable is meant be set in tests, not by user. |
| It's equivalent of `tst_test.timeout` in C. |
| |============================================================================= |
| |
| NOTE: Network tests (see testcases/network/README.md) use additional variables |
| in 'tst_net.sh'. |
| |
| Checking for presence of commands |
| +++++++++++++++++++++++++++++++++ |
| |
| [source,sh] |
| ------------------------------------------------------------------------------- |
| #!/bin/sh |
| |
| ... |
| |
| TST_NEEDS_CMDS="modinfo modprobe" |
| . tst_test.sh |
| |
| ... |
| |
| ------------------------------------------------------------------------------- |
| |
| Setting '$TST_NEEDS_CMDS' to a string listing required commands will check for |
| existence each of them and exits the test with 'TCONF' on first missing. |
| |
| Alternatively the 'tst_require_cmds()' function can be used to do the same on |
| runtime, since sometimes we need to the check at runtime too. |
| |
| 'tst_check_cmds()' can be used for requirements just for a particular test |
| as it doesn't exit (it issues 'tst_res TCONF'). Expected usage is: |
| ... |
| |
| TST_TESTFUNC=do_test |
| . tst_test.sh |
| |
| do_test() |
| { |
| tst_check_cmds cmd || return |
| cmd --foo |
| ... |
| } |
| |
| tst_run |
| ... |
| |
| Locating kernel modules |
| +++++++++++++++++++++++ |
| |
| The LTP build system can build kernel modules as well, setting |
| '$TST_NEEDS_MODULE' to module name will cause the library to look for the |
| module in a few possible paths. |
| |
| If module was found the path to it will be stored into '$TST_MODPATH' |
| variable, if module wasn't found the test will exit with 'TCONF'. |
| |
| 2.3.3 Optional command line parameters |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| [source,sh] |
| ------------------------------------------------------------------------------- |
| #!/bin/sh |
| # SPDX-License-Identifier: GPL-2.0-or-later |
| # Optional test command line parameters |
| |
| TST_OPTS="af:" |
| TST_USAGE=usage |
| TST_PARSE_ARGS=parse_args |
| TST_TESTFUNC=do_test |
| |
| . tst_test.sh |
| |
| ALTERNATIVE=0 |
| MODE="foo" |
| |
| usage() |
| { |
| cat << EOF |
| usage: $0 [-a] [-f <foo|bar>] |
| |
| OPTIONS |
| -a Enable support for alternative foo |
| -f Specify foo or bar mode |
| EOF |
| } |
| |
| parse_args() |
| { |
| case $1 in |
| a) ALTERNATIVE=1;; |
| f) MODE="$2";; |
| esac |
| } |
| |
| do_test() |
| { |
| ... |
| } |
| |
| tst_run |
| ------------------------------------------------------------------------------- |
| |
| The 'getopts' string for optional parameters is passed in the '$TST_OPTS' |
| variable. There are a few default parameters that cannot be used by a test, |
| these can be listed with passing help '-h' option to any test. |
| |
| The function that prints the usage is passed in '$TST_USAGE', the help for |
| the options implemented in the library is appended when usage is printed. |
| |
| Lastly the function '$PARSE_ARGS' is called with the option name in the '$1' |
| and, if option has argument, its value in the '$2'. |
| |
| [source,sh] |
| ------------------------------------------------------------------------------- |
| #!/bin/sh |
| # SPDX-License-Identifier: GPL-2.0-or-later |
| # Optional test positional parameters |
| |
| TST_POS_ARGS=3 |
| TST_USAGE=usage |
| TST_TESTFUNC=do_test |
| |
| . tst_test.sh |
| |
| usage() |
| { |
| cat << EOF |
| usage: $0 [min] [max] [size] |
| |
| EOF |
| } |
| |
| min="$1" |
| max="$2" |
| size="$3" |
| |
| do_test() |
| { |
| ... |
| } |
| |
| tst_run |
| ------------------------------------------------------------------------------- |
| |
| You can also request a number of positional parameters by setting the |
| '$TST_POS_ARGS' variable. If you do, these will be available as they were |
| passed directly to the script in '$1', '$2', ..., '$n'. |
| |
| 2.3.4 Useful library functions |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| Retrieving configuration variables |
| ++++++++++++++++++++++++++++++++++ |
| |
| You may need to retrieve configuration values such as PAGESIZE, there is |
| 'getconf' but as some system may not have it, you are advised to use |
| 'tst_getconf' instead. Note that it implements subset of 'getconf' |
| system variables used by the testcases only. |
| |
| [source,sh] |
| ------------------------------------------------------------------------------- |
| # retrieve PAGESIZE |
| pagesize=`tst_getconf PAGESIZE` |
| ------------------------------------------------------------------------------- |
| |
| Sleeping for subsecond intervals |
| ++++++++++++++++++++++++++++++++ |
| |
| Albeit there is a sleep command available basically everywhere not all |
| implementations can support sleeping for less than one second. And most of the |
| time sleeping for a second is too much. Therefore LTP includes 'tst_sleep' |
| that can sleep for defined amount of seconds, milliseconds or microseconds. |
| |
| [source,sh] |
| ------------------------------------------------------------------------------- |
| # sleep for 100 milliseconds |
| tst_sleep 100ms |
| ------------------------------------------------------------------------------- |
| |
| Retry a function in limited time |
| ++++++++++++++++++++++++++++++++ |
| |
| Sometimes LTP test needs retrying a function for many times to get success. |
| This achievement makes that possible via keeping it retrying if the return |
| value of the function is NOT as we expected. After exceeding a limited time, |
| test will break from the retries immediately. The time limit is multiplied |
| with LTP_TIMEOUT_MUL. |
| |
| [source,c] |
| ------------------------------------------------------------------------------- |
| # retry function in 1 second |
| TST_RETRY_FUNC(FUNC, EXPECTED_RET) |
| |
| # retry function in N second |
| TST_RETRY_FN_EXP_BACKOFF(FUNC, EXPECTED_RET, N) |
| ------------------------------------------------------------------------------- |
| |
| [source,sh] |
| ------------------------------------------------------------------------------- |
| # retry function in 1 second |
| TST_RETRY_FUNC "FUNC arg1 arg2 ..." "EXPECTED_RET" |
| |
| # retry function in N second |
| TST_RETRY_FN_EXP_BACKOFF "FUNC arg1 arg2 ..." "EXPECTED_RET" "N" |
| ------------------------------------------------------------------------------- |
| |
| Checking for integers |
| +++++++++++++++++++++ |
| |
| [source,sh] |
| ------------------------------------------------------------------------------- |
| # returns zero if passed an integer parameter, non-zero otherwise |
| tst_is_int "$FOO" |
| ------------------------------------------------------------------------------- |
| |
| Checking for integers and floating point numbers |
| ++++++++++++++++++++++++++++++++++++++++++++++++ |
| |
| [source,sh] |
| ------------------------------------------------------------------------------- |
| # returns zero if passed an integer or floating point number parameter, |
| # non-zero otherwise |
| tst_is_num "$FOO" |
| ------------------------------------------------------------------------------- |
| |
| Obtaining random numbers |
| ++++++++++++++++++++++++ |
| |
| There is no '$RANDOM' in portable shell, use 'tst_random' instead. |
| |
| [source,sh] |
| ------------------------------------------------------------------------------- |
| # get random integer between 0 and 1000 (including 0 and 1000) |
| tst_random 0 1000 |
| ------------------------------------------------------------------------------- |
| |
| Formatting device with a filesystem |
| +++++++++++++++++++++++++++++++++++ |
| |
| The 'tst_mkfs' helper will format device with the filesystem. |
| |
| [source,sh] |
| ------------------------------------------------------------------------------- |
| # format test device with ext2 |
| tst_mkfs ext2 $TST_DEVICE |
| # default params are $TST_FS_TYPE $TST_DEVICE |
| tst_mkfs |
| # optional parameters |
| tst_mkfs ext4 /dev/device -T largefile |
| ------------------------------------------------------------------------------- |
| |
| Mounting and unmounting filesystems |
| +++++++++++++++++++++++++++++++++++ |
| |
| The 'tst_mount' and 'tst_umount' helpers are a safe way to mount/umount |
| a filesystem. |
| |
| The 'tst_mount' mounts '$TST_DEVICE' of '$TST_FS_TYPE' (optional) to |
| '$TST_MNTPOINT' (defaults to mntpoint), optionally using the |
| '$TST_MNT_PARAMS'. The '$TST_MNTPOINT' directory is created if it didn't |
| exist prior to the function call. |
| |
| If the path passed (optional, defaults to '$TST_DEVICE') to the 'tst_umount' is |
| not mounted (present in '/proc/mounts') it's noop. |
| Otherwise it retries to umount the filesystem a few times on a failure, which |
| is a workaround since there are a daemons dumb enough to probe all newly |
| mounted filesystems, which prevents them from umounting shortly after they |
| were mounted. |
| |
| ROD and ROD_SILENT |
| ++++++++++++++++++ |
| |
| These functions supply the 'SAFE_MACROS' used in C although they work and are |
| named differently. |
| |
| [source,sh] |
| ------------------------------------------------------------------------------- |
| ROD_SILENT command arg1 arg2 ... |
| |
| # is shorthand for: |
| |
| command arg1 arg2 ... > /dev/null 2>&1 |
| if [ $? -ne 0 ]; then |
| tst_brkm TBROK "..." |
| fi |
| |
| |
| ROD command arg1 arg2 ... |
| |
| # is shorthand for: |
| |
| ROD arg1 arg2 ... |
| if [ $? -ne 0 ]; then |
| tst_brkm TBROK "..." |
| fi |
| ------------------------------------------------------------------------------- |
| |
| WARNING: Keep in mind that output redirection (to a file) happens in the |
| caller rather than in the ROD function and cannot be checked for |
| write errors by the ROD function. |
| |
| As a matter of a fact doing +ROD echo a > /proc/cpuinfo+ would work just fine |
| since the 'ROD' function will only get the +echo a+ part that will run just |
| fine. |
| |
| [source,sh] |
| ------------------------------------------------------------------------------- |
| # Redirect output to a file with ROD |
| ROD echo foo \> bar |
| ------------------------------------------------------------------------------- |
| |
| Note the '>' is escaped with '\', this causes that the '>' and filename are |
| passed to the 'ROD' function as parameters and the 'ROD' function contains |
| code to split '$@' on '>' and redirects the output to the file. |
| |
| EXPECT_PASS{,_BRK} and EXPECT_FAIL{,_BRK} |
| +++++++++++++++++++++++++++++++++++++++++ |
| |
| [source,sh] |
| ------------------------------------------------------------------------------- |
| EXPECT_PASS command arg1 arg2 ... [ \> file ] |
| EXPECT_FAIL command arg1 arg2 ... [ \> file ] |
| ------------------------------------------------------------------------------- |
| |
| 'EXPECT_PASS' calls 'tst_resm TPASS' if the command exited with 0 exit code, |
| and 'tst_resm TFAIL' otherwise. 'EXPECT_FAIL' does vice versa. |
| |
| Output redirection rules are the same as for the 'ROD' function. In addition |
| to that, 'EXPECT_FAIL' always redirects the command's stderr to '/dev/null'. |
| |
| There are also 'EXPECT_PASS_BRK' and 'EXPECT_FAIL_BRK', which works the same way |
| except breaking a test when unexpected action happen. |
| |
| It's possible to detect whether expected value happened: |
| [source,sh] |
| ------------------------------------------------------------------------------- |
| if ! EXPECT_PASS command arg1 2\> /dev/null; then |
| continue |
| fi |
| ------------------------------------------------------------------------------- |
| |
| tst_kvcmp |
| +++++++++ |
| |
| This command compares the currently running kernel version given conditions |
| with syntax similar to the shell test command. |
| |
| [source,sh] |
| ------------------------------------------------------------------------------- |
| # Exit the test if kernel version is older or equal to 2.6.8 |
| if tst_kvcmp -le 2.6.8; then |
| tst_brk TCONF "Kernel newer than 2.6.8 is needed" |
| fi |
| |
| # Exit the test if kernel is newer than 3.8 and older than 4.0.1 |
| if tst_kvcmp -gt 3.8 -a -lt 4.0.1; then |
| tst_brk TCONF "Kernel must be older than 3.8 or newer than 4.0.1" |
| fi |
| ------------------------------------------------------------------------------- |
| |
| [options="header"] |
| |======================================================================= |
| | expression | description |
| | -eq kver | Returns true if kernel version is equal |
| | -ne kver | Returns true if kernel version is not equal |
| | -gt kver | Returns true if kernel version is greater |
| | -ge kver | Returns true if kernel version is greater or equal |
| | -lt kver | Returns true if kernel version is lesser |
| | -le kver | Returns true if kernel version is lesser or equal |
| | -a | Does logical and between two expressions |
| | -o | Does logical or between two expressions |
| |======================================================================= |
| |
| The format for kernel version has to either be with one dot e.g. '2.6' or with |
| two dots e.g. '4.8.1'. |
| |
| .tst_fs_has_free |
| [source,sh] |
| ------------------------------------------------------------------------------- |
| #!/bin/sh |
| |
| ... |
| |
| # whether current directory has 100MB free space at least. |
| if ! tst_fs_has_free . 100MB; then |
| tst_brkm TCONF "Not enough free space" |
| fi |
| |
| ... |
| ------------------------------------------------------------------------------- |
| |
| The 'tst_fs_has_free' shell interface returns 0 if the specified free space is |
| satisfied, 1 if not, and 2 on error. |
| |
| The second argument supports suffixes kB, MB and GB, the default unit is Byte. |
| |
| .tst_retry |
| [source,sh] |
| ------------------------------------------------------------------------------- |
| #!/bin/sh |
| |
| ... |
| |
| # Retry ping command three times |
| tst_retry "ping -c 1 127.0.0.1" |
| |
| if [ $? -ne 0 ]; then |
| tst_resm TFAIL "Failed to ping 127.0.0.1" |
| else |
| tst_resm TPASS "Successfully pinged 127.0.0.1" |
| fi |
| |
| ... |
| ------------------------------------------------------------------------------- |
| |
| The 'tst_retry' function allows you to retry a command after waiting small |
| amount of time until it succeeds or until given amount of retries has been |
| reached (default is three attempts). |
| |
| 2.3.5 Restarting daemons |
| ^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| Restarting system daemons is a complicated task for two reasons. |
| |
| * There are different init systems |
| (SysV init, systemd, etc...) |
| |
| * Daemon names are not unified between distributions |
| (apache vs httpd, cron vs crond, various syslog variations) |
| |
| To solve these problems LTP has 'testcases/lib/daemonlib.sh' library that |
| provides functions to start/stop/query daemons as well as variables that store |
| correct daemon name. |
| |
| .Supported operations |
| |============================================================================== |
| | start_daemon() | Starts daemon, name is passed as first parameter. |
| | stop_daemon() | Stops daemon, name is passed as first parameter. |
| | restart_daemon() | Restarts daemon, name is passed as first parameter. |
| | status_daemon() | Detect daemon status (exit code: 0: running, 1: not running). |
| |============================================================================== |
| |
| .Variables with detected names |
| |============================================================================== |
| | CROND_DAEMON | Cron daemon name (cron, crond). |
| | SYSLOG_DAEMON | Syslog daemon name (syslog, syslog-ng, rsyslog). |
| |============================================================================== |
| |
| .Cron daemon restart example |
| [source,sh] |
| ------------------------------------------------------------------------------- |
| #!/bin/sh |
| # SPDX-License-Identifier: GPL-2.0-or-later |
| # Cron daemon restart example |
| |
| TCID=cron01 |
| TST_COUNT=1 |
| . test.sh |
| . daemonlib.sh |
| |
| ... |
| |
| restart_daemon $CROND_DAEMON |
| |
| ... |
| |
| tst_exit |
| ------------------------------------------------------------------------------- |
| |
| 2.3.6 Access to the checkpoint interface |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| The shell library provides an implementation of the checkpoint interface |
| compatible with the C version. All 'TST_CHECKPOINT_*' functions are available. |
| |
| In order to initialize checkpoints '$TST_NEEDS_CHECKPOINTS' must be set to '1' |
| before the inclusion of 'test.sh': |
| |
| [source,sh] |
| ------------------------------------------------------------------------------- |
| #!/bin/sh |
| |
| TST_NEEDS_CHECKPOINTS=1 |
| . test.sh |
| ------------------------------------------------------------------------------- |
| |
| Since both the implementations are compatible, it's also possible to start |
| a child binary process from a shell test and synchronize with it. This process |
| must have checkpoints initialized by calling 'tst_reinit()'. |
| |
| 3. Common problems |
| ------------------ |
| |
| This chapter describes common problems/misuses and less obvious design patters |
| (quirks) in UNIX interfaces. Read it carefully :) |
| |
| 3.1 umask() |
| ~~~~~~~~~~~ |
| |
| I've been hit by this one several times already... When you create files |
| with 'open()' or 'creat()' etc, the mode specified as the last parameter *is |
| not* the mode the file is created with. The mode depends on current 'umask()' |
| settings which may clear some of the bits. If your test depends on specific |
| file permissions you need either to change umask to 0 or 'chmod()' the file |
| afterwards or use 'SAFE_TOUCH()' that does the 'chmod()' for you. |
| |
| 3.2 access() |
| ~~~~~~~~~~~ |
| |
| If 'access(some_file, W_OK)' is executed by root, it will return success even |
| if the file doesn't have write permission bits set (the same holds for R_OK |
| too). For sysfs files you can use 'open()' as a workaround to check file |
| read/write permissions. It might not work for other filesystems, for these you |
| have to use 'stat()', 'lstat()' or 'fstat()'. |
| |
| 3.3 umount() EBUSY |
| ~~~~~~~~~~~~~~~~~~ |
| |
| Various desktop daemons (gvfsd-trash is known for that) may be stupid enough |
| to probe all newly mounted filesystem which results in 'umount(2)' failing |
| with 'EBUSY'; use 'tst_umount()' described in 2.2.19 that retries in this case |
| instead of plain 'umount(2)'. |
| |
| 3.4 FILE buffers and fork() |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| Be vary that if a process calls 'fork(2)' the child process inherits open |
| descriptors as well as copy of the parent memory so especially if there are |
| any open 'FILE' buffers with a data in them they may be written both by the |
| parent and children resulting in corrupted/duplicated data in the resulting |
| files. |
| |
| Also open 'FILE' streams are flushed and closed at 'exit(3)' so if your |
| program works with 'FILE' streams, does 'fork(2)', and the child may end up |
| calling 'exit(3)' you will likely end up with corrupted files. |
| |
| The solution to this problem is either simply call 'fflush(NULL)' that flushes |
| all open output 'FILE' streams just before doing 'fork(2)'. You may also use |
| '_exit(2)' in child processes which does not flush 'FILE' buffers and also |
| skips 'atexit(3)' callbacks. |
| |
| 4. Test Contribution Checklist |
| ------------------------------ |
| |
| 1. Test compiles and runs fine (check with -i 10 too) |
| 2. Checkpatch does not report any errors |
| 3. The runtest entires are in place |
| 4. Test files are added into corresponding .gitignore files |
| 5. Patches apply over the latest git |
| |
| |
| 4.1 About .gitignore files |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| There are numerous '.gitignore' files in the LTP tree. Usually there is a |
| '.gitignore' file per a group of tests. The reason for this setup is simple. |
| It's easier to maintain a '.gitignore' file per directory with tests, rather |
| than having single file in the project root directory. This way, we don't have |
| to update all the gitignore files when moving directories, and they get deleted |
| automatically when a directory with tests is removed. |