Complete the documentation adding missing headers
v6 cover Complete the documentation adding missing headers
This conversion and fix has been done with Claude Code. Complete this review before adding these changes:
https://patchwork.ozlabs.org/project/ltp/list/?series=506891
- add missing headers
- convert documentation from doxygen to kernel-doc
- add SAFE_* macro section
---
Changes in v6:
- PATCH 3: replace the U+2014 em-dash next to SAFE_CLOSE in
api_safe_macros.rst with an ASCII '--' so doc/ stays ASCII-only
- Link to v5: https://lore.kernel.org/r/[email protected]
Changes in v5:
- PATCH 1: drop the stray empty "Verdict:" line accidentally left in
the commit message body
- PATCH 1: remove the leftover "@sa tst_fzsync_pair" Doxygen directive
from the file-level overview comment in tst_fuzzy_sync.h
- PATCH 2: extend the shell API variables reference with the remaining
public inputs (TST_DISABLE_APPARMOR, TST_DISABLE_SELINUX,
TST_SKIP_LSM_WARNINGS, TST_NO_DEFAULT_RUN, TST_TMPDIR_RHOST)
- Link to v4: https://lore.kernel.org/r/[email protected]
Changes in v4:
- fix build errors
- Link to v3: https://lore.kernel.org/r/[email protected]
Changes in v3:
- PATCH 3: add the missing blank line between tst_mount_has_opt() and
the tst_is_mounted() kernel-doc block in tst_device.h
- PATCH 3: restore the "Requires <string.h>" note (for strlen()) in the TST_KCONFIG_INIT() kernel-doc comment in tst_kconfig.h
- Link to v2: https://lore.kernel.org/r/[email protected]
Changes in v2:
- PATCH 1: drop the incorrect claim about fixing the tse_numa.h
kernel-doc reference (it was already correct) and correct the header
count from 12 to 10 (tse_numa.h and tse_swap.h were already present)
- PATCH 1: remove leftover Doxygen directives (@param, @return,
@relates, @sa) in tst_fuzzy_sync.h that the new kernel-doc comments
superseded
- PATCH 2: drop the already-applied field-rename claims (.runtime,
.hugepages, dev_* moves) from the commit message and correct the
added-field count from 10 to 8
- PATCH 3: fix the copyright year (2025 -> 2026), remove the duplicate
SAFE_MMAP entry from the core macros section, and correct the macro
count from 217 to 216
- Link to v1: https://lore.kernel.org/r/[email protected]
---
Andrea Cervesato (3):
doc: Add missing API references to api_c_tests.rst
doc: Complete struct tst_test table and shell API docs
doc: Add SAFE_* macros reference page
doc/developers/api_c_tests.rst | 71 +++++-- doc/developers/api_safe_macros.rst | 382 +++++++++++++++++++++++++++++++++++++ doc/developers/api_shell_tests.rst | 183 ++++++++++++++++++ doc/developers/writing_tests.rst | 28 ++- doc/index.rst | 4 + include/tse_uinput.h | 30 +-- include/tst_clone.h | 24 ++- include/tst_device.h | 166 ++++++++++------ include/tst_fuzzy_sync.h | 232 +++++++++++----------- include/tst_hugepage.h | 35 +++- include/tst_kconfig.h | 78 ++++---- include/tst_taint.h | 32 ++-- 12 files changed, 972 insertions(+), 293 deletions(-)
---
base-commit: d635eefe6f4cc0791c6cbd3c564c420ca303e729
change-id: 20260601-doc_add_missing_headers-ca51d98d32ac
Best regards,
Signature · 5 lines
Andrea Cervesato <[email protected]> -- Mailing list info: https://lists.linux.it/listinfo/ltp
PATCH v6 1/3 doc: Add missing API references to api_c_tests.rst
From: Andrea Cervesato <[email protected]>
Add kernel-doc directives for 10 headers that were missing from the C API documentation page:
tse_uinput.h, tst_clone.h, tst_device.h, tst_fs.h, tst_fuzzy_sync.h, tst_hugepage.h, tst_kconfig.h, tst_memutils.h, tst_safe_file_ops.h, tst_taint.h
Convert plain and Doxygen-style comments to kernel-doc format in tse_uinput.h, tst_clone.h, tst_device.h, tst_fuzzy_sync.h, tst_hugepage.h, tst_kconfig.h and tst_taint.h so the documentation builder can extract them. This includes removing leftover Doxygen directives (@param, @return, @relates, @sa) superseded by the new kernel-doc comments.
Sort all sections alphabetically under LTP C API.
--- doc/developers/api_c_tests.rst | 71 ++++++++++--- include/tse_uinput.h | 30 +++--- include/tst_clone.h | 24 +++-- include/tst_device.h | 166 ++++++++++++++++++----------- include/tst_fuzzy_sync.h | 232 ++++++++++++++++++++--------------------- include/tst_hugepage.h | 35 +++++-- include/tst_kconfig.h | 78 +++++++------- include/tst_taint.h | 32 +++--- 8 files changed, 377 insertions(+), 291 deletions(-)
doc/developers/api_c_tests.rst +54 -17
@@ -7,46 +7,68 @@ LTP C API ========= -Core LTP API ------------- -.. kernel-doc:: ../../include/tst_res_flags.h -.. kernel-doc:: ../../include/tst_test.h - -Test macros ------------ -.. kernel-doc:: ../../include/tst_test_macros.h - Capabilities ------------ .. kernel-doc:: ../../include/tst_capability.h Checkpoints ----------- - .. kernel-doc:: ../../include/tst_checkpoint.h +Clone +----- +.. kernel-doc:: ../../include/tst_clone.h + Commands -------- .. kernel-doc:: ../../include/tst_cmd.h +Core LTP API +------------ +.. kernel-doc:: ../../include/tst_res_flags.h +.. kernel-doc:: ../../include/tst_test.h + Crypto ------ .. kernel-doc:: ../../include/tst_crypto.h .. kernel-doc:: ../../include/tst_af_alg.h +Devices +------- +.. kernel-doc:: ../../include/tst_device.h + +Filesystems +----------- +.. kernel-doc:: ../../include/tst_fs.h + +Fuzzy sync +---------- +.. kernel-doc:: ../../include/tst_fuzzy_sync.h + Guarded buffers --------------- .. kernel-doc:: ../../include/tst_buffers.h +Hugepages +--------- +.. kernel-doc:: ../../include/tst_hugepage.h + Kernel ------ .. kernel-doc:: ../../include/tst_kernel.h .. kernel-doc:: ../../include/tst_kvercmp.h -Process state -------------- +Kernel configuration +-------------------- +.. kernel-doc:: ../../include/tst_kconfig.h -.. kernel-doc:: ../../include/tst_process_state.h +Kernel taint +------------ +.. kernel-doc:: ../../include/tst_taint.h + +Memory +------ +.. kernel-doc:: ../../include/tst_memutils.h NUMA ----
@@ -54,17 +76,32 @@ NUMA Option parsing -------------- - .. kernel-doc:: ../../include/tst_parse.h +Process state +------------- +.. kernel-doc:: ../../include/tst_process_state.h + +Safe file operations +-------------------- +.. kernel-doc:: ../../include/tst_safe_file_ops.h + Saving and restoring /proc|sys values ------------------------------------- .. kernel-doc:: ../../include/tst_sys_conf.h +Swap +---- +.. kernel-doc:: ../../include/tse_swap.h + Temporary directory ------------------- .. kernel-doc:: ../../include/tst_tmpdir.h -LTP libraries -------------- -.. kernel-doc:: ../../include/tse_swap.h +Test macros +----------- +.. kernel-doc:: ../../include/tst_test_macros.h + +Uinput +------ +.. kernel-doc:: ../../include/tse_uinput.h
include/tse_uinput.h +15 -15
@@ -7,40 +7,40 @@#define TSE_UINPUT_H__ /** -* Tries to open the uinput device. +* open_uinput() - Try to open the uinput device. * -* Returns file descriptor on success, -1 on failure. +* Return: File descriptor on success, -1 on failure. */ int open_uinput (void );/** -* Creates virtual input device. -* -* @fd File descriptor returned by open_uinput(). +* create_input_device() - Create a virtual input device. +* @fd: File descriptor returned by open_uinput(). */ void create_input_device (int fd);/** -* Parses /proc/bus/input/devices and returns the strings for our virtual device. -* If passing 'H' to it, it returns HANDLERS string. If passing 'S' to it, it -* returns SYSFS string. +* get_input_field_value() - Get a field string for the virtual device. +* @field: Field character ('H' for handlers, 'S' for sysfs). +* +* Parses /proc/bus/input/devices and returns the string for our +* virtual device matching the requested field. * -* Returns newly allocated string, or NULL in a case of failure. +* Return: Newly allocated string, or NULL on failure. */ char *get_input_field_value (char field);/** -* Sets up the virtual device to appear as a mouse, this must be called before -* the call to create_input_device(). +* setup_mouse_events() - Set up the virtual device as a mouse. +* @fd: File descriptor as returned by open_uinput(). * -* @fd File descriptor as returned by open_uinput(). +* Must be called before create_input_device(). */ void setup_mouse_events (int fd);/** -* Destroys virtual input device. -* -* @fd File descriptor returned by open_uinput(). +* destroy_input_device() - Destroy a virtual input device. +* @fd: File descriptor returned by open_uinput(). */ void destroy_input_device (int fd);
include/tst_clone.h +16 -8
@@ -9,7 +9,14 @@ #ifdef TST_TEST_H__ -/* The parts of clone3's clone_args we support */ +/** + * struct tst_clone_args - Arguments for tst_clone(). + * @flags: Clone flags (e.g. CLONE_NEWNS, CLONE_NEWPID). + * @pidfd: Pointer (cast to u64) where the kernel stores the pidfd when + * CLONE_PIDFD is set. + * @exit_signal: Signal sent to the parent when the child exits. + * @cgroup: Target cgroup fd (requires CLONE_INTO_CGROUP). + */ struct tst_clone_args { uint64_t flags; uint64_t pidfd;
@@ -17,15 +24,16 @@ struct tst_clone_args {uint64_t cgroup; }; -/* clone3 with fallbacks to clone when possible. Be aware that it -* returns -1 if clone3 fails (except ENOSYS), but -2 if clone fails. +/** +* tst_clone() - Create a child process via clone3 with clone fallback. +* @args: Clone arguments. * -* Without CLONE_VM this acts like fork so you may want to set -* tst_test.forks_child (safe_clone requires this). +* Without CLONE_VM this acts like fork(); set tst_test.forks_child +* accordingly (safe_clone requires it). Set exit_signal to SIGCHLD +* for tst_reap_children. * -* You should set exit_signal to SIGCHLD for -* tst_reap_children. Otherwise you must call wait with the -* appropriate parameters. +* Return: Child PID in the parent, 0 in the child, -1 on clone3 failure +* (except ENOSYS), -2 on clone failure. */ pid_t tst_clone (const struct tst_clone_args *args);
include/tst_device.h +107 -59
230 lines not on this page · raw message
include/tst_fuzzy_sync.h +112 -120
472 lines not on this page · raw message
include/tst_hugepage.h +25 -10
@@ -11,6 +11,11 @@extern char *nr_opt;/* -s num Set the number of the been allocated hugepages */ extern char *Hopt;/* -H /.. Location of hugetlbfs, i.e. -H /var/hugetlbfs */ +/** +* enum tst_hp_policy - Hugepage reservation policy. +* @TST_REQUEST: Try to reserve hugepages; tst_hugepages may be 0. +* @TST_NEEDS: Fail with TCONF if the requested count cannot be reserved. +*/ enum tst_hp_policy {TST_REQUEST ,TST_NEEDS ,
@@ -18,30 +23,40 @@ enum tst_hp_policy {#define TST_NO_HUGEPAGES ((unsigned long)-1) +/** +* struct tst_hugepage - Hugepage reservation request. +* @number: Number of hugepages to reserve. +* @policy: Reservation policy (TST_REQUEST or TST_NEEDS). +*/ struct tst_hugepage {const unsigned long number;enum tst_hp_policy policy; }; -/* -* Get the default hugepage size. Returns 0 if hugepages are not supported. +/** +* tst_get_hugepage_size() - Get the default hugepage size. +* +* Return: Hugepage size in bytes, or 0 if hugepages are not supported. */ size_t tst_get_hugepage_size (void ); -/* -* Try the best to request a specified number of huge pages from system, -* it will store the reserved hpage number in tst_hugepages. +/** +* tst_reserve_hugepages() - Reserve hugepages from the system. +* @hp: Hugepage request describing count and policy. +* +* Stores the number of actually reserved hugepages in tst_hugepages. +* The result depends on system memory fragmentation. * -* Note: this depend on the status of system memory fragmentation. +* Return: Number of hugepages reserved. */ unsigned long tst_reserve_hugepages (struct tst_hugepage *hp);/* -* This variable is used for recording the number of hugepages which system can -* provides. It will be equal to 'hpages' if tst_reserve_hugepages on success, -* otherwise set it to a number of hugepages that we were able to reserve. +* tst_hugepages - Number of hugepages actually reserved. * -* If system does not support hugetlb, then it will be set to 0. +* Set by tst_reserve_hugepages(). Equals the requested count on success, +* or fewer if the system could not provide enough. Zero when hugepages +* are not supported. */ extern unsigned long tst_hugepages;
include/tst_kconfig.h +36 -42
122 lines not on this page · raw message
include/tst_taint.h +12 -20
@@ -66,32 +66,24 @@#define TST_TAINT_T (1 << 17)/* kernel was built with the struct randomization plugin */ #define TST_TAINT_N (1 << 18)/* an in-kernel test has been run */ -/* -* Initialize and prepare support for checking tainted kernel. Called -* automatically by LTP library during test setup if tst_test.taint_check -* is non-zero. The value of tst_test.taint_check will be passed as the mask -* argument. -* -* supply the mask of TAINT-flags you want to check, for example -* (TST_TAINT_W | TST_TAINT_D) when you want to check if the kernel issued -* a warning or even reported it died. -* -* This function tests if the requested flags are supported on the -* locally running kernel. In case the tainted-flags are already set by -* the kernel, there is no reason to continue and TBROK is generated. +/** +* tst_taint_init() - Set up kernel taint checking. +* @mask: Bitmask of TST_TAINT_* flags to monitor. * -* The mask must not be zero. +* Called automatically by the LTP library during test setup when +* tst_test.taint_check is non-zero. Aborts with TBROK if any +* requested flags are already set. */ void tst_taint_init (unsigned int mask); -/* -* check if the tainted flags handed to tst_taint_init() are still not set -* during or after running the test. -* Calling this function is only allowed after tst_taint_init() was called, -* otherwise TBROK will be generated. +/** +* tst_taint_check() - Check if monitored taint flags have been set. +* +* May only be called after tst_taint_init(). Also called automatically +* at the end of testing when tst_test.taint_check is non-zero. * -* returns 0 or a bitmask of the flags that currently tainted the kernel. +* Return: 0 if clean, or a bitmask of newly set taint flags. */ unsigned int tst_taint_check (void );
Signature · 5 lines
2.51.0 -- Mailing list info: https://lists.linux.it/listinfo/ltp
Re: [LTP] doc: Add missing API references to api_c_tests.rst
Hi Andrea,
Quoted 1 line · Andrea Cervesato
doc: Add missing API references to
api_c_tests.rst
--- [PATCH 1/3] ---
Quoted 1 line
Fixes eef750db28 ("libs: adopt tse_ prefix for extended (non-core) library")
The Fixes tag references a commit that does not exist in the git history. git cat-file -t eef750db28 returns "Not a valid object name". Either the hash is wrong or the tag should be dropped.
--- [PATCH 2/3] ---
Review
Quoted 8 lines
* - .needs_device
-TST_NEEDS_DEVICE(quoted diff) +3
-0+ * - .needs_hugetlbfs + - \- + * - removed - TST_NEEDS_DRIVERS
The removed row corresponds to the formerly-named .needs_drivers field. Alphabetically needs_drivers (d) sorts before needs_hugetlbfs (h), so the removed row should appear before .needs_hugetlbfs, not after it.
Quoted 4 lines
Add 8 missing struct
tst_testfields to the C/Shell API comparison table inwriting_tests.rst: ...Add a shell API variables reference section to
api_shell_tests.rst
Two independent changes are bundled here: updating the comparison table in writing_tests.rst and adding the "Shell API variables" section to api_shell_tests.rst. These touch different files and serve different purposes. Each should be a separate commit per ground rule 7 (one logical change per patch).
--- [PATCH 3/3] ---
Quoted 1 line
- ``SAFE_FILE_READ_STR(path, buf)``
The macro is declared in include/tst_safe_file_ops.h as:
#define SAFE_FILE_READ_STR(path, buf, buf_size)
It takes three arguments, not two. The buf_size parameter is missing from the listed signature.
Verdict: Needs revision
---
Note:
The agent can sometimes produce false positives although often its findings are genuine. If you find issues with the review, please comment this email or ignore the suggestions.
Regards,
LTP AI Reviewer
Signature · 1 line
Mailing list info: https://lists.linux.it/listinfo/ltp
Re: [LTP] doc: Add missing API references to api_c_tests.rst
Hi,
Quoted 7 lines
Quoted 2 lines
Fixes eef750db28 ("libs: adopt tse_ prefix for extended (non-core) library")The Fixes tag references a commit that does not exist in the git history.
git cat-file -t eef750db28returns "Not a valid object name". Either the hash is wrong or the tag should be dropped.
This is caused by the CI. I need to fix it.
Quoted 11 lines
--- [PATCH 2/3] ---
Review
Quoted 8 lines
* - .needs_device
-TST_NEEDS_DEVICE(quoted diff) +3
-0+ * - .needs_hugetlbfs + - \- + * - removed - TST_NEEDS_DRIVERS
Quoted 4 lines
The
removedrow corresponds to the formerly-named.needs_driversfield. Alphabeticallyneeds_drivers(d) sorts beforeneeds_hugetlbfs(h), so theremovedrow should appear before.needs_hugetlbfs, not after it.
This is valid.
Quoted 14 lines
Quoted 5 lines
Add 8 missing struct
tst_testfields to the C/Shell API comparison table inwriting_tests.rst: ...Add a shell API variables reference section to
api_shell_tests.rstTwo independent changes are bundled here: updating the comparison table in
writing_tests.rstand adding the "Shell API variables" section toapi_shell_tests.rst. These touch different files and serve different purposes. Each should be a separate commit per ground rule 7 (one logical change per patch).--- [PATCH 3/3] ---
Quoted 8 lines
Quoted 1 line
- ``SAFE_FILE_READ_STR(path, buf)``
The macro is declared in
include/tst_safe_file_ops.has:#define SAFE_FILE_READ_STR(path, buf, buf_size)It takes three arguments, not two. The
buf_sizeparameter is missing from the listed signature.
This is also valid.
--
Andrea Cervesato
SUSE QE Automation Engineer Linux
[email protected]
Signature · 1 line
Mailing list info: https://lists.linux.it/listinfo/ltp
Re: [LTP] doc: Add missing API references to api_c_tests.rst
In reply to Andrea CervesatoHi Andrea,
Quoted 1 line · Andrea Cervesato
[PATCH] doc: Add missing API references to
api_c_tests.rst
--- [PATCH 1/3] ---
Quoted 1 line
Fixes eef750db28 ("libs: adopt tse_ prefix for extended (non-core) library")
The commit eef750db28 referenced in the Fixes tag does not exist in the LTP git history. Is the commit hash correct?
--- [PATCH 2/3] ---
Quoted 11 lines
doc: Complete struct
tst_testtable and shell API docsAdd 8 missing struct
tst_testfields to the C/Shell API comparison table inwriting_tests.rst: .filesystems, .forks_child, .min_runtime, .needs_abi_bits, .needs_cgroup_nsdelegate, .needs_cgroup_ver, .needs_hugetlbfs and .runs_script, and fix the alphabetical ordering of .mnt_flags and .min_swap_avail.Add a shell API variables reference section to
api_shell_tests.rstdocumenting all public TST_* input/output variables, checkpoint functions, and retry helpers.
The commit body describes what changed, but does not explain why the change is needed. Could you provide a motivation for the change?
Verdict: Needs revision
---
Note:
The agent can sometimes produce false positives although often its findings are genuine. If you find issues with the review, please comment this email or ignore the suggestions.
Regards,
LTP AI Reviewer
Signature · 1 line
Mailing list info: https://lists.linux.it/listinfo/ltp
PATCH v6 2/3 doc: Complete struct tst_test table and shell API docs
In reply to Andrea CervesatoFrom: Andrea Cervesato <[email protected]>
Add 8 missing struct tst_test fields to the C/Shell API comparison table in writing_tests.rst: .filesystems, .forks_child, .min_runtime, .needs_abi_bits, .needs_cgroup_nsdelegate, .needs_cgroup_ver, .needs_hugetlbfs and .runs_script, and fix the alphabetical ordering of .mnt_flags and .min_swap_avail.
Add a shell API variables reference section to api_shell_tests.rst documenting all public TST_* input/output variables, checkpoint functions, and retry helpers.
--- doc/developers/api_shell_tests.rst | 183 +++++++++++++++++++++++++++++++++++++ doc/developers/writing_tests.rst | 28 +++++- 2 files changed, 209 insertions(+), 2 deletions(-)
doc/developers/api_shell_tests.rst +183 -0
@@ -93,3 +93,186 @@ interrupted by :ref:`tst_brk`. .. literalinclude:: ../../testcases/lib/tests/shell_loader_setup_cleanup.sh :language: shell + +Shell API variables +------------------- + +The following variables are available to shell tests. Variables marked +*input* are set by the test before sourcing ``tst_run.sh``; variables +marked *output* are set by the library for tests to read. + +Test definition (input) +~~~~~~~~~~~~~~~~~~~~~~~ + +``TST_TESTFUNC`` + Name of the test function (required). + +``TST_CNT`` + Number of test cases. When set the test function is called + ``TST_CNT`` times with a counter argument. + +``TST_SETUP`` + Name of the setup function (called once before tests). + +``TST_CLEANUP`` + Name of the cleanup function (called once after tests or on + ``tst_brk``). + +``TST_OPTS`` + Extra getopts option string. + +``TST_PARSE_ARGS`` + Name of a function to parse extra options from ``TST_OPTS``. + +``TST_USAGE`` + Name of a function printing extra usage information. + +``TST_POS_ARGS`` + Number of expected positional arguments. + +``TST_TEST_DATA`` + Space-separated data passed as a second argument to the test + function. + +``TST_TEST_DATA_IFS`` + Custom delimiter for ``TST_TEST_DATA`` (default: space). + +Requirements (input) +~~~~~~~~~~~~~~~~~~~~ + +``TST_NEEDS_ROOT`` + Set to 1 to require root privileges. + +``TST_NEEDS_TMPDIR`` + Set to 1 to create a temporary directory. + +``TST_NEEDS_DEVICE`` + Set to 1 to prepare a block device. + +``TST_NEEDS_CMDS`` + Space-separated list of required commands. + +``TST_NEEDS_MODULE`` + Kernel module name that must be loadable. + +``TST_NEEDS_DRIVERS`` + Space-separated list of required kernel drivers. + +``TST_NEEDS_KCONFIGS`` + Space-separated list of required kernel config options + (e.g. ``CONFIG_NUMA=y``). + +``TST_NEEDS_KCONFIGS_IFS`` + Custom delimiter for ``TST_NEEDS_KCONFIGS`` (default: comma). + +``TST_NEEDS_CHECKPOINTS`` + Set to 1 to enable checkpoint support. + +``TST_MIN_KVER`` + Minimum kernel version string (e.g. ``4.18``). + +Device and filesystem (input) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``TST_FORMAT_DEVICE`` + Set to 1 to format ``TST_DEVICE`` before the test. + +``TST_MOUNT_DEVICE`` + Set to 1 to mount ``TST_DEVICE`` at ``TST_MNTPOINT``. + +``TST_DEV_EXTRA_OPTS`` + Extra options passed to ``mkfs``. + +``TST_DEV_FS_OPTS`` + Extra filesystem-specific ``mkfs`` options. + +``TST_FS_TYPE`` + Filesystem type for formatting (default: ``ext2``). + +``TST_DEVICE_SIZE`` + Device size in MB. + +``TST_ALL_FILESYSTEMS`` + Set to 1 to repeat the test for each supported filesystem. + +``TST_SKIP_FILESYSTEMS`` + Space-separated list of filesystems to skip. + +``TST_MNT_PARAMS`` + Mount flags/options string. + +Miscellaneous (input) +~~~~~~~~~~~~~~~~~~~~~ + +``TST_SKIP_IN_LOCKDOWN`` + Set to 1 to skip when kernel lockdown is active. + +``TST_SKIP_IN_SECUREBOOT`` + Set to 1 to skip when Secure Boot is enabled. + +``TST_DISABLE_APPARMOR`` + Set to 1 to disable AppArmor before the test runs (requires root). + +``TST_DISABLE_SELINUX`` + Set to 1 to put SELinux in permissive mode before the test runs + (requires root). + +``TST_SKIP_LSM_WARNINGS`` + Set to 1 to suppress the library's warnings about active LSMs + (AppArmor, SELinux) at startup. + +``TST_NO_DEFAULT_RUN`` + Set to a non-empty value to source ``tst_test.sh`` without invoking + ``tst_run`` automatically. Useful for shell libraries that build on + top of the test API. + +``TST_TIMEOUT`` + Test timeout in seconds. + +``TST_TMPDIR_RHOST`` + Set to 1 to also clean up the temporary directory on the remote + host (used by network tests). + +Output variables +~~~~~~~~~~~~~~~~ + +``TST_TMPDIR`` + Path to the temporary directory (when ``TST_NEEDS_TMPDIR=1``). + +``TST_STARTWD`` + Original working directory before ``chdir`` to ``TST_TMPDIR``. + +``TST_DEVICE`` + Block device path (when ``TST_NEEDS_DEVICE=1``). + +``TST_MNTPOINT`` + Mount point path. + +``TST_MODPATH`` + Path to the loaded kernel module. + +Checkpoint functions +~~~~~~~~~~~~~~~~~~~~ + +``TST_CHECKPOINT_WAIT`` + Wait on checkpoint (argument: checkpoint id). + +``TST_CHECKPOINT_WAKE`` + Wake one waiter on checkpoint (argument: checkpoint id). + +``TST_CHECKPOINT_WAKE2`` + Wake multiple waiters (arguments: checkpoint id, count). + +``TST_CHECKPOINT_WAKE_AND_WAIT`` + Wake one waiter and then wait (argument: checkpoint id). + +Retry helpers +~~~~~~~~~~~~~ + +``TST_RETRY_FUNC`` + Retry a function until it succeeds or times out + (arguments: function, expected value). + +``TST_RETRY_FN_EXP_BACKOFF`` + Like ``TST_RETRY_FUNC`` with exponential backoff + (arguments: function, expected value, max delay).
doc/developers/writing_tests.rst +26 -2
@@ -382,6 +382,12 @@ LTP C And Shell Test API Comparison * - .dev_min_size - TST_DEVICE_SIZE + * - .filesystems + - \- + + * - .forks_child + - not applicable + * - .format_device - TST_FORMAT_DEVICE
@@ -399,21 +405,33 @@ LTP C And Shell Test API Comparison * - .min_mem_avail - not applicable - * - .mnt_flags - - TST_MNT_PARAMS + * - .min_runtime + - \- * - .min_swap_avail - not applicable + * - .mnt_flags + - TST_MNT_PARAMS + * - .mntpoint | .mnt_data - TST_MNTPOINT * - .mount_device - TST_MOUNT_DEVICE + * - .needs_abi_bits + - not applicable + * - .needs_cgroup_ctrls - \- + * - .needs_cgroup_nsdelegate + - \- + + * - .needs_cgroup_ver + - \- + * - .needs_checkpoints - TST_NEEDS_CHECKPOINTS
@@ -426,6 +444,9 @@ LTP C And Shell Test API Comparison * - .needs_device - TST_NEEDS_DEVICE + * - .needs_hugetlbfs + - \- + * - removed - TST_NEEDS_DRIVERS
@@ -453,6 +474,9 @@ LTP C And Shell Test API Comparison * - .restore_wallclock - not applicable + * - .runs_script + - not applicable + * - .sample - \-
Signature · 5 lines
2.51.0 -- Mailing list info: https://lists.linux.it/listinfo/ltp
PATCH v6 3/3 doc: Add SAFE_* macros reference page
In reply to Andrea CervesatoFrom: Andrea Cervesato <[email protected]>
Add doc/developers/api_safe_macros.rst listing all 245 SAFE_* wrapper macros grouped by header and category (file ops, memory, process, signals, networking, pthreads, IPC, cgroups, clocks, etc.).
This gives test writers a single reference page to discover available safe macros without grepping headers.
--- doc/developers/api_safe_macros.rst | 382 +++++++++++++++++++++++++++++++++++++ doc/index.rst | 4 + 2 files changed, 386 insertions(+)
doc/developers/api_safe_macros.rst new file +382 -0
@@ -0,0 +1,382 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later +.. Copyright (c) Linux Test Project, 2026 + +Safe macros reference +===================== + +LTP provides ``SAFE_*`` wrappers for common system calls and library +functions. Each wrapper calls the underlying function and, on failure, +invokes ``tst_brk(TBROK | TERRNO, ...)`` to abort the test. This +eliminates repetitive error-checking boilerplate. + +**When NOT to use SAFE_\* macros:** when the syscall is the *subject* +of the test (e.g. testing ``close()`` error paths). Use ``TEST()`` or +``TST_EXP_*`` macros instead. + +Core macros (tst_safe_macros.h) +------------------------------- + +File and directory operations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- ``SAFE_ACCESS(path, mode)`` +- ``SAFE_CHMOD(path, mode)`` +- ``SAFE_CHOWN(path, owner, group)`` +- ``SAFE_CHDIR(path)`` +- ``SAFE_CHROOT(path)`` +- ``SAFE_CREAT(path, mode)`` +- ``SAFE_FCHMOD(fd, mode)`` +- ``SAFE_FCHOWN(fd, owner, group)`` +- ``SAFE_GETCWD(buf, size)`` +- ``SAFE_LCHOWN(path, owner, group)`` +- ``SAFE_LINK(oldpath, newpath)`` +- ``SAFE_LINKAT(olddirfd, oldpath, newdirfd, newpath, flags)`` +- ``SAFE_MKDIR(path, mode)`` +- ``SAFE_MKFIFO(path, mode)`` +- ``SAFE_MKNOD(path, mode, dev)`` +- ``SAFE_READLINK(path, buf, bufsiz)`` +- ``SAFE_RENAME(oldpath, newpath)`` +- ``SAFE_RMDIR(path)`` +- ``SAFE_SYMLINK(target, linkpath)`` +- ``SAFE_SYMLINKAT(target, newdirfd, linkpath)`` +- ``SAFE_UNLINK(path)`` + +File descriptor operations +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- ``SAFE_CLOSE(fd)`` -- also sets ``fd = -1`` +- ``SAFE_DUP(oldfd)`` +- ``SAFE_DUP2(oldfd, newfd)`` +- ``SAFE_FCNTL(fd, cmd, ...)`` +- ``SAFE_FSYNC(fd)`` +- ``SAFE_OPEN(path, oflag, ...)`` +- ``SAFE_OPENDIR(name)`` +- ``SAFE_CLOSEDIR(dirp)`` +- ``SAFE_READDIR(dirp)`` +- ``SAFE_PIPE(pipefd)`` +- ``SAFE_PIPE2(pipefd, flags)`` +- ``SAFE_PTSNAME(fd)`` + +Reading and writing +~~~~~~~~~~~~~~~~~~~ + +- ``SAFE_READ(len_strict, fd, buf, count)`` +- ``SAFE_READV(fd, iov, iovcnt)`` +- ``SAFE_WRITE(len_strict, fd, buf, count)`` +- ``SAFE_WRITEV(fd, iov, iovcnt)`` + +Memory management +~~~~~~~~~~~~~~~~~ + +- ``SAFE_CALLOC(nmemb, size)`` +- ``SAFE_MALLOC(size)`` +- ``SAFE_MEMALIGN(alignment, size)`` +- ``SAFE_REALLOC(ptr, size)`` +- ``SAFE_MUNMAP(addr, length)`` +- ``SAFE_MLOCK(addr, len)`` +- ``SAFE_MUNLOCK(addr, len)`` +- ``SAFE_MPROTECT(addr, len, prot)`` +- ``SAFE_MSYNC(addr, length, flags)`` +- ``SAFE_MINCORE(addr, length, vec)`` + +Process management +~~~~~~~~~~~~~~~~~~ + +- ``SAFE_EXECL(path, arg, ...)`` +- ``SAFE_EXECLP(file, arg, ...)`` +- ``SAFE_EXECVP(file, argv)`` +- ``SAFE_KILL(pid, sig)`` +- ``SAFE_WAIT(status)`` +- ``SAFE_WAITPID(pid, status, opts)`` +- ``SAFE_GETPGID(pid)`` +- ``SAFE_SETPGID(pid, pgid)`` +- ``SAFE_SETSID()`` +- ``SAFE_PRCTL(option, ...)`` +- ``SAFE_PTRACE(request, pid, addr, data)`` +- ``SAFE_PIDFD_OPEN(pid, flags)`` + +User and group +~~~~~~~~~~~~~~ + +- ``SAFE_GETPWNAM(name)`` +- ``SAFE_GETGRNAM(name)`` +- ``SAFE_GETGRNAM_FALLBACK(name)`` +- ``SAFE_GETGRGID(gid)`` +- ``SAFE_GETGROUPS(size, list)`` +- ``SAFE_SETGROUPS(size, list)`` +- ``SAFE_SETUID(uid)`` +- ``SAFE_SETEUID(euid)`` +- ``SAFE_SETREUID(ruid, euid)`` +- ``SAFE_SETRESUID(ruid, euid, suid)`` +- ``SAFE_GETRESUID(ruid, euid, suid)`` +- ``SAFE_SETGID(gid)`` +- ``SAFE_SETEGID(egid)`` +- ``SAFE_SETREGID(rgid, egid)`` +- ``SAFE_SETRESGID(rgid, egid, sgid)`` +- ``SAFE_GETRESGID(rgid, egid, sgid)`` + +Signals +~~~~~~~ + +- ``SAFE_SIGACTION(signum, act, oldact)`` +- ``SAFE_SIGADDSET(set, signum)`` +- ``SAFE_SIGDELSET(set, signum)`` +- ``SAFE_SIGEMPTYSET(set)`` +- ``SAFE_SIGFILLSET(set)`` +- ``SAFE_SIGNAL(signum, handler)`` +- ``SAFE_SIGPROCMASK(how, set, oldset)`` +- ``SAFE_SIGWAIT(set, sig)`` + +Extended attributes +~~~~~~~~~~~~~~~~~~~ + +- ``SAFE_GETXATTR(path, name, value, size)`` +- ``SAFE_SETXATTR(path, name, value, size, flags)`` +- ``SAFE_REMOVEXATTR(path, name)`` +- ``SAFE_LSETXATTR(path, name, value, size, flags)`` +- ``SAFE_LREMOVEXATTR(path, name)`` +- ``SAFE_FSETXATTR(fd, name, value, size, flags)`` +- ``SAFE_FREMOVEXATTR(fd, name)`` + +Mounting +~~~~~~~~ + +- ``SAFE_MOUNT(source, target, filesystemtype, mountflags, data)`` +- ``SAFE_MOUNT2(source, target, filesystemtype, mountflags, data)`` +- ``SAFE_UMOUNT(target)`` + +Miscellaneous +~~~~~~~~~~~~~ + +- ``SAFE_BASENAME(path)`` +- ``SAFE_CMD(argv, stdout_path, stderr_path)`` +- ``SAFE_DIRNAME(path)`` +- ``SAFE_GETPRIORITY(which, who)`` +- ``SAFE_GETRUSAGE(who, usage)`` +- ``SAFE_IOCTL(fd, request, ...)`` +- ``SAFE_PERSONALITY(persona)`` +- ``SAFE_SETENV(name, value, overwrite)`` +- ``SAFE_SETNS(fd, nstype)`` +- ``SAFE_SSCANF(str, format, ...)`` +- ``SAFE_STATVFS(path, buf)`` +- ``SAFE_SYSCONF(name)`` +- ``SAFE_SYSINFO(info)`` +- ``SAFE_UNSHARE(flags)`` + +String conversion +~~~~~~~~~~~~~~~~~ + +- ``SAFE_STRTOL(str, min, max)`` +- ``SAFE_STRTOUL(str, min, max)`` +- ``SAFE_STRTOF(str, min, max)`` + +Inline macros (tst_safe_macros_inline.h) +---------------------------------------- + +- ``SAFE_FSTAT(fd, statbuf)`` +- ``SAFE_FTRUNCATE(fd, length)`` +- ``SAFE_GETRLIMIT(resource, rlim)`` +- ``SAFE_LSEEK(fd, offset, whence)`` +- ``SAFE_LSTAT(path, statbuf)`` +- ``SAFE_MMAP(addr, length, prot, flags, fd, offset)`` +- ``SAFE_POSIX_FADVISE(fd, offset, len, advice)`` +- ``SAFE_SETRLIMIT(resource, rlim)`` +- ``SAFE_STAT(path, statbuf)`` +- ``SAFE_STATFS(path, buf)`` +- ``SAFE_TRUNCATE(path, length)`` + +File content operations (tst_safe_file_ops.h) +---------------------------------------------- + +- ``SAFE_FILE_SCANF(path, fmt, ...)`` +- ``SAFE_FILE_LINES_SCANF(path, fmt, ...)`` +- ``SAFE_FILE_PRINTF(path, fmt, ...)`` +- ``SAFE_TRY_FILE_PRINTF(path, fmt, ...)`` +- ``SAFE_FILE_READ_STR(path, buf)`` +- ``SAFE_READ_MEMINFO(item)`` +- ``SAFE_READ_PROC_STATUS(pid, item)`` +- ``SAFE_CP(src, dst)`` +- ``SAFE_TOUCH(path, mode, times)`` +- ``SAFE_MOUNT_OVERLAY()`` + +File-at operations (tst_safe_file_at.h) +---------------------------------------- + +- ``SAFE_OPENAT(dirfd, path, oflag, ...)`` +- ``SAFE_FILE_READAT(dirfd, path, buf, bufsiz)`` +- ``SAFE_FILE_PRINTFAT(dirfd, path, fmt, ...)`` +- ``SAFE_UNLINKAT(dirfd, path, flags)`` +- ``SAFE_FCHOWNAT(dirfd, path, owner, group, flags)`` +- ``SAFE_FSTATAT(dirfd, path, statbuf, flags)`` + +Positioned I/O (tst_safe_prw.h) +--------------------------------- + +- ``SAFE_PREAD(len_strict, fd, buf, count, offset)`` +- ``SAFE_PREADV(fd, iov, iovcnt, offset)`` +- ``SAFE_PWRITE(len_strict, fd, buf, count, offset)`` +- ``SAFE_PWRITEV(fd, iov, iovcnt, offset)`` + +Networking (tst_safe_net.h) +---------------------------- + +- ``SAFE_SOCKET(domain, type, protocol)`` +- ``SAFE_SOCKETPAIR(domain, type, protocol, sv)`` +- ``SAFE_BIND(sockfd, addr, addrlen)`` +- ``SAFE_CONNECT(sockfd, addr, addrlen)`` +- ``SAFE_LISTEN(sockfd, backlog)`` +- ``SAFE_ACCEPT(sockfd, addr, addrlen)`` +- ``SAFE_SEND(sockfd, buf, len, flags)`` +- ``SAFE_SENDTO(sockfd, buf, len, flags, dest_addr, addrlen)`` +- ``SAFE_SENDMSG(sockfd, msg, flags)`` +- ``SAFE_RECV(sockfd, buf, len, flags)`` +- ``SAFE_RECVMSG(sockfd, msg, flags)`` +- ``SAFE_GETSOCKNAME(sockfd, addr, addrlen)`` +- ``SAFE_GETSOCKOPT(sockfd, level, optname, optval, optlen)`` +- ``SAFE_SETSOCKOPT(sockfd, level, optname, optval, optlen)`` +- ``SAFE_SETSOCKOPT_INT(sockfd, level, optname, value)`` +- ``SAFE_GETHOSTNAME(name, len)`` +- ``SAFE_SETHOSTNAME(name, len)`` +- ``SAFE_GETADDRINFO(node, service, hints, res)`` + +Pthreads (tst_safe_pthread.h) +------------------------------ + +- ``SAFE_PTHREAD_CREATE(thread, attr, start_routine, arg)`` +- ``SAFE_PTHREAD_JOIN(thread, retval)`` +- ``SAFE_PTHREAD_CANCEL(thread)`` +- ``SAFE_PTHREAD_KILL(thread, sig)`` +- ``SAFE_PTHREAD_BARRIER_INIT(barrier, attr, count)`` +- ``SAFE_PTHREAD_BARRIER_WAIT(barrier)`` +- ``SAFE_PTHREAD_BARRIER_DESTROY(barrier)`` +- ``SAFE_PTHREAD_MUTEX_INIT(mutex, attr)`` +- ``SAFE_PTHREAD_MUTEX_LOCK(mutex)`` +- ``SAFE_PTHREAD_MUTEX_TRYLOCK(mutex)`` +- ``SAFE_PTHREAD_MUTEX_TIMEDLOCK(mutex, abstime)`` +- ``SAFE_PTHREAD_MUTEX_UNLOCK(mutex)`` +- ``SAFE_PTHREAD_MUTEX_DESTROY(mutex)`` +- ``SAFE_PTHREAD_MUTEXATTR_INIT(attr)`` +- ``SAFE_PTHREAD_MUTEXATTR_SETTYPE(attr, type)`` +- ``SAFE_PTHREAD_MUTEXATTR_DESTROY(attr)`` + +Standard I/O (tst_safe_stdio.h) +-------------------------------- + +- ``SAFE_FOPEN(path, mode)`` +- ``SAFE_FREOPEN(path, mode, stream)`` +- ``SAFE_FCLOSE(stream)`` +- ``SAFE_FREAD(ptr, size, nmemb, stream)`` +- ``SAFE_FWRITE(ptr, size, nmemb, stream)`` +- ``SAFE_FFLUSH(stream)`` +- ``SAFE_FSEEK(stream, offset, whence)`` +- ``SAFE_FTELL(stream)`` +- ``SAFE_FILENO(stream)`` +- ``SAFE_POPEN(command, type)`` +- ``SAFE_ASPRINTF(strp, fmt, ...)`` + +SysV IPC (tst_safe_sysv_ipc.h) +-------------------------------- + +- ``SAFE_MSGGET(key, msgflg)`` +- ``SAFE_MSGSND(msqid, msgp, msgsz, msgflg)`` +- ``SAFE_MSGRCV(msqid, msgp, msgsz, msgtyp, msgflg)`` +- ``SAFE_MSGCTL(msqid, cmd, buf)`` +- ``SAFE_SEMGET(key, nsems, semflg)`` +- ``SAFE_SEMOP(semid, sops, nsops)`` +- ``SAFE_SEMCTL(semid, semnum, cmd, ...)`` +- ``SAFE_SHMGET(key, size, shmflg)`` +- ``SAFE_SHMAT(shmid, shmaddr, shmflg)`` +- ``SAFE_SHMDT(shmaddr)`` +- ``SAFE_SHMCTL(shmid, cmd, buf)`` + +POSIX IPC (tst_safe_posix_ipc.h) +---------------------------------- + +- ``SAFE_MQ_OPEN(name, oflag, ...)`` +- ``SAFE_MQ_CLOSE(mqdes)`` +- ``SAFE_MQ_SEND(mqdes, msg_ptr, msg_len, msg_prio)`` +- ``SAFE_MQ_NOTIFY(mqdes, sevp)`` +- ``SAFE_MQ_UNLINK(name)`` + +Clocks and timers (tst_safe_clocks.h) +-------------------------------------- + +- ``SAFE_CLOCK_GETRES(clk_id, res)`` +- ``SAFE_CLOCK_GETTIME(clk_id, tp)`` +- ``SAFE_CLOCK_SETTIME(clk_id, tp)`` +- ``SAFE_CLOCK_NANOSLEEP(clk_id, flags, request, remain)`` +- ``SAFE_TIMER_CREATE(clockid, sevp, timerid)`` +- ``SAFE_TIMER_SETTIME(timerid, flags, new_value, old_value)`` +- ``SAFE_TIMER_GETTIME(timerid, curr_value)`` +- ``SAFE_TIMER_DELETE(timerid)`` + +Timer file descriptors (tst_safe_timerfd.h) +-------------------------------------------- + +- ``SAFE_TIMERFD_CREATE(clockid, flags)`` +- ``SAFE_TIMERFD_SETTIME(fd, flags, new_value, old_value)`` +- ``SAFE_TIMERFD_GETTIME(fd, curr_value)`` + +io_uring (tst_safe_io_uring.h) +------------------------------- + +- ``SAFE_IO_URING_INIT(entries, params, ring)`` +- ``SAFE_IO_URING_ENTER(fd, to_submit, min_complete, flags, sig)`` +- ``SAFE_IO_URING_CLOSE(ring)`` + +Filesystem creation (tst_mkfs.h) +-------------------------------- + +- ``SAFE_MKFS(device, fs_type, fs_opts, extra_opts)`` + +Process creation (tst_clone.h, tst_test.h) +------------------------------------------ + +- ``SAFE_CLONE(args)`` +- ``SAFE_FORK()`` + +Control groups (tst_cgroup.h) +----------------------------- + +- ``SAFE_CG_HAS(cg, file_name)`` +- ``SAFE_CG_OPEN(cg, file_name, flags, fds)`` +- ``SAFE_CG_READ(cg, file_name, out, len)`` +- ``SAFE_CG_PRINT(cg, file_name, str)`` +- ``SAFE_CG_PRINTF(cg, file_name, fmt, ...)`` +- ``SAFE_CG_SCANF(cg, file_name, fmt, ...)`` +- ``SAFE_CG_LINES_SCANF(cg, file_name, fmt, ...)`` +- ``SAFE_CG_OCCURSIN(cg, file_name, needle)`` +- ``SAFE_CG_FCHOWN(cg, file_name, owner, group)`` + +Epoll (tst_epoll.h) +------------------- + +- ``SAFE_EPOLL_CREATE1(flags)`` +- ``SAFE_EPOLL_CTL(epfd, op, fd, ev)`` +- ``SAFE_EPOLL_WAIT(epfd, events, maxevents, timeout)`` + +Swap files (tse_swap.h) +----------------------- + +- ``SAFE_MAKE_SMALL_SWAPFILE(swapfile)`` +- ``SAFE_MAKE_SWAPFILE_SIZE(swapfile, size)`` +- ``SAFE_MAKE_SWAPFILE_BLKS(swapfile, blocks)`` + +Realtime signals (lapi/safe_rt_signal.h) +---------------------------------------- + +- ``SAFE_RT_SIGACTION(signum, act, oldact, sigsetsize)`` +- ``SAFE_RT_SIGPROCMASK(how, set, oldset, sigsetsize)`` + +Fallback syscall wrappers (include/lapi/) +----------------------------------------- + +- ``SAFE_STATX(dirfd, pathname, flags, mask, buf)`` +- ``SAFE_FCHMODAT2(dfd, filename, mode, flags)`` +- ``SAFE_SPLICE(fd_in, off_in, fd_out, off_out, len, flags)`` +- ``SAFE_KEYCTL(cmd, arg2, arg3, arg4, arg5)`` +- ``SAFE_USERFAULTFD(flags, retry)`` +- ``SAFE_MODIFY_LDT(func, ptr, bytecount)`` +- ``SAFE_LANDLOCK_CREATE_RULESET(attr, size, flags)`` +- ``SAFE_LANDLOCK_ADD_RULE(ruleset_fd, rule_type, rule_attr, flags)`` +- ``SAFE_LANDLOCK_RESTRICT_SELF(ruleset_fd, flags)``
doc/index.rst +4 -0
@@ -25,6 +25,7 @@ developers/writing_tests developers/test_case_tutorial developers/api_c_tests + developers/api_safe_macros developers/api_shell_tests developers/api_network_tests developers/api_kvm_tests
@@ -82,6 +83,9 @@ For developers :doc:`developers/api_c_tests` Walk through the C API features +:doc:`developers/api_safe_macros` + Reference of all ``SAFE_*`` wrapper macros + :doc:`developers/api_shell_tests` Walk through the Shell API features
Signature · 5 lines
2.51.0 -- Mailing list info: https://lists.linux.it/listinfo/ltp