Developing using 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.
- TFAIL
Reports a single failure.
- TBROK
Reports a single breakage.
- TWARN
Reports a single warning. Warnings increment a warning counter and show up in test results.
- 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_type.
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_type.
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.
- Parameters:
ttype – An enum tst_res_type.
arg_fmt – A printf-like format.
ellipsis (ellipsis) – A printf-like parameters.
Description
Reports either TBROK or TCONF and exits the test immediately. When called
all children in the same process group as the main test library process are
killed. This function, unless in a test cleanup, calls _exit()
and does not
return.
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.
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_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 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;
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;
const char *dev_fs_type;
const char *const *dev_fs_opts;
const char *const *dev_extra_opts;
const char *mntpoint;
unsigned int mnt_flags;
void *mnt_data;
int max_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 char * const *needs_drivers;
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;
const char *const *needs_cmds;
const enum tst_cg_ver needs_cgroup_ver;
const char *const *needs_cgroup_ctrls;
}
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 tst_test.dev_fs_type 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 byexec()
.- 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 filesytems, 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_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 andtst_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.
- dev_fs_type
If set overrides the default file system type for the device and sets the tst_device.fs_type.
- dev_fs_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.
- dev_extra_opts
A NULL terminated array of extra options passed to mkfs in the case of ‘tst_test.format_device’. Extra options are passed to mkfs after the device path. Commonly the option after mkfs is the number of blocks and can be used to limit the file system not to use the whole block device.
- 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.
- 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’.
- max_runtime
Maximal test runtime in seconds. Any test that runs for more than a second or two should set this and also use
tst_remaining_runtime()
to exit when runtime was used up. Tests may finish sooner, for example if requested number of iterations was reached before the runtime runs out. If test runtime cannot be know in advance it should be set to TST_UNLIMITED_RUNTIME.- 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
undescribed
- sample
undescribed
- resource_files
A NULL terminated array of filenames that will be copied to the test temporary directory from the LTP datafiles directory.
- needs_drivers
A NULL terminated array of kernel modules required to run the test. The module has to be build in or present in order for the test to run.
- 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.
- 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_buffer_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 commands 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.
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.
important
The LTP_IPC_PATH variable must be passed to the program environment.
macro TST_TEST_TCONF
-
TST_TEST_TCONF(message)
Exit tests with a TCONF message.
- Parameters:
message – undescribed
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.
Option parsing
Option parsing functions
Implements simple helpers on the top of the strtol()
and strtod()
for
command line option parsing.
tst_parse_int
-
int tst_parse_int(const char *str, int *val, int min, int max)
Parse an integer from a string.
- Parameters:
str (const char*) – A string with an integer number.
val (int*) – A pointer to integer to store the result to.
min (int) – A lower bound, pass INT_MIN for full range.
max (int) – An upper bound, pass INT_MAX for full range.
Return
- A zero if whole string was consumed and the value was within bounds,
an errno otherwise.
tst_parse_long
-
int tst_parse_long(const char *str, long *val, long min, long max)
Parse a long integer from a string.
- Parameters:
str (const char*) – A string with an integer number.
val (long*) – A pointer to long integer to store the result to.
min (long) – A lower bound, pass LONG_MIN for full range.
max (long) – An upper bound, pass LONG_MAX for full range.
Return
- A zero if whole string was consumed and the value was within bounds,
an errno otherwise.
tst_parse_float
-
int tst_parse_float(const char *str, float *val, float min, float max)
Parse a floating point number from a string.
- Parameters:
str (const char*) – A string with a floating point number.
val (float*) – A pointer to float to store the result to.
min (float) – A lower bound.
max (float) – An upper bound.
Return
- A zero if whole string was consumed and the value was within bounds,
an errno otherwise.
tst_parse_filesize
-
int tst_parse_filesize(const char *str, long long *val, long long min, long long max)
Parse a file size from a string.
- Parameters:
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.
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.
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()
.
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()
.
libltpswap
macro MAKE_SMALL_SWAPFILE
-
MAKE_SMALL_SWAPFILE(swapfile)
create small swap file.
- Parameters:
swapfile – swap filename.
Description
Macro to create small swap file. Size defined with MINIMAL_SWAP_SIZE_MB.
macro SAFE_MAKE_SMALL_SWAPFILE
-
SAFE_MAKE_SMALL_SWAPFILE(swapfile)
create small swap file (safe version).
- Parameters:
swapfile – swap filename.
Description
Macro to create small swap file. Size defined with MINIMAL_SWAP_SIZE_MB. Includes safety checks to handle potential errors.
macro MAKE_SWAPFILE_SIZE
-
MAKE_SWAPFILE_SIZE(swapfile, size)
create swap file (MB).
- Parameters:
swapfile – swap filename.
size – swap size in MB.
Description
Macro to create swap file, size specified in megabytes (MB).
macro MAKE_SWAPFILE_BLKS
-
MAKE_SWAPFILE_BLKS(swapfile, blocks)
create swap file (blocks).
- Parameters:
swapfile – swap filename.
blocks – number of blocks.
Description
Macro to create swap file, size specified in block numbers.
macro SAFE_MAKE_SWAPFILE_SIZE
-
SAFE_MAKE_SWAPFILE_SIZE(swapfile, size)
create swap file (MB, safe version).
- Parameters:
swapfile – swap file name.
size – swap size in MB.
Description
Macro to safely create swap file, size specified in megabytes (MB). Includes safety checks to handle potential errors.
macro SAFE_MAKE_SWAPFILE_BLKS
-
SAFE_MAKE_SWAPFILE_BLKS(swapfile, blocks)
create swap file (block, safe version)
- Parameters:
swapfile – swap file name.
blocks – number of blocks.
Description
Macro to safely create swap file, size specified in block numbers. Includes safety checks to handle potential errors.
is_swap_supported
-
bool is_swap_supported(const char *filename)
Check swapon/swapoff support.
- 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.
tst_max_swapfiles
-
int tst_max_swapfiles(void)
Get kernel constant MAX_SWAPFILES value.
- Parameters:
void – no arguments
Return
MAX_SWAPFILES value.
tst_count_swaps
-
int tst_count_swaps(void)
Get the used swapfiles number.
- Parameters:
void – no arguments
Return
used swapfiles number.