LTP C API

Core LTP API

enum tst_res_flags

enum tst_res_flags: Test result reporting flags.

Definition

enum tst_res_flags {
    TPASS,
    TFAIL,
    TBROK,
    TWARN,
    TDEBUG,
    TINFO,
    TCONF,
    TERRNO,
    TTERRNO,
    TRERRNO
};

Constants

TPASS: Reports a single success. Successes increment passed counter and show up in the test results.
TFAIL: Reports a single failure. Failures increment failure counter and show up in the test results. A failure occurs when test assertion is broken.
TBROK: Reports a single breakage. Breakages increment breakage counter and show up in the test results. Breakages are reported in cases where a test couldn’t be executed due to an unexpected failure during the test setup. The TBROK status is mostly used with tst_brk() which exit the test immediately. The difference between TBROK and TCONF is that TCONF is used in cases where optional functionality is missing while TBROK is used in cases where something that is supposed to work is broken unexpectedly.
TWARN: Reports a single warning. Warnings increment a warning counter and show up in test results. Warnings are somewhere in the middle between TBROK and TCONF. Warnings usually appear when something that is supposed to be working is broken but the test can somehow continue.
TDEBUG: Prints additional debugging messages, it does not change the test result counters and the message is not displayed unless debugging is enabled with -D test command line parameter.
TINFO: Prints an additional information, it does not change the test result counters but unlike TDEBUG the message is always displayed.
TCONF: Reports unsupported configuration. When tests produce this result at least a subset of test was skipped, because it couldn’t run. The usual reasons are, missing kernel modules or CONFIG options. Unsuitable CPU architecture, not enough memory, etc.
TERRNO: Combine bitwise with result flags to append errno to the output message.
TTERRNO: Combine bitwise with result flags to append error from TST_ERR to the message. The TST_*() test macros store the errno into the TST_ERR global variable in order to make sure it’s not change between the test is done and results are printed.
TRERRNO: Combine bitwise with result flags to errno from TST_RET variable to the message. The TST_*() test macros store return value into the TST_RET global variable and quite a few, e.g. pthread functions, return the error value directly instead of storing it to the errno.

Description

A result flag with optional bitwise combination of errno flag are passed to the tst_res() and tst_brk() functions. Each message counts as a single test result and tests can produce arbitrary number of results, i.e. TPASS, TFAIL, TBROK, TWARN and TCONF messages. Each such message increases a result counter in a piece of shared memory, which means that reported results are accounted immediately even from child processes and there is no need for result propagation.

macro tst_res

tst_res(ttype, arg_fmt, ...)

Reports a test result.

Parameters:

ttype – An enum tst_res_flags.
arg_fmt – A printf-like format.
ellipsis (ellipsis) – A printf-like parameters.

Description

This is the main test reporting function. Each time this function is called with one of TPASS, TFAIL, TCONF, TBROK or TWARN a counter in page of shared memory is incremented. This means that there is no need to propagate test results from children and that results are accounted for once this function returns. The counters are incremented atomically which makes this function thread-safe.

macro tst_res_hexd

tst_res_hexd(ttype, buf, size, arg_fmt, ...)

Reports a test result along with hex dump of a buffer.

Parameters:

ttype – An enum tst_res_flags.
buf – A pointer to a buffer to print in hexadecimal format.
size – A size of the buffer.
arg_fmt – A printf-like format.
ellipsis (ellipsis) – A printf-like parameters.

Description

This call is the same as tst_res() but includes a pointer and size of the buffer that is going to be printed in the output in a hexadecimal format.

macro tst_brk

tst_brk(ttype, arg_fmt, ...)

Reports a breakage and exits the test or test process.

Parameters:

ttype – An enum tst_res_flags.
arg_fmt – A printf-like format.
ellipsis (ellipsis) – A printf-like parameters.

Description

Reports a single result and exits immediately. The call behaves differently based on the ttype parameter. For all ttype results but TBROK the call exits the current test process, i.e. increments test result counters and calls exit(0).

The TBROK ttype is special that apart from exiting the current test process it also tells to the test library to exit immediately. When TBROK is triggered by any of the test processes the whole process group is killed so that there are no processes left after the library process exits. This also means that any subsequent test iterations are not executed, e.g. if a test runs for all filesystems and tst_brk() with TBROK is called, the test exits and does not attempt to continue a test iteration for the next filesystem.

When test is in cleanup() function TBROK is converted into TWARN by the test library and we attempt to carry on with a cleanup even when tst_brk() was called. This makes it possible to use SAFE_FOO() macros in the test cleanup without interrupting the cleanup process on a failure.

tst_flush

void tst_flush(void)

Flushes the output file streams.

Parameters:

void – no arguments

Description

There are rare cases when we want to flush the output file streams explicitly, e.g. before we do an action that may crash the test to ensure that the messages have been written out.

This is also called by the SAFE_FORK() because otherwise each child would end up with the same copy of the file in it’s memory and any messages in buffers would be multiplied.

macro SAFE_FORK

SAFE_FORK(void)

Forks a test child.

Parameters:

void – no arguments

Description

This call makes sure that output file streams are flushed and also handles errors from fork(). Use this instead of fork() whenever possible!

tst_strerrno

const char *tst_strerrno(int err)

Converts an errno number into a name.

Parameters:

err (int) – An errno number.

Return

An errno name e.g. “EINVAL”.

tst_strsig

const char *tst_strsig(int sig)

Converts a signal number into a name.

Parameters:

sig (int) – A signal number.

Return

A signal name e.g. “SIGINT”.

tst_strstatus

const char *tst_strstatus(int status)

Returns string describing status as returned by wait().

Parameters:

status (int) – A status as returned by wait()

Description

Warning

Not thread safe.

Return

A string description for the status e.g. “killed by SIGKILL”.

tst_reap_children

void tst_reap_children(void)

Waits for all child processes to exit.

Parameters:

void – no arguments

Description

Wait for all children and exit with TBROK if any of them returned a non-zero exit status.

struct tst_option

struct tst_option: Test command line option.

Definition

struct tst_option {
    char *optstr;
    char **arg;
    char *help;
}

Members

optstr: A short command line option, e.g. “a” or “a:”.
arg: A pointer to store the option value to.
help: A help string for the option displayed when test is passed ‘-h’ on the command-line.

struct tst_tag

struct tst_tag: A test tag.

Definition

struct tst_tag {
    const char *name;
    const char *value;
}

Members

name: A tag name.
value: A tag value.

Description

This structure is used to encode pointers to upstream commits in regression tests as well as CVE numbers or any additional useful hints.

The content of these tags is printed by the test on a failure to help the testers with debugging.

The supported tags are

“linux-git” with first 12 numbers from an upstream kernel git hash.
“CVE” with a CVE number e.g. “2000-1234”.
“glibc-git” with first 12 numbers from an upstream glibc git hash.
“musl-git” with first 12 numbers from an upstream musl git hash.
“known-fail” a message describing something that is supposed to work but rather than that produces a longstanding failures.

struct tst_ulimit_val

struct tst_ulimit_val: An ulimit resource and value.

Definition

struct tst_ulimit_val {
    int resource;
    rlim_t rlim_cur;
}

Members

resource: Which resource limits should be adjusted. See setrlimit(2) for the list of the RLIMIT_* constants.
rlim_cur: A limit value.

struct tst_fs

struct tst_fs: A file system type, mkfs and mount options

Definition

struct tst_fs {
    const char *type;
    const char *const *mkfs_opts;
    const char *mkfs_size_opt;
    const char *mkfs_ver;
    unsigned int mnt_flags;
    const void *mnt_data;
    const char *min_kver;
}

Members

type: A filesystem type to use.
mkfs_opts: A NULL terminated array of options passed to mkfs in the case of ‘tst_test.format_device’. These options are passed to mkfs before the device path.
mkfs_size_opt: An option passed to mkfs in the case of ‘tst_test.format_device’. The device size in blocks is passed to mkfs after the device path and can be used to limit the file system not to use the whole block device.
mkfs_ver: mkfs tool version. The string format supports relational operators such as < > <= >= ==.
mnt_flags: MS_* flags passed to mount(2) when the test library * mounts a device in the case of ‘tst_test.mount_device’.
mnt_data: The data passed to mount(2) when the test library mounts a device in the case of ‘tst_test.mount_device’.
min_kver: A minimum kernel version supporting the filesystem which has been created with mkfs.

struct tst_test

struct tst_test: A test description.

Definition

struct tst_test {
    unsigned int tcnt;
    struct tst_option *options;
    const char *min_kver;
    const char *const *supported_archs;
    const char *tconf_msg;
    unsigned int needs_tmpdir:1;
    unsigned int needs_root:1;
    unsigned int forks_child:1;
    unsigned int needs_device:1;
    unsigned int needs_checkpoints:1;
    unsigned int needs_overlay:1;
    unsigned int format_device:1;
    unsigned int mount_device:1;
    unsigned int needs_rofs:1;
    unsigned int child_needs_reinit:1;
    unsigned int runs_script:1;
    unsigned int needs_devfs:1;
    unsigned int restore_wallclock:1;
    unsigned int all_filesystems:1;
    unsigned int skip_in_lockdown:1;
    unsigned int skip_in_secureboot:1;
    unsigned int skip_in_compat:1;
    int needs_abi_bits;
    unsigned int needs_hugetlbfs:1;
    const char *const *skip_filesystems;
    unsigned long min_cpus;
    unsigned long min_mem_avail;
    unsigned long min_swap_avail;
    struct tst_hugepage hugepages;
    unsigned int taint_check;
    unsigned int test_variants;
    unsigned int dev_min_size;
    struct tst_fs *filesystems;
    const char *mntpoint;
    int timeout;
    int runtime;
    int min_runtime;
    void (*setup)(void);
    void (*cleanup)(void);
    void (*test)(unsigned int test_nr);
    void (*test_all)(void);
    const char *scall;
    int (*sample)(int clk_id, long long usec);
    const char *const *resource_files;
    const struct tst_path_val *save_restore;
    const struct tst_ulimit_val *ulimit;
    const char *const *needs_kconfigs;
    struct tst_buffers *bufs;
    struct tst_cap *caps;
    const struct tst_tag *tags;
    struct tst_cmd *needs_cmds;
    const enum tst_cg_ver needs_cgroup_ver;
    const char *const *needs_cgroup_ctrls;
    unsigned int needs_cgroup_nsdelegate:1;
}

Members

tcnt: A number of tests. If set the test() callback is called tcnt times and each time passed an increasing counter value.
options: An NULL optstr terminated array of struct tst_option.
min_kver: A minimal kernel version the test can run on. e.g. “3.10”.
supported_archs: A NULL terminated array of architectures the test runs on e.g. {“x86_64, “x86”, NULL}. Calls tst_is_on_arch() to check if current CPU architecture is supported and exits the test with TCONF if it’s not.
tconf_msg: If set the test exits with TCONF right after entering the test library. This is used by the TST_TEST_TCONF() macro to disable tests at compile time.
needs_tmpdir: If set a temporary directory is prepared for the test inside $TMPDIR and the test $CWD is set to point to it. The content of the temporary directory is removed automatically after the test is finished.
needs_root: If set the test exit with TCONF unless it’s executed under root user.
forks_child: Has to be set if the test intends to fork children.
needs_device: If set a block device is prepared for the test, the device path and size are set in the struct tst_device variable called tst_device. If $LTP_DEV variable exists in the test environment the test attempts to use that device first and only if that fails the test falls back to use loop devices. This flag implies needs_tmpdir flag because loop device backing files are created in the test temporary directory.
needs_checkpoints: Has to be set if the test wants to use checkpoint synchronization primitives.
needs_overlay: If set overlay file system is mounted on the top of the file system at tst_test.mntpoint.
format_device: Does all tst_test.needs_device would do and also formats the device with a file system as well.
mount_device: Does all tst_test.format_device would do and also mounts the device at tst_test.mntpoint.
needs_rofs: If set a read-only file system is mounted at tst_test.mntpoint.
child_needs_reinit: Has to be set if the test needs to call tst_reinit() from a process started by exec().
runs_script: Implies child_needs_reinit and forks_child at the moment.
needs_devfs: If set the devfs is mounted at tst_test.mntpoint. This is needed for tests that need to create device files since tmpfs at /tmp is usually mounted with ‘nodev’ option.
restore_wallclock: Saves wall clock at the start of the test and restores it at the end with the help of monotonic timers. Testcases that modify system wallclock use this to restore the system to the previous state.
all_filesystems: If set the test is executed for all supported filesystems, i.e. file system that is supported by the kernel and has mkfs installed on the system.The file system is mounted at tst_test.mntpoint and file system details, e.g. type are set in the struct tst_device. Each execution is independent, that means that for each iteration tst_test.setup() is called at the test start and tst_test.cleanup() is called at the end and tst_brk() only exits test for a single file system. That especially means that calling tst_brk(TCONF, …) in the test setup will skip the current file system.
skip_in_lockdown: Skip the test if kernel lockdown is enabled.
skip_in_secureboot: Skip the test if secureboot is enabled.
skip_in_compat: Skip the test if we are executing 32bit binary on a 64bit kernel, i.e. we are testing the kernel compat layer.
needs_abi_bits: Skip the test if runs on a different kernel ABI than requested (on 32bit instead of 64bit or vice versa). Possible values: 32, 64.
needs_hugetlbfs: If set hugetlbfs is mounted at tst_test.mntpoint.
skip_filesystems: A NULL terminated array of unsupported file systems. The test reports TCONF if the file system to be tested is present in the array. This is especially useful to filter out unsupported file system when tst_test.all_filesystems is enabled.
min_cpus: Minimal number of online CPUs the test needs to run.
min_mem_avail: Minimal amount of available RAM memory in megabytes required for the test to run.
min_swap_avail: Minimal amount of available swap memory in megabytes required for the test to run.
hugepages: An interface to reserve hugepages prior running the test. Request how many hugepages should be reserved in the global pool and also if having hugepages is required for the test run or not, i.e. if test should exit with TCONF if the requested amount of hugepages cannot be reserved. If TST_REQUEST is set the library will try it’s best to reserve the hugepages and return the number of available hugepages in tst_hugepages, which may be 0 if there is no free memory or hugepages are not supported at all. If TST_NEEDS the requested hugepages are required for the test and the test exits if it couldn’t be required. It can also be used to disable hugepages by setting .hugepages = {TST_NO_HUGEPAGES}. The test library restores the original poll allocations after the test has finished.
taint_check: If set the test fails if kernel is tainted during the test run. That means tst_taint_init() is called during the test setup and tst_taint_check() at the end of the test. If all_filesystems is set taint check will be performed after each iteration and testing will be terminated by TBROK if taint is detected.
test_variants: If set denotes number of test variant, the test is executed variants times each time with tst_variant set to different number. This allows us to run the same test for different settings. The intended use is to test different syscall wrappers/variants but the API is generic and does not limit usage in any way.
dev_min_size: A minimal device size in megabytes.
filesystems: A NULL type terminated array of per file system type parameters for mkfs and mount. If the first entry type is NULL it describes a default parameters for all file system tests. The rest of the entries the describes per file system type parameters. If tst_test.all_filesystems is set, the test runs for all filesystems and uses the array to lookup the mkfs and mount options. If tst_test.all_filesystems is not set the test iterates over file system types defined in the array. If there is only a single entry in the array with a NULL type, the test runs just once for the default file system i.e. $TST_FS_TYPE.
mntpoint: A mount point where the test library mounts requested file system. The directory is created by the library, the test must not create it itself.
timeout: Maximum allowable time in seconds for the entire duration of a test. By default, the timeout limits the total time for setup, single test function invocation, and cleanup phases. However, if .runtime is explicitly set and tst_remaining_runtime() is used in the test’s main loop, the timeout then applies only to the setup and cleanup phases, as the runtime separately limits the main test execution. This ensures the test does not hang indefinitely, in the rare case that the test timeout cannot be accurately determined, it can be set to a sufficiently large value or TST_UNLIMITED_TIMEOUT to remove the limit.
runtime: Maximum runtime in seconds for the test’s main execution loop. This should be set for tests that are expected to run longer than a few seconds and call tst_remaining_runtime() in their main loop to exit gracefully when the runtime is exceeded. Tests may finish sooner if their task completes (e.g., reaching a requested number of iterations) before the runtime runs out. The runtime is fixed and does not scale with timeout multipliers (e.g., TIMEOUT_MUL), ensuring consistent test duration across different environments (e.g., debug vs. stock kernels).
min_runtime: Optional lower bound (in seconds) applied after runtime is scaled by LTP_RUNTIME_MUL. If the scaled runtime is smaller than this value, it will be clamped up to min_runtime. This is useful for tests that require a minimum execution time to gather sufficient samples or trigger events (e.g., probabilistic or fuzzy synchronization tests). If not set, a default minimum of 1 second is enforced.
setup: Setup callback is called once at the start of the test in order to prepare the test environment.
cleanup: Cleanup callback is either called at the end of the test, or in a case that tst_brk() was called. That means that cleanup must be able to handle all possible states the test can be in. This usually means that we have to check if file descriptor was opened before we attempt to close it, etc.
test: A main test function, only one of the tst_test.test and test_all can be set. When this function is set the tst_test.tcnt must be set to a positive integer and this function will be executed tcnt times during a single test iteration. May be executed several times if test was passed ‘-i’ or ‘-d’ command line parameters.
test_all: A main test function, only one of the tst_test.test and test_all can be set. May be executed several times if test was passed ‘-i’ or ‘-d’ command line parameters.
scall: Internal only (timer measurement library).
sample: Internal only (timer measurement library).
resource_files: A NULL terminated array of filenames that will be copied to the test temporary directory from the LTP datafiles directory.
save_restore: A {} terminated array of /proc or /sys files that should saved at the start of the test and restored at the end. See tst_sys_conf_save() and struct tst_path_val for details.
ulimit: A {} terminated array of process limits RLIMIT_* to be adjusted for the test.
needs_kconfigs: A NULL terminated array of kernel config options that are required for the test. All strings in the array have to be evaluated to true for the test to run. Boolean operators and parenthesis are supported, e.g. “CONFIG_X86_INTEL_UMIP=y | CONFIG_X86_UIMP=y” is evaluated to true if at least one of the options is present. A presence of a config option in the config file does not guarantee that the corresponding functionality is available. For instance, an option might be set to ‘m’ without the module being installed, or the feature could be disabled via the kernel command line. To address this, the kconfig library implements supplementary runtime checks for specific options required by the tests.
bufs: A description of guarded buffers to be allocated for the test. Guarded buffers are buffers with poisoned page allocated right before the start of the buffer and canary right after the end of the buffer. See struct tst_buffers and tst_buffers_alloc() for details.
caps: A {} terminated array of capabilities to change before the start of the test. See struct tst_cap and tst_cap_setup() for details.
tags: A {} terminated array of test tags. See struct tst_tag for details.
needs_cmds: A NULL terminated array of struct tst_cmd required for the test to run.
needs_cgroup_ver: If set the test will run only if the specified cgroup version is present on the system.
needs_cgroup_ctrls: A {} terminated array of cgroup controllers the test needs to run.
needs_cgroup_nsdelegate: If set test the will run only if cgroup2 is mounted with nsdelegate option.

tst_run_tcases

void tst_run_tcases(int argc, char *argv, struct tst_test *self)

Entry point to the test library.

Parameters:

argc (int) – An argc that was passed to the main().
argv (char*) – An argv that was passed to the main().
self (struct tst_test*) – The test description and callbacks packed in the struct tst_test structure.

Description

A main() function which calls this function is added to each test automatically by including the tst_test.h header. The test has to define the struct tst_test called test.

This function does not return, i.e. calls exit() after the test has finished.

tst_reinit

void tst_reinit(void)

Reinitialize the test library.

Parameters:

void – no arguments

Description

In a cases where a test child process calls exec() it no longer can access the test library shared memory and therefore use the test reporting functions, checkpoint library, etc. This function re-initializes the test library so that it can be used again.

Warning

The LTP_IPC_PATH environment variable must be passed to the program environment.

tst_run_script

int tst_run_script(const char *script_name, char *const params)

Prepare the environment and execute a (shell) script.

Parameters:

script_name (const char*) – A filename of the script.
params (char *const) – A NULL terminated array of (shell) script parameters, pass NULL if none are needed. This what is passed starting from argv[1].

Description

The (shell) script is executed with LTP_IPC_PATH in environment so that the binary helpers such as tst_res or tst_checkpoint work properly when executed from the script. This also means that the tst_test.runs_script flag needs to be set.

A shell script has to source the tst_env.sh shell script at the start and after that it’s free to use tst_res in the same way C code would use.

Example shell script that reports success:

#!/bin/sh
. tst_env.sh

tst_res TPASS "Example test works"

The call returns a pid in a case that you want to examine the return value of the script yourself. If you do not need to check the return value yourself you can use tst_reap_children() to wait for the completion. Or let the test library collect the child automatically, just be wary that the script and the test both runs concurently at the same time in this case.

Return

A pid of the (shell) script process.

tst_set_timeout

void tst_set_timeout(int timeout)

Sets the timeout for single test iteration.

Parameters:

timeout (int) – A timeout for a single iteration of the test in seconds.

Description

Allows to set timeout dynamically during the test setup.

This is used only for rare cases that the test does something that runs for a long time and cannot be easily interrupted (otherwise it would set .runtime and exit when runtime was exhausted).

The timeout is multiplied by tst_multiply_timeout() internally in the test library.

tst_multiply_timeout

unsigned int tst_multiply_timeout(unsigned int timeout)

Uses heuristics to multiply a time interval based on expected CPU slowdowns.

Parameters:

timeout (unsigned int) – A timeout.

Description

If a machine is expected to be slow for some reason, e.g. if we run on an emulated CPU, a user can export LTP_TIMEOUT_MUL variable that is used by this call to multiply the interval.

Various kernel configuration (debugging) options that slow down the machine are detected automatically and are taken into account.

This function is used internally in the test library to multiply various timeouts to make sure that they match the expected slowdown.

Return

A timeout multiplied by an expected slowdown coefficient.

tst_remaining_runtime

unsigned int tst_remaining_runtime(void)

Returns the remaining test runtime.

Parameters:

void – no arguments

Description

The function returns remaining runtime in seconds. If runtime was used up zero is returned.

Test that runs for more than a few seconds should check if they should exit by calling this function regularly.

Return

A remaining test runtime in seconds.

tst_set_runtime

void tst_set_runtime(int runtime)

Sets maximal test runtime in seconds.

Parameters:

runtime (int) – A timeout in seconds.

Description

Allows for setting the runtime per test iteration dynamically during the test setup phase. The runtime is specified in seconds and defines how long the test is allowed to execute its main workload, excluding the setup and teardown phases.

This function is useful for tests where the duration of the main workload can be controlled or needs to be adjusted dynamically. For example, tests that run in a loop until the runtime expires can use this function to define how long they should execute.

A test that sets a runtime must monitor the remaining time with tst_remaining_runtime() in the main loop.

tst_creat_unlinked

int tst_creat_unlinked(const char *path, int flags, mode_t mode)

Create, open, and unlink a file.

Parameters:

path (const char*) – Path to the directory.
flags (int) – open(2) flags.
mode (mode_t) – open(2) mode.

Description

Creates and opens a unique file name inside the given directory path, unlinks the file after opening and returns a file descriptor.

Return

A file descriptor.

tst_get_tmpdir_root

const char *tst_get_tmpdir_root(void)

Returns path to the test temporary directory root.

Parameters:

void – no arguments

Description

The path is either hardcoded as /tmp or could be overrided by a TMPDIR environment variable.

Return

A path to the test temporary directory root.

tst_cmd_present

bool tst_cmd_present(const char *cmd)

Check if a command is present

Parameters:

cmd (const char*) – The name of the command to check for.

Description

This function iterates through the tst_test->needs_cmds array. It compares the given command name with each entry in the array and returns the tst_cmd->present flag for the matching command.

Return

true if the command is present, false otherwise.

macro tst_validate_children

tst_validate_children(count)

Validates exit status of the child processes.

Parameters:

count – Number of the child processes.

macro TST_TEST_TCONF

TST_TEST_TCONF(message)

Exit tests with a TCONF message.

Parameters:

message – Error message (the reason to skip test).

Description

This macro is used in test that couldn’t be compiled either because current CPU architecture is unsupported or because of missing development libraries.

Test macros

tst_test_macros.h – helpers for testing syscalls

macro TEST

TEST(SCALL)

Store syscall retval long and errno.

Parameters:

SCALL – Tested syscall e.g. write(fd, buf, len).

Description

This macro is a shortcut for storing an errno and a return value. The errno is cleared before the syscall is called and saved to a TST_ERR global variable right after the call returns. The return value is available in TST_RET global variable.

The TST_ERR and TST_RET can be included into tst_res() messages with the TST_ERR and TTERRNO and TRERRNO flags.

This macro is also used as a base for all the more specific variants e.g. TST_EXP_FAIL().

macro TESTPTR

TESTPTR(SCALL)

Store syscall retval pointer and errno.

Parameters:

SCALL – Tested syscall e.g. write(fd, buf, len).

Description

Sets TST_RET_PTR and TST_ERR.

This is the same as TEST() macro the only difference is that the return value is a pointer which is stored into TST_RET_PTR instead.

macro TST_EXP_POSITIVE

TST_EXP_POSITIVE(SCALL, ...)

Test syscall, expect return value >= 0.

Parameters:

SCALL – Tested syscall.
ellipsis (ellipsis) – A printf-like parameters.

Description

This macro calls the SCALL with a TEST() macro and additionaly prints pass or fail message. Apart from TST_ERR and TST_RET set by the TEST() macro TST_PASS global variable is set as well based on the outcome.

The printf-like parameters can be optionally used to pass a description printed by the pass or fail tst_res() calls. If omitted the first parameter is converted to a string and used instead.

macro TST_EXP_FD_SILENT

TST_EXP_FD_SILENT(SCALL, ...)

Test syscall to return a file descriptor, silent variant.

Parameters:

SCALL – Tested syscall.
ellipsis (ellipsis) – A printf-like parameters.

Description

Unlike TST_EXP_FD() does not print TPASS on success, only prints TFAIL on failure.

macro TST_EXP_FD

TST_EXP_FD(SCALL, ...)

Test syscall to return a file descriptor.

Parameters:

SCALL – Tested syscall.
ellipsis (ellipsis) – A printf-like parameters.

Description

This is a variant of the TST_EXP_POSSITIVE() for a more specific case that the returned value is a file descriptor.

macro TST_EXP_FD_OR_FAIL

TST_EXP_FD_OR_FAIL(SCALL, ERRNO, ...)

Test syscall to return file descriptor or fail with expected errno.

Parameters:

SCALL – Tested syscall.
ERRNO – Expected errno or 0.
ellipsis (ellipsis) – A printf-like parameters.

Description

Expect a file descriptor if errno is 0 otherwise expect a failure with expected errno.

Internally it uses TST_EXP_FAIL() and TST_EXP_FD().

macro TST_EXP_PID_SILENT

TST_EXP_PID_SILENT(SCALL, ...)

Test syscall to return PID, silent variant.

Parameters:

SCALL – Tested syscall.
ellipsis (ellipsis) – A printf-like parameters.

Description

Unlike TST_EXP_PID() does not print TPASS on success, only prints TFAIL on failure.

macro TST_EXP_PID

TST_EXP_PID(SCALL, ...)

Test syscall to return PID.

Parameters:

SCALL – Tested syscall.
ellipsis (ellipsis) – A printf-like parameters.

Description

This is a variant of the TST_EXP_POSSITIVE() for a more specific case that the returned value is a pid.

macro TST_EXP_VAL_SILENT

TST_EXP_VAL_SILENT(SCALL, VAL, ...)

Test syscall to return specified value, silent variant.

Parameters:

SCALL – Tested syscall.
VAL – Expected return value.
ellipsis (ellipsis) – A printf-like parameters.

Description

Unlike TST_EXP_VAL() does not print TPASS on success, only prints TFAIL on failure.

macro TST_EXP_VAL

TST_EXP_VAL(SCALL, VAL, ...)

Test syscall to return specified value.

Parameters:

SCALL – Tested syscall.
VAL – Expected return value.
ellipsis (ellipsis) – A printf-like parameters.

Description

This macro calls the SCALL with a TEST() macro and additionaly prints pass or fail message after comparing the returned value againts the expected value. Apart from TST_ERR and TST_RET set by the TEST() macro TST_PASS global variable is set as well based on the outcome.

The printf-like parameters can be optionally used to pass a description printed by the pass or fail tst_res() calls. If omitted the first parameter is converted to a string and used instead.

macro TST_EXP_PASS_SILENT

TST_EXP_PASS_SILENT(SCALL, ...)

Test syscall to return 0, silent variant.

Parameters:

SCALL – Tested syscall.
ellipsis (ellipsis) – A printf-like parameters.

Description

Unlike TST_EXP_PASS() does not print TPASS on success, only prints TFAIL on failure.

macro TST_EXP_PASS

TST_EXP_PASS(SCALL, ...)

Test syscall to return 0.

Parameters:

SCALL – Tested syscall.
ellipsis (ellipsis) – A printf-like parameters.

Description

This macro calls the SCALL with a TEST() macro and additionaly prints pass or fail message after checking the return value againts zero. Apart from TST_ERR and TST_RET set by the TEST() macro TST_PASS global variable is set as well based on the outcome.

The printf-like parameters can be optionally used to pass a description printed by the pass or fail tst_res() calls. If omitted the first parameter is converted to a string and used instead.

macro TST_EXP_PASS_PTR_VOID

TST_EXP_PASS_PTR_VOID(SCALL, ...)

Test syscall to return a valid pointer.

Parameters:

SCALL – Tested syscall.
ellipsis (ellipsis) – A printf-like parameters.

Description

This macro calls the SCALL with a TESTPTR() macro and additionaly prints pass or fail message after checking the return value against (void *)-1. Apart from TST_ERR and TST_RET_PTR set by the TESTPTR() macro TST_PASS global variable is set as well based on the outcome.

The printf-like parameters can be optionally used to pass a description printed by the pass or fail tst_res() calls. If omitted the first parameter is converted to a string and used instead.

macro TST_EXP_PASS_PTR_NULL

TST_EXP_PASS_PTR_NULL(SCALL, ...)

Test call to return a non-NULL pointer.

Parameters:

SCALL – Tested call.
ellipsis (ellipsis) – A printf-like parameters.

Description

This macro works like TST_EXP_PASS_PTR_VOID() but checks the return value against NULL instead of (void *)-1. Use this for libc functions such as fopen() that return NULL on failure.

macro TST_EXP_FAIL

TST_EXP_FAIL(SCALL, EXP_ERR, ...)

Test syscall to fail with expected errno.

Parameters:

SCALL – Tested syscall.
EXP_ERR – Expected errno.
ellipsis (ellipsis) – A printf-like parameters.

Description

This macro calls the SCALL with a TEST() macro and additionaly prints pass or fail message. The check passes if syscall has returned -1 and failed with the specified errno.

The SCALL is supposed to return zero on success. For syscalls that return positive number on success TST_EXP_FAIL2() has to be used instead.

Apart from TST_ERR and TST_RET set by the TEST() macro TST_PASS global variable is set as well based on the outcome.

The printf-like parameters can be optionally used to pass a description printed by the pass or fail tst_res() calls. If omitted the first parameter is converted to a string and used instead.

macro TST_EXP_FAIL_ARR

TST_EXP_FAIL_ARR(SCALL, EXP_ERRS, EXP_ERRS_CNT, ...)

Test syscall to fail with expected errnos.

Parameters:

SCALL – Tested syscall.
EXP_ERRS – Array of expected errnos.
EXP_ERRS_CNT – Lenght of EXP_ERRS.
ellipsis (ellipsis) – A printf-like parameters.

Description

This is a variant of TST_EXP_FAIL() with an array of possible errors.

macro TST_EXP_FAIL2_ARR

TST_EXP_FAIL2_ARR(SCALL, EXP_ERRS, EXP_ERRS_CNT, ...)

Test syscall to fail with expected errnos.

Parameters:

SCALL – Tested syscall.
EXP_ERRS – Array of expected errnos.
EXP_ERRS_CNT – Lenght of EXP_ERRS.
ellipsis (ellipsis) – A printf-like parameters.

Description

This is a variant of TST_EXP_FAIL2() with an array of possible errors.

macro TST_EXP_FAIL_PTR_NULL

TST_EXP_FAIL_PTR_NULL(SCALL, EXP_ERR, ...)

Test syscall to fail with expected errno and return a NULL pointer.

Parameters:

SCALL – Tested syscall.
EXP_ERR – Expected errno.
ellipsis (ellipsis) – A printf-like parameters.

Description

This macro calls the SCALL with a TESTPTR() macro and additionaly prints pass or fail message after checking the return value against NULL and errno.

Apart from TST_ERR and TST_RET_PTR set by the TESTPTR() macro TST_PASS global variable is set as well based on the outcome.

The printf-like parameters can be optionally used to pass a description printed by the pass or fail tst_res() calls. If omitted the first parameter is converted to a string and used instead.

macro TST_EXP_FAIL_PTR_NULL_ARR

TST_EXP_FAIL_PTR_NULL_ARR(SCALL, EXP_ERRS, EXP_ERRS_CNT, ...)

Test syscall to fail with expected errnos and return a NULL pointer.

Parameters:

SCALL – Tested syscall.
EXP_ERRS – Array of expected errnos.
EXP_ERRS_CNT – Lenght of EXP_ERRS.
ellipsis (ellipsis) – A printf-like parameters.

Description

This is a variant of TST_EXP_FAIL_PTR_NULL() with an array of possible errors.

macro TST_EXP_FAIL_PTR_VOID

TST_EXP_FAIL_PTR_VOID(SCALL, EXP_ERR, ...)

Test syscall to fail with expected errno and return a (void *)-1 pointer.

Parameters:

SCALL – Tested syscall.
EXP_ERR – Expected errno.
ellipsis (ellipsis) – A printf-like parameters.

Description

This macro calls the SCALL with a TESTPTR() macro and additionaly prints pass or fail message after checking the return value against (void *)-1 and errno.

Apart from TST_ERR and TST_RET_PTR set by the TESTPTR() macro TST_PASS global variable is set as well based on the outcome.

The printf-like parameters can be optionally used to pass a description printed by the pass or fail tst_res() calls. If omitted the first parameter is converted to a string and used instead.

macro TST_EXP_FAIL_PTR_VOID_ARR

TST_EXP_FAIL_PTR_VOID_ARR(SCALL, EXP_ERRS, EXP_ERRS_CNT, ...)

Test syscall to fail with expected errnos and return a (void *)-1 pointer.

Parameters:

SCALL – Tested syscall.
EXP_ERRS – Array of expected errnos.
EXP_ERRS_CNT – Lenght of EXP_ERRS.
ellipsis (ellipsis) – A printf-like parameters.

Description

This is a variant of TST_EXP_FAIL_PTR_VOID() with an array of possible errors.

macro TST_EXP_FAIL2

TST_EXP_FAIL2(SCALL, EXP_ERR, ...)

Test syscall to fail with expected errno.

Parameters:

SCALL – Tested syscall.
EXP_ERR – Expected errno.
ellipsis (ellipsis) – A printf-like parameters.

Description

This macro calls the SCALL with a TEST() macro and additionaly prints pass or fail message. The check passes if syscall has returned -1 and failed with the specified errno.

The SCALL is supposed to return possitive number on success e.g. pid or file descriptor. For syscalls that return zero on success TST_EXP_FAIL() has to be used instead.

Apart from TST_ERR and TST_RET set by the TEST() macro TST_PASS global variable is set as well based on the outcome.

The printf-like parameters can be optionally used to pass a description printed by the pass or fail tst_res() calls. If omitted the first parameter is converted to a string and used instead.

macro TST_EXP_FAIL_SILENT

TST_EXP_FAIL_SILENT(SCALL, EXP_ERR, ...)

Test syscall to fail with expected errno, silent variant.

Parameters:

SCALL – Tested syscall.
EXP_ERR – Expected errno.
ellipsis (ellipsis) – A printf-like parameters.

Description

Unlike TST_EXP_FAIL() does not print TPASS on success, only prints TFAIL on failure.

macro TST_EXP_FAIL2_SILENT

TST_EXP_FAIL2_SILENT(SCALL, EXP_ERR, ...)

Test syscall to fail with expected errno, silent variant.

Parameters:

SCALL – Tested syscall.
EXP_ERR – Expected errno.
ellipsis (ellipsis) – A printf-like parameters.

Description

Unlike TST_EXP_FAIL2() does not print TPASS on success, only prints TFAIL on failure.

macro TST_EXP_FAIL_ARR_SILENT

TST_EXP_FAIL_ARR_SILENT(SCALL, EXP_ERRS, EXP_ERRS_CNT, ...)

Test syscall to fail with expected errnos, silent variant.

Parameters:

SCALL – Tested syscall.
EXP_ERRS – Array of expected errnos.
EXP_ERRS_CNT – Lenght of EXP_ERRS.
ellipsis (ellipsis) – A printf-like parameters.

Description

Unlike TST_EXP_FAIL_ARR() does not print TPASS on success, only prints TFAIL on failure.

macro TST_EXP_FAIL2_ARR_SILENT

TST_EXP_FAIL2_ARR_SILENT(SCALL, EXP_ERRS, EXP_ERRS_CNT, ...)

Test syscall to fail with expected errnos, silent variant.

Parameters:

SCALL – Tested syscall.
EXP_ERRS – Array of expected errnos.
EXP_ERRS_CNT – Lenght of EXP_ERRS.
ellipsis (ellipsis) – A printf-like parameters.

Description

Unlike TST_EXP_FAIL2_ARR() does not print TPASS on success, only prints TFAIL on failure.

macro TST_EXP_EXPR

TST_EXP_EXPR(EXPR, ...)

Check for expected expression.

Parameters:

EXPR – Expression to be tested.
ellipsis (ellipsis) – A printf-like parameters.

Description

Reports a pass if expression evaluates to non-zero and a fail otherwise.

The printf-like parameters can be optionally used to pass a description printed by the pass or fail tst_res() calls. If omitted the expression is converted to a string and used instead.

macro TST_EXP_LE_LU

TST_EXP_LE_LU(VAL_A, VAL_B)

Compare two unsigned long long values, expect A <= B.

Parameters:

VAL_A – unsigned long long value A.
VAL_B – unsigned long long value B.

Description

Reports a pass if A <= B and a fail otherwise.

macro TST_EXP_LE_LU_SILENT

TST_EXP_LE_LU_SILENT(VAL_A, VAL_B)

Compare two unsigned long long values, silent variant.

Parameters:

VAL_A – unsigned long long value A.
VAL_B – unsigned long long value B.

Description

Unlike TST_EXP_LE_LU() does not print TPASS on success, only prints TFAIL on failure.

macro TST_EXP_EQ_LI

TST_EXP_EQ_LI(VAL_A, VAL_B)

Compare two long long values.

Parameters:

VAL_A – long long value A.
VAL_B – long long value B.

Description

Reports a pass if values are equal and a fail otherwise.

macro TST_EXP_EQ_LI_SILENT

TST_EXP_EQ_LI_SILENT(VAL_A, VAL_B)

Compare two long long values, silent variant.

Parameters:

VAL_A – long long value A.
VAL_B – long long value B.

Description

Unlike TST_EXP_EQ_LI() does not print TPASS on success, only prints TFAIL on failure.

macro TST_EXP_EQ_LU

TST_EXP_EQ_LU(VAL_A, VAL_B)

Compare two unsigned long long values.

Parameters:

VAL_A – unsigned long long value A.
VAL_B – unsigned long long value B.

Description

Reports a pass if values are equal and a fail otherwise.

macro TST_EXP_EQ_LU_SILENT

TST_EXP_EQ_LU_SILENT(VAL_A, VAL_B)

Compare two unsigned long long values, silent variant.

Parameters:

VAL_A – unsigned long long value A.
VAL_B – unsigned long long value B.

Description

Unlike TST_EXP_EQ_LU() does not print TPASS on success, only prints TFAIL on failure.

macro TST_EXP_EQ_SZ

TST_EXP_EQ_SZ(VAL_A, VAL_B)

Compare two unsigned size_t values.

Parameters:

VAL_A – unsigned long long value A.
VAL_B – unsigned long long value B.

Description

Reports a pass if values are equal and a fail otherwise.

macro TST_EXP_EQ_SZ_SILENT

TST_EXP_EQ_SZ_SILENT(VAL_A, VAL_B)

Compare two unsigned size_t values, silent variant.

Parameters:

VAL_A – unsigned long long value A.
VAL_B – unsigned long long value B.

Description

Unlike TST_EXP_EQ_SZ() does not print TPASS on success, only prints TFAIL on failure.

macro TST_EXP_EQ_SSZ

TST_EXP_EQ_SSZ(VAL_A, VAL_B)

Compare two unsigned ssize_t values.

Parameters:

VAL_A – unsigned long long value A.
VAL_B – unsigned long long value B.

Description

Reports a pass if values are equal and a fail otherwise.

macro TST_EXP_EQ_SSZ_SILENT

TST_EXP_EQ_SSZ_SILENT(VAL_A, VAL_B)

Compare two unsigned ssize_t values, silent variant.

Parameters:

VAL_A – unsigned long long value A.
VAL_B – unsigned long long value B.

Description

Unlike TST_EXP_EQ_SSZ() does not print TPASS on success, only prints TFAIL on failure.

macro TST_EXP_EQ_STR

TST_EXP_EQ_STR(STR_A, STR_B)

Compare two strings.

Parameters:

STR_A – string to compare.
STR_B – string to compare.

Description

Reports a pass if strings are equal and a fail otherwise.

macro TST_EXP_EQ_STRN

TST_EXP_EQ_STRN(STR_A, STR_B, LEN)

Compare two strings, providing length as well.

Parameters:

STR_A – string to compare.
STR_B – string to compare.
LEN – length of the string.

Description

Reports a pass if first LEN bytes of strings are equal and a fail otherwise.

Capabilities

Capabilities introduction

Limited capability operations without libcap.

enum tst_cap_act

enum tst_cap_act: A capability action masks.

Definition

enum tst_cap_act {
    TST_CAP_DROP,
    TST_CAP_REQ
};

Constants

TST_CAP_DROP: Drop capabilities.
TST_CAP_REQ: Add capabilities.

struct tst_cap_user_header

struct tst_cap_user_header: Kernel capget(), capset() syscall header.

Definition

struct tst_cap_user_header {
    uint32_t version;
    int pid;
}

Members

version: A capability API version.
pid: A process to operate on.

struct tst_cap_user_data

struct tst_cap_user_data: Kernel capset(), capget() syscall payload.

Definition

struct tst_cap_user_data {
    uint32_t effective;
    uint32_t permitted;
    uint32_t inheritable;
}

Members

effective: A capability effective set.
permitted: A capability permitted set.
inheritable: A capability inheritable set.

struct tst_cap

struct tst_cap: A capability to alter.

Definition

struct tst_cap {
    uint32_t action;
    uint32_t id;
    char *name;
}

Members

action: What should we do, i.e. drop or add a capability.
id: A capability id.
name: A capability name.

Description

This structure is usually constructed with the TST_CAP() macro so that the name is created automatically.

macro TST_CAP

TST_CAP(action, capability)

Create a struct tst_cap entry.

Parameters:

action – What should we do, i.e. drop or add capability.
capability – A capability id, e.g. CAP_BPF.

tst_capget

int tst_capget(struct tst_cap_user_header *hdr, struct tst_cap_user_data *data)

Get the capabilities as decided by hdr.

Parameters:

hdr (struct tst_cap_user_header*) – A capability user header stores a pid to operate on and which capability API version is used.
data (struct tst_cap_user_data*) – A memory to store the capabilities to. The memory pointed to by data should be large enough to store two structs.

Return

Returns 0 on success, -1 on a failure and sets errno.

tst_capset

int tst_capset(struct tst_cap_user_header *hdr, const struct tst_cap_user_data *data)

Set the capabilities as decided by hdr and data

Parameters:

hdr (struct tst_cap_user_header*) – A capability user header stores a pid to operate on and which capability API version is used.
data (const struct tst_cap_user_data*) – A memory to store the capabilities to. The memory pointed to by data should be large enough to store two structs.

Return

Returns 0 on success, -1 on a failure and sets errno.

tst_cap_action

void tst_cap_action(struct tst_cap *cap)

Add, check or remove a capability.

Parameters:

cap (struct tst_cap*) – An {} terminated array of capabilities to alter.

Description

It will attempt to drop or add capability to the effective set. It will try to detect if this is needed and whether it can or can’t be done. If it clearly can not add a privilege to the effective set then it will return TCONF. However it may fail for some other reason and return TBROK.

This only tries to change the effective set. Some tests may need to change the inheritable and ambient sets, so that child processes retain some capability.

tst_cap_setup

void tst_cap_setup(struct tst_cap *cap, enum tst_cap_act action_mask)

Add, check or remove a capabilities.

Parameters:

cap (struct tst_cap*) – An {} terminated array of capabilities to alter.
action_mask (enum tst_cap_act) – Decides which actions are done, i.e. only drop caps, add them or both.

Description

Takes a NULL terminated array of structs which describe whether some capabilities are needed or not and mask that determines subset of the actions to be performed. Loops over the array and if mask matches the element action it’s passed to tst_cap_action().

Checkpoints

Checkpoints introduction

Checkpoints implements a futex based synchronization primitive for threads and processes. When a process calls wait function its execution is suspended until wake is called for a corresponding checkpoint. Checkpoints are numbered from 0 and process can use at least hundred of them.

In order to use checkpoints the test must set the tst_test.needs_checkpoints flag.

macro TST_CHECKPOINT_WAIT

TST_CHECKPOINT_WAIT(id)

Waits for a checkpoint.

Parameters:

id – A checkpoint id a positive integer.

Description

Suspends thread/process execution until it’s woken up with a wake. The call does not wait indefinitely it gives up after 10 seconds. If an error happened or timeout was reached the function calls tst_brk(TBROK, …) which exits the test.

macro TST_CHECKPOINT_WAIT2

TST_CHECKPOINT_WAIT2(id, msec_timeout)

Waits for a checkpoint.

Parameters:

id – A checkpoint id a positive integer.
msec_timeout – A timeout.

Description

Suspends thread/process execution until it’s woken up with a wake. If an error happened or timeout was reached the function calls tst_brk(TBROK, …) which exits the test.

macro TST_CHECKPOINT_WAKE

TST_CHECKPOINT_WAKE(id)

Wakes up a checkpoint.

Parameters:

id – A checkpoint id a positive integer.

Description

Wakes up a process suspended on a checkpoint and retries if there is no process suspended on the checkpoint yet. The call does not retry indefinitely but gives up after 10 seconds. If an error happened or timeout was reached the function calls tst_brk(TBROK, …) which exits the test.

macro TST_CHECKPOINT_WAKE2

TST_CHECKPOINT_WAKE2(id, nr_wake)

Wakes up several checkpoints.

Parameters:

id – A checkpoint id a positive integer.
nr_wake – A number of processes to wake.

Description

Wakes up nr_wake processes suspended on a checkpoint and retries if there wasn’t enough process suspended on the checkpoint yet. The call does not retry indefinitely but gives up if it does not wake nr_wake processes after 10 seconds. If an error happened or timeout was reached the function calls tst_brk(TBROK, …) which exits the test.

macro TST_CHECKPOINT_WAKE_AND_WAIT

TST_CHECKPOINT_WAKE_AND_WAIT(id)

Wakes up a checkpoint and immediately waits on it.

Parameters:

id – A checkpoint id a positive integer.

Description

This is a combination of TST_CHECKPOINT_WAKE() and TST_CHECKPOINT_WAIT().

Commands

enum tst_cmd_flags

enum tst_cmd_flags: flags for tst_cmd() and tst_cmd_fds().

Definition

enum tst_cmd_flags {
    TST_CMD_PASS_RETVAL,
    TST_CMD_TCONF_ON_MISSING
};

Constants

TST_CMD_PASS_RETVAL: return the program exit code, otherwise it will call cleanup_fn() if the program exit code is not zero.
TST_CMD_TCONF_ON_MISSING: exit with TCONF if program is not in PATH.

struct tst_cmd

struct tst_cmd: Provides details about a command struct needed by LTP test.

Definition

struct tst_cmd {
    const char *cmd;
    unsigned int optional:1;
    unsigned int present:1;
}

Members

cmd: The name of the command.
optional: A flag indicating if the command is optional.
present: A flag indicating if the command was found at runtime. This is an output parameter, set by the LTP library during the test setup.

tst_cmd_fds

int tst_cmd_fds(const char *const argv, int stdout_fd, int stderr_fd, enum tst_cmd_flags flags)

vfork(2) + execvp(3) specified program.

Parameters:

argv (const char *const) – A list of two (at least program name + NULL) or more pointers that represent the argument list to the new program. The array of pointers must be terminated by a NULL pointer.
stdout_fd (int) – File descriptor where to redirect stdout. Set -1 if redirection is not needed.
stderr_fd (int) – File descriptor where to redirect stderr. Set -1 if redirection is not needed.
flags (enum tst_cmd_flags) – enum tst_cmd_flags.

Return

The exit status of the program.

tst_cmd

int tst_cmd(const char *const argv, const char *stdout_path, const char *stderr_path, enum tst_cmd_flags flags)

Executes tst_cmd_fds() and redirects its output to a file.

Parameters:

argv (const char *const) – A list of two (at least program name + NULL) or more pointers that
stdout_path (const char*) – Path where to redirect stdout. Set NULL if redirection is not needed.
stderr_path (const char*) – Path where to redirect stderr. Set NULL if redirection is not needed.
flags (enum tst_cmd_flags) – enum tst_cmd_flags.

Return

The exit status of the program.

tst_system

int tst_system(const char *command)

Wrapper function for system(3), ignorcing SIGCHLD signal.

Parameters:

command (const char*) – The command to be run.

Return

The system() return code.

Crypto

tst_crypto.h – kernel’s crypto layer helpers

Helpers for interacting with kernel’s crypto layer using the netlink interface.

tst_crypto_add_alg

int tst_crypto_add_alg(struct tst_netlink_context *ctx, const struct crypto_user_alg *alg)

Add a crypto algorithm to a session.

Parameters:

ctx (struct tst_netlink_context*) – Initialized netlink context
alg (const struct crypto_user_alg*) – The crypto algorithm or module to add.

Description

This requests a new crypto algorithm/engine/module to be initialized by the kernel. It sends the request contained in alg and then waits for a response. If sending the message or receiving the ack fails at the netlink level then tst_brk() with TBROK will be called.

Return

On success it will return 0 otherwise it will return an inverted error code from the crypto layer.

tst_crypto_del_alg

int tst_crypto_del_alg(struct tst_netlink_context *ctx, const struct crypto_user_alg *alg, unsigned int retries)

Delete a crypto algorithm from a session.

Parameters:

ctx (struct tst_netlink_context*) – Initialized netlink context
alg (const struct crypto_user_alg*) – The crypto algorithm to delete.
retries (unsigned int) – Number of retries before giving up. Recommended value: 1000

Description

Request that the kernel remove an existing crypto algorithm. This behaves in a similar way to tst_crypto_add_alg() except that it is the inverse operation and that it is not unusual for the crypto layer to return EBUSY. If EBUSY is returned then the function will internally retry the operation tst_crypto_session::retries times before giving up and returning EBUSY.

Return

Either 0 or an inverted error code from the crypto layer. If called during cleanup it may return a positive ENODATA value from the LTP library, you don’t need to log this error as it will already have been printed by tst_brk().

tst_af_alg.h – Kernel crypto algorithms (AF_ALG) helpers

Helpers for accessing kernel crypto algorithms via AF_ALG.

See https://www.kernel.org/doc/html/latest/crypto/userspace-if.html for more information about AF_ALG.

tst_alg_create

int tst_alg_create(void)

Create an AF_ALG algorithm socket.

Parameters:

void – no arguments

Description

This creates an AF_ALG algorithm socket that is initially not bound to any particular algorithm. On failure, tst_brk() is called with TCONF if the kernel doesn’t support AF_ALG, otherwise TBROK.

Return

a new AF_ALG algorithm socket

tst_alg_bind_addr

void tst_alg_bind_addr(int algfd, const struct sockaddr_alg *addr)

Bind an AF_ALG algorithm socket to an algorithm.

Parameters:

algfd (int) – An AF_ALG algorithm socket
addr (const struct sockaddr_alg*) – A structure which specifies the algorithm to use

Description

On failure, tst_brk() is called with TCONF if the kernel doesn’t support the specified algorithm, otherwise TBROK.

tst_alg_bind

void tst_alg_bind(int algfd, const char *algtype, const char *algname)

Bind an AF_ALG algorithm socket to an algorithm.

Parameters:

algfd (int) – An AF_ALG algorithm socket
algtype (const char*) – The type of algorithm, such as “hash” or “skcipher”
algname (const char*) – The name of the algorithm, such as “sha256” or “xts(aes)”

Description

Like tst_alg_bind_addr(), except this just takes in the algorithm type and name. The ‘feat’ and ‘mask’ fields are left 0.

On failure, tst_brk() is called with TCONF if the kernel doesn’t support the specified algorithm, otherwise TBROK.

tst_try_alg

int tst_try_alg(const char *algtype, const char *algname)

Check for the availability of an algorithm.

Parameters:

algtype (const char*) – The type of algorithm, such as “hash” or “skcipher”
algname (const char*) – The name of the algorithm, such as “sha256” or “xts(aes)”

Return

0 if the algorithm is available, or errno if unavailable.

tst_have_alg

bool tst_have_alg(const char *algtype, const char *algname)

Check for the availability of an algorithm.

Parameters:

algtype (const char*) – The type of algorithm, such as “hash” or “skcipher”
algname (const char*) – The name of the algorithm, such as “sha256” or “xts(aes)”

Return

true if the algorithm is available, or false if unavailable and call tst_res() with TCONF. If another error occurs, tst_brk() is called with TBROK unless algorithm is disabled due FIPS mode (errno ELIBBAD).

tst_require_alg

void tst_require_alg(const char *algtype, const char *algname)

Require the availability of an algorithm.

Parameters:

algtype (const char*) – The type of algorithm, such as “hash” or “skcipher”
algname (const char*) – The name of the algorithm, such as “sha256” or “xts(aes)”

Description

If the algorithm is unavailable, tst_brk() is called with TCONF. If another error occurs, tst_brk() is called with TBROK.

tst_alg_setkey

void tst_alg_setkey(int algfd, const uint8_t *key, unsigned int keylen)

Assign a cryptographic key to an AF_ALG algorithm socket.

Parameters:

algfd (int) – An AF_ALG algorithm socket
key (const uint8_t*) – Pointer to the key. If NULL, a random key is generated.
keylen (unsigned int) – Length of the key in bytes

Description

On failure, tst_brk() is called with TBROK.

tst_alg_accept

int tst_alg_accept(int algfd)

Create an AF_ALG request socket for the given algorithm socket.

Parameters:

algfd (int) – An AF_ALG algorithm socket

Description

This creates a request socket for the given algorithm socket, which must be bound to an algorithm. The same algorithm socket can have many request sockets used concurrently to perform independent cryptographic operations, e.g. hashing or encryption/decryption. But the key, if any, that has been assigned to the algorithm is shared by all request sockets.

On failure, tst_brk() is called with TBROK.

Return

a new AF_ALG request socket

tst_alg_setup

int tst_alg_setup(const char *algtype, const char *algname, const uint8_t *key, unsigned int keylen)

Set up an AF_ALG algorithm socket for the given algorithm w/ given key.

Parameters:

algtype (const char*) – The type of algorithm, such as “hash” or “skcipher”
algname (const char*) – The name of the algorithm, such as “sha256” or “xts(aes)”
key (const uint8_t*) – The key to use (optional)
keylen (unsigned int) – The length of the key in bytes (optional)

Description

This is a helper function which creates an AF_ALG algorithm socket, binds it to the specified algorithm, and optionally sets a key. If keylen is 0 then no key is set; otherwise if key is NULL a key of the given length is randomly generated and set; otherwise the given key is set.

Return

the AF_ALG algorithm socket that was set up

tst_alg_setup_reqfd

int tst_alg_setup_reqfd(const char *algtype, const char *algname, const uint8_t *key, unsigned int keylen)

Set up an AF_ALG request socket for the given algorithm w/ given key.

Parameters:

algtype (const char*) – The type of algorithm, such as “hash” or “skcipher”
algname (const char*) – The name of the algorithm, such as “sha256” or “xts(aes)”
key (const uint8_t*) – The key to use (optional)
keylen (unsigned int) – The length of the key in bytes (optional)

Description

This is like tst_alg_setup(), except this returns a request fd instead of the alg fd. The alg fd is closed, so it doesn’t need to be kept track of.

Return

the AF_ALG request socket that was set up

tst_alg_sendmsg

void tst_alg_sendmsg(int reqfd, const void *data, size_t datalen, const struct tst_alg_sendmsg_params *params)

Send some data to an AF_ALG request socket, including control data.

Parameters:

reqfd (int) – An AF_ALG request socket
data (const void*) – The data to send
datalen (size_t) – The length of data in bytes
params (const struct tst_alg_sendmsg_params*) – Specification of the control data to send

Description

On failure, tst_brk() is called with TBROK.

Guarded buffers

Guarded buffers introduction

Guarded buffer has a page with PROT_NONE allocated right before the start of the buffer and canary after the end of the buffer. That means that any memory access before the buffer ends with EFAULT or SEGFAULT and any write after the end of the buffer will be detected because it would overwrite the canaries.

It should be used for all buffers passed to syscalls to make sure off-by-one buffer accesses does not happen.

struct tst_buffers

struct tst_buffers: A guarded buffer description for allocator.

Definition

struct tst_buffers {
    void *ptr;
    size_t size;
    int *iov_sizes;
    char *str;
}

Members

ptr: A pointer to the pointer to buffer. This is dereferenced and set by the allocator.
size: A buffer size in bytes. Only one of size and iov_sizes can be set.
iov_sizes: An -1 terminated array of sizes used to construct a struct iovec buffers.
str: If size is zero and iov_sizes is NULL this string is going to be copied into the buffer.

Description

Buffer description consist of a pointer to a pointer and buffer type/size encoded as a different structure members.

tst_buffers_alloc

void tst_buffers_alloc(struct tst_buffers bufs)

Allocates buffers based on the tst_buffers structure.

Parameters:

bufs (struct tst_buffers) – A NULL terminated array of test buffer descriptions.

Description

This is called from the test library if the tst_test.bufs pointer is set.

tst_strdup

char *tst_strdup(const char *str)

Copies a string into a newly allocated guarded buffer.

Parameters:

str (const char*) – A string to be duplicated.

Return

A pointer to the string duplicated in a guarded buffer.

Allocates a buffer with tst_alloc() and copies the string into it.

tst_alloc

void *tst_alloc(size_t size)

Allocates a guarded buffer.

Parameters:

size (size_t) – A size of the buffer.

Return

A newly allocated guarded buffer.

tst_aprintf

char *tst_aprintf(const char *fmt, ...)

Printf into a newly allocated guarded buffer.

Parameters:

fmt (const char*) – A printf-like format.
ellipsis (ellipsis) – A printf-like parameters.

Return

A newly allocated buffer.

Allocates a buffer with tst_alloc() then prints the data into it.

tst_iovec_alloc

struct iovec *tst_iovec_alloc(int sizes)

Allocates a complete iovec structure.

Parameters:

sizes (int) – A -1 terminated array of buffer sizes.

Return

Newly allocated iovec structure.

tst_free_all

void tst_free_all(void)

Frees all allocated buffers.

Parameters:

void – no arguments

Description

It’s important to free all guarded buffers because the canaries after the buffer are checked only when the buffer is being freed.

This is called at the end of the test automatically.

Kernel

tst_kernel_bits

int tst_kernel_bits(void)

Detect if running on 32bit or 64bit kernel.

Parameters:

void – no arguments

Return

32 if the test process is running on 32bit kernel and 64 if on 64bit kernel.

tst_is_compat_mode

int tst_is_compat_mode(void)

Detect if running in compat mode.

Parameters:

void – no arguments

Description

driver (const char*) – the name of the driver.

Description

Check support for the kernel module (both built-in and loadable).

Return

0 if the kernel has the driver, -1 when driver is missing or config file not available. On Android always 0 (always expect the driver is available).

tst_check_preempt_rt

int tst_check_preempt_rt(void)

Check if the running kernel is RT.

Parameters:

void – no arguments

Description

Check support for the kernel module (both built-in and loadable).

Return

-1 if the kernel is RT, 0 otherwise.

tst_kvcmp

int tst_kvcmp(const char *cur_kver, int r1, int r2, int r3)

Compare given kernel version with kernel in string.

Parameters:

cur_kver (const char*) – Kernel version string (struct utsname.release).
r1 (int) – Major kernel version.
r2 (int) – Minor kernel version.
r3 (int) – Kernel patch level.

Description

Everything after first three version numbers till the end of the string is ignored.

The same as tst_kvercmp() but running kernel version is passed as parameter instead of utilizing uname().

Return

Negative if older, 0 if the same and positive if newer.

tst_parse_kver

int tst_parse_kver(const char *str_kver, int *v1, int *v2, int *v3)

Parses a version string into three integers.

Parameters:

str_kver (const char*) – Kernel version string (struct utsname.release).
v1 (int*) – Major kernel version.
v2 (int*) – Minor kernel version.
v3 (int*) – Kernel patch level.

Description

Everything after first three version numbers till the end of the string is ignored.

Return

0 on success, 1 on error.

tst_kvcmp_distname

const char *tst_kvcmp_distname(const char *cur_kver)

Get the distribution name from kernel version string.

Parameters:

cur_kver (const char*) – Kernel version string (struct utsname.release).

Return

The distribution name parsed from kernel version string or NULL.

tst_kvexcmp

int tst_kvexcmp(const char *tst_exv, const char *cur_kver)

Compares versions up to five version numbers long.

Parameters:

tst_exv (const char*) – The tested kernel version string (struct utsname.release).
cur_kver (const char*) – The current version in string (struct utsname.release).

Description

The return value is similar to the strcmp(3) function, i.e. zero means equal, negative value means that the kernel is older than the expected value and positive means that it’s newer.

Return

negative if older, 0 if the same and positive if newer.

tst_kvercmp

int tst_kvercmp(int r1, int r2, int r3)

Compare a kernel version against currently running kernel.

Parameters:

r1 (int) – Major kernel version.
r2 (int) – Minor kernel version.
r3 (int) – Kernel patch level.

Description

Parse the output from uname(2) and compare it to the passed values. This is shortcut for calling tst_kvcmp() with uname -r as str_kver.

Return

Negative if older, 0 if the same and positive if newer.

struct tst_kern_exv

struct tst_kern_exv: describe vendor kernel.

Definition

struct tst_kern_exv {
    char *dist_name;
    char *extra_ver;
}

Members

dist_name: A distribution name, e.g. “SLES”, “RHEL9”, “UBUNTU”.
extra_ver: A vendor kernel version to check, e.g. “5.14.0-441”.

tst_kvercmp2

int tst_kvercmp2(int r1, int r2, int r3, struct tst_kern_exv *vers)

Compare given distro kernel version with the currently running kernel.

Parameters:

r1 (int) – Major kernel version.
r2 (int) – Minor kernel version.
r3 (int) – Kernel patch level.
vers (struct tst_kern_exv*) – A {} terminated array of struct tst_kern_exv.

Description

Attempts to look up a distro specific kernel version from the struct tst_kern_exv table first and if no match is found falls back to the version passed in r1, r2, r3 (see tst_kvercmp()).

The distribution name is detected either from the kernel release string e.g. el9 is mapped to RHEL9 or as a capitalized value of the ID= variable from /etc/os-release.

Return

Negative if older, 0 if the same and positive if newer.

Process state

macro TST_PROCESS_STATE_WAIT

TST_PROCESS_STATE_WAIT(pid, state, msec_timeout)

Waits for a process state change.

Parameters:

pid – A process pid.
state – A state to wait for.
msec_timeout – A timeout for the wait.

Description

Polls /proc/$PID/state for a process state changes.

Possible process states (see ps(1)):

R Process is running.
S Process is sleeping.
D Process sleeping uninterruptibly.
Z Zombie process.
T Process is traced.
t Tracing stopped.
X Process id dead.

macro TST_PROCESS_EXIT_WAIT

TST_PROCESS_EXIT_WAIT(pid, msec_timeout)

Waits while pid is present on the system.

Parameters:

pid – A process pid.
msec_timeout – A timeout for the wait.

Description

Loops until kill($PID, 0) succeds or timeout is reached.

macro TST_THREAD_STATE_WAIT

TST_THREAD_STATE_WAIT(tid, state, msec_timeout)

Waits for a thread state change.

Parameters:

tid – A thread tid.
state – A state to wait for.
msec_timeout – A timeout for the wait.

Description

Polls /proc/self/task/$TID/state for a thread state change.

Possible thread states are the same as for TST_PROCESS_STATE_WAIT().

NUMA

str (const char*) – A string a positive number optionally followed by an unit, i.e. K, M, or G for kilobytes, megabytes and gigabytes.
val (long long*) – A pointer to long long integer to store the size in bytes to.
min (long long) – A lower bound.
max (long long) – An upper bound.

Return

A zero if whole string was consumed and the value was within bounds, an errno otherwise.

Saving and restoring /proc|sys values

macro TST_SR_TCONF_MISSING

TST_SR_TCONF_MISSING(): End test with TCONF if the file does not exist.

macro TST_SR_TBROK_MISSING

TST_SR_TBROK_MISSING(): End test with TBROK if the file does not exist.

macro TST_SR_SKIP_MISSING

TST_SR_SKIP_MISSING(): Continue without saving the file if it does not exist.

macro TST_SR_TCONF_RO

TST_SR_TCONF_RO(): End test with TCONF if the file is read-only.

macro TST_SR_TBROK_RO

TST_SR_TBROK_RO(): End test with TBROK if the file is read-only.

macro TST_SR_SKIP_RO

TST_SR_SKIP_RO(): Continue without saving the file if it is read-only.

macro TST_SR_IGNORE_ERR

TST_SR_IGNORE_ERR(): Ignore all errors during reading and writing the file.

struct tst_path_val

struct tst_path_val: Saving and restoring /proc|sys values.

Definition

struct tst_path_val {
    const char *path;
    const char *val;
    unsigned int flags;
}

Members

path: A file in /proc|sys.
val: If non-NULL string it will be saved to path.
flags: TST_SR_* flags to modify the behavior.

macro TST_SYS_CONF_LONG_SET

TST_SYS_CONF_LONG_SET(path, val, check)

Writes a long int into a sys or proc file.

Parameters:

path – A path to a sysfs or a procfs file.
val – A long int value to be written to the file.
check – If non-zero the library reads the file back and checks that the value is the one we have written there. If not the library calls tst_brk(TBROK, …).

Description

Sets a sysfs or procfs file and optionally checks that it was set correctly.

macro TST_SYS_CONF_LONG_GET

TST_SYS_CONF_LONG_GET(path)

Reads a long int from sys or proc file.

Parameters:

path – A path to a sysfs or a procfs file.

Return

A value read from the file converted into a long.

Gets a sysfs or procfs file value and converts it to long.

Temporary directory

tst_purge_dir

void tst_purge_dir(const char *path)

Wipe the content of given directory.

Parameters:

path (const char*) – Path of the directory to be wiped.

Description

Wipe the content of given directory but keep the directory itself.

tst_tmpdir_path

char *tst_tmpdir_path(void)

Returns a pointer to a tmpdir path.

Parameters:

void – no arguments

Description

The returned path is allocated and initialized the first time this function is called, each subsequent call will return the same pointer.

Return

A newly allocated path. The memory is freed automatically at the end of the test. If allocation fails the function calls tst_brk() and exits the test.

tst_tmpdir_genpath

char *tst_tmpdir_genpath(const char *fmt, ...)

Construct an absolute path pointing to a file inside tmpdir.

Parameters:

fmt (const char*) – A printf-like format string.
ellipsis (ellipsis) – A printf-like parameter list.

Description

Constructs a path inside tmpdir i.e. adds a prefix pointing to the current test tmpdir to the string build by the printf-like format.

Return

Parameters:

filename (const char*) – swap file name.

Description

Check swapon/swapoff support status of filesystems or files we are testing on.

Return

true if swap is supported, false if not.

tse_count_swaps

int tse_count_swaps(void)

Get the used swapfiles number.

Parameters:

void – no arguments

Return

used swapfiles number.