Complete the documentation adding missing headers
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
---
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 | 326 +++++++++++++++++++++++++++++++++++++ doc/developers/api_shell_tests.rst | 163 +++++++++++++++++++ doc/developers/writing_tests.rst | 28 +++- doc/index.rst | 4 + include/tse_uinput.h | 30 ++-- include/tst_clone.h | 23 ++- include/tst_device.h | 165 ++++++++++++------- include/tst_fuzzy_sync.h | 163 +++++++++++++------ include/tst_hugepage.h | 35 ++-- include/tst_kconfig.h | 77 ++++----- include/tst_taint.h | 32 ++-- 12 files changed, 896 insertions(+), 221 deletions(-)
---
base-commit: 2ee13a3772ae4942597afa615b3cb411d380db86
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 1/3 doc: Add missing API references to api_c_tests.rst
From: Andrea Cervesato <[email protected]>
Fix broken kernel-doc reference to renamed tse_numa.h header and add kernel-doc directives for 12 headers that were missing from the C API documentation page:
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, tse_numa.h, tse_swap.h, tse_uinput.h
Convert plain comments to kernel-doc format in tst_device.h, tst_hugepage.h, tst_clone.h, and tst_taint.h so the documentation builder can extract them.
Sort all sections alphabetically under LTP C API.
--- doc/developers/api_c_tests.rst | 71 +++++++++++++----- include/tse_uinput.h | 30 ++++---- include/tst_clone.h | 23 ++++-- include/tst_device.h | 165 ++++++++++++++++++++++++++--------------- include/tst_fuzzy_sync.h | 163 ++++++++++++++++++++++++++++------------ include/tst_hugepage.h | 35 ++++++--- include/tst_kconfig.h | 77 +++++++++---------- include/tst_taint.h | 32 +++----- 8 files changed, 377 insertions(+), 219 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 +15 -8
@@ -9,7 +9,13 @@ #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: If CLONE_PIDFD is set, stores the pidfd here. + * @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 +23,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 +106 -59
229 lines not on this page · raw message
include/tst_fuzzy_sync.h +115 -48
365 lines not on this page · raw message
include/tst_hugepage.h +25 -10
@@ -19,6 +19,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 ,
@@ -26,30 +31,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 +35 -42
121 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] [PATCH 1/3] doc: Add missing API references to api_c_tests.rst
Hi Andrea,
Quoted 1 line
Fix broken kernel-doc reference to renamed
tse_numa.hheader and add
Not only this patch but none of the other two actually fixes it. I suppose you forget to amend git commit.
How about to fix this one in a separate commit (which you can merge right now, no need to even send it to ML) with the usual tag?
Specially because Cyril might want to review if all the docs is correct (which takes time).
Also there are still some unresolved problems, but we can fix it afterwards:
include/tst_test.h:302: WARNING: undefined label: 'struct tst_option' include/tst_test.h:325: WARNING: undefined label: 'struct tst_device' include/tst_test.h:361: WARNING: undefined label: 'struct tst_device' include/tst_test.h:502: WARNING: undefined label: 'struct tst_path_val' include/tst_test.h:523: WARNING: undefined label: 'struct tst_buffers' include/tst_test.h:528: WARNING: undefined label: 'struct tst_cap' include/tst_test.h:531: WARNING: undefined label: 'struct tst_tag' include/tst_test.h:533: WARNING: undefined label: 'struct tst_cmd' include/tst_kvercmp.h:97: WARNING: undefined label: 'struct tst_kern_exv' doc/developers/api_shell_tests.rst:30: WARNING: undefined label: 'struct tst_test' doc/developers/test_case_tutorial.rst:140: WARNING: undefined label: 'struct tst_test' doc/developers/todo.rst:62: WARNING: undefined label: 'struct tst_test' doc/developers/writing_tests.rst:141: WARNING: undefined label: 'struct tst_test' doc/developers/writing_tests.rst:364: WARNING: undefined label: 'struct tst_test' doc/developers/writing_tests.rst:558: WARNING: undefined label: 'struct tst_device'
Generally changes are good, thanks for finishing the transition. With fixed tse_numa.h (preferably in a separate commit) you may add:
Quoted 7 lines
kernel-doc directives for 12 headers that were missing from the C API documentation page:
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,tse_numa.h,tse_swap.h,tse_uinput.h
Quoted 5 lines
Convert plain comments to kernel-doc format in
tst_device.h,tst_hugepage.h,tst_clone.h, andtst_taint.hso the documentation builder can extract them.Sort all sections alphabetically under LTP C API.
FYI I quite liked that Core API was the first, but ok with the move.
Kind regards,
Petr
Signature · 1 line
Mailing list info: https://lists.linux.it/listinfo/ltp
Re: [LTP] [PATCH 1/3] doc: Add missing API references to api_c_tests.rst
Hi Petr,
as mentioned inside the cover letter, this patch-set has to be added on top of the " [PATCH 0/4] Fix documentation issues " patch-set. Once done that it won't have issues anymore with warnings etc.
Quoted 48 lines
Hi Andrea,
Quoted 1 line
Fix broken kernel-doc reference to renamed
tse_numa.hheader and addNot only this patch but none of the other two actually fixes it. I suppose you forget to amend git commit.
How about to fix this one in a separate commit (which you can merge right now, no need to even send it to ML) with the usual tag?
Fixes eef750db28 ("libs: adopt tse_ prefix for extended (non-core) library")Specially because Cyril might want to review if all the docs is correct (which takes time).
Also there are still some unresolved problems, but we can fix it afterwards:
include/tst_test.h:302: WARNING: undefined label: 'structtst_option'include/tst_test.h:325: WARNING: undefined label: 'structtst_device'include/tst_test.h:361: WARNING: undefined label: 'structtst_device'include/tst_test.h:502: WARNING: undefined label: 'structtst_path_val'include/tst_test.h:523: WARNING: undefined label: 'structtst_buffers'include/tst_test.h:528: WARNING: undefined label: 'structtst_cap'include/tst_test.h:531: WARNING: undefined label: 'structtst_tag'include/tst_test.h:533: WARNING: undefined label: 'structtst_cmd'include/tst_kvercmp.h:97: WARNING: undefined label: 'structtst_kern_exv'doc/developers/api_shell_tests.rst:30: WARNING: undefined label: 'structtst_test'doc/developers/test_case_tutorial.rst:140: WARNING: undefined label: 'structtst_test'doc/developers/todo.rst:62: WARNING: undefined label: 'structtst_test'doc/developers/writing_tests.rst:141: WARNING: undefined label: 'structtst_test'doc/developers/writing_tests.rst:364: WARNING: undefined label: 'structtst_test'doc/developers/writing_tests.rst:558: WARNING: undefined label: 'structtst_device'Generally changes are good, thanks for finishing the transition. With fixed
tse_numa.h(preferably in a separate commit) you may add:Reviewed-by Petr Vorel <[email protected]>Quoted 10 lines
kernel-doc directives for 12 headers that were missing from the C API documentation page:
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,tse_numa.h,tse_swap.h,tse_uinput.hConvert plain comments to kernel-doc format in
tst_device.h,tst_hugepage.h,tst_clone.h, andtst_taint.hso the documentation builder can extract them.
Quoted 6 lines
Quoted 1 line
Sort all sections alphabetically under LTP C API.
FYI I quite liked that Core API was the first, but ok with the move.
Kind regards,
Petr
--
Andrea Cervesato
SUSE QE Automation Engineer Linux
[email protected]
Signature · 1 line
Mailing list info: https://lists.linux.it/listinfo/ltp
Re: [LTP] [PATCH 1/3] doc: Add missing API references to api_c_tests.rst
Hi Andrea,
Quoted 6 lines
Hi Petr,
as mentioned inside the cover letter, this patch-set has to be added on top of the " [PATCH 0/4] Fix documentation issues " patch-set. Once done that it won't have issues anymore with warnings etc.
Thanks for a hint.
Quoted 3 lines
Quoted 3 lines
Hi Andrea,
Quoted 1 line
Fix broken kernel-doc reference to renamed
tse_numa.hheader and add
But in that case this part of the commit message is wrong.
Kind regards,
Petr
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,
Thank you for this documentation series. The kernel-doc conversions and new reference pages are a welcome addition. However, several commit message claims do not match what the patches actually implement, and there are technical issues in tst_fuzzy_sync.h that need to be fixed before merging.
---
[PATCH 1/3] doc: Add missing API references to api_c_tests.rst 04e9aa97059d1301f10954322074c7cb3d9fdd53
--- Commit message ---
Quoted 1 line
Fix broken kernel-doc reference to renamed
tse_numa.hheader
This claim is false. The api_c_tests.rst NUMA section still references ../../include/tst_numa.h (which does not exist) in both master and HEAD:
$ cat doc/developers/api_c_tests.rst | grep -n numa 73:NUMA 75:.. kernel-doc:: ../../include/tst_numa.h
The actual file is include/tse_numa.h. The reference was not corrected by this patch.
Quoted 2 lines
Convert plain comments to kernel-doc format in
tst_device.h,tst_hugepage.h,tst_clone.h, andtst_taint.h
tst_fuzzy_sync.h also receives kernel-doc conversions (old @param/@return Doxygen style → new function() - description / @param: style) but is not mentioned here.
--- include/tst_fuzzy_sync.h ---
The patch adds new-style kernel-doc parameters to several functions but fails to remove the old Doxygen-style @param / @return lines. This leaves duplicate, conflicting documentation in the following functions:
tst_exp_moving_avg():
/**
* tst_exp_moving_avg() - Exponential moving average.
* @alpha: Smoothing factor. ← new style
* @sample: New sample value.
* @prev_avg: Previous average.
*
* Return: New average.
*
* @param alpha The preference for recent samples over old ones. ← stale * @param sample The current sample ← stale * @param prev_avg The average of the all the previous samples ← stale
*
* @return The average including the current sample. ← stale
*/
@param alpha and @param sample were removed by the patch, but @param prev_avg and @return were not. They should be removed.
tst_fzsync_pair_reset():
/**
* tst_fzsync_pair_reset() - Reset or initialise fzsync.
* @pair: Fuzzy sync pair. ← new style
* @run_b: Thread B function pointer.
*
* @relates tst_fzsync_pair
* @param pair The state structure initialised with TST_FZSYNC_PAIR_INIT. ← stale
* @param run_b The function defining thread B or NULL. ← stale
*/
@param pair and @param run_b were not removed. They should be removed.
tst_fzsync_pair_wait():
/**
* tst_fzsync_pair_wait() - Wait for the other thread.
* @our_cntr: Our atomic counter. ← new style
* @other_cntr: Other thread's atomic counter.
* @spins: Spin counter.
* @exit: Exit flag.
* @yield_in_wait: Whether to yield while waiting. *
* @relates tst_fzsync_pair
* @param our_cntr The counter for the thread we are on ← stale * @param other_cntr ... ← stale * @param spins ... ← stale * @param exit ... ← stale
* ...
* @return A non-zero value if the thread should continue ← stale */
All four @param lines and the @return line were not removed.
tst_fzsync_run_a():
/**
* tst_fzsync_run_a() - Decide whether to continue running thread A.
* @pair: Fuzzy sync pair.
*
* Return: Non-zero to continue, 0 to stop. ← new style
*
* ...
* @return True to continue and false to break. ← stale, not removed */
tst_fzsync_pair_add_bias():
/**
* tst_fzsync_pair_add_bias() - Add some amount to the delay bias.
* @pair: Fuzzy sync pair.
* @change: Amount to add to bias. ← new style
*
* @relates tst_fzsync_pair
* @param change The amount to add, can be negative ← stale, not removed */
All stale @param / @return / @relates lines left after the conversion should be removed.
---
[PATCH 2/3] doc: Complete struct tst_test table and shell API docs f1c9189e4415389807671809f27d2b922e36e99b
--- Commit message ---
The body describes four fixes to writing_tests.rst that are NOT present in the patch:
1. ".max_runtime -> .runtime (renamed in a6a369c5eeb4)"
Not done. writing_tests.rst still has:
* - .max_runtime
- TST_TIMEOUT ...
The actual struct field is int runtime (include/tst_test.h:599). The table entry should be .runtime, not .max_runtime.
2. ".tst_hugepage -> .hugepages (actual field name)"
Not done. writing_tests.rst still has:
* - .tst_hugepage
- not applicable
The actual struct field is struct tst_hugepage hugepages (include/tst_test.h:586). The table entry should be .hugepages.
3. ".dev_extra_opts, .dev_fs_opts, .dev_fs_type are shell-only variables, not C struct fields; move them to the 'not applicable' section"
Not done. These three rows remain unchanged in the table, still listed as if they were C struct fields. None of these names appear in include/tst_test.h.
4. "Add 10 missing struct tst_test fields"
Only 8 fields are added: .filesystems, .forks_child, .min_runtime, .needs_abi_bits, .needs_cgroup_nsdelegate, .needs_cgroup_ver, .needs_hugetlbfs, .runs_script. The commit body also lists exactly 8 names. The subject and body should say 8, not 10.
The commit message must be corrected to describe only what the patch actually does, and the four unimplemented fixes above must either be implemented or dropped from the description.
---
[PATCH 3/3] doc: Add SAFE_* macros reference pagec9f08715e5e82b5a07d355c6c26313e4608cb3e4
--- doc/developers/api_safe_macros.rst ---
Quoted 1 line
+.. Copyright (c) Linux Test Project, 2025
This file is being created in 2026; the year should be 2026 (or 2025-2026 if the content dates to 2025, but for a new file 2026 is appropriate). Compare api_c_tests.rst which uses "2024-2025".
Quoted 1 line
+- ``SAFE_MMAP(addr, length, prot, flags, fd, offset)``
This line appears in the "Core macros (tst_safe_macros.h)" Memory management section. However, SAFE_MMAP is defined only in include/tst_safe_macros_inline.h, not in tst_safe_macros.h. It is also correctly listed in the "Inline macros (tst_safe_macros_inline.h)" section. Remove the duplicate entry from the core macros section; it belongs only under "Inline macros".
Because of this duplicate, the "all 217 SAFE_* wrapper macros" claim in the subject overstates by one; there are 216 unique macros. The count and subject line should be corrected after removing the duplicate.
---
Verdict: Needs revision
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
Sigh, I should have sent this one with the previous documentation fix patch-set . I will do it in the next iteration.
--
Andrea Cervesato
SUSE QE Automation Engineer Linux
[email protected]
Signature · 1 line
Mailing list info: https://lists.linux.it/listinfo/ltp
Re: [LTP] [PATCH 1/3] doc: Add missing API references to api_c_tests.rst
In reply to Andrea CervesatoHi!
Quoted 1 line
Fix broken kernel-doc reference to renamed
tse_numa.hheader and add
That was actually fixed in the first patch of the previous patchset.
Signature · 5 lines
Cyril Hrubis [email protected] -- Mailing list info: https://lists.linux.it/listinfo/ltp
PATCH 2/3 doc: Complete struct tst_test table and shell API docs
In reply to Andrea CervesatoFrom: Andrea Cervesato <[email protected]>
Fix incorrect field names in the C/Shell API comparison table in writing_tests.rst:
- .max_runtime -> .runtime (renamed in a6a369c5eeb4)
- .tst_hugepage -> .hugepages (actual field name)
- .dev_extra_opts, .dev_fs_opts, .dev_fs_type are shell-only variables, not C struct fields; move them to the 'not applicable' section
Add 10 missing struct tst_test fields to the table: .filesystems, .forks_child, .min_runtime, .needs_abi_bits, .needs_cgroup_nsdelegate, .needs_cgroup_ver, .needs_hugetlbfs, .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 | 163 +++++++++++++++++++++++++++++++++++++ doc/developers/writing_tests.rst | 28 ++++++- 2 files changed, 189 insertions(+), 2 deletions(-)
doc/developers/api_shell_tests.rst +163 -0
@@ -93,3 +93,166 @@ 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_TIMEOUT`` + Test timeout in seconds. + +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,12 +405,15 @@ 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
@@ -414,6 +423,12 @@ LTP C And Shell Test API Comparison * - .needs_cgroup_ctrls - \- + * - .needs_cgroup_nsdelegate + - \- + + * - .needs_cgroup_ver + - \- + * - .needs_checkpoints - TST_NEEDS_CHECKPOINTS
@@ -426,6 +441,9 @@ LTP C And Shell Test API Comparison * - .needs_device - TST_NEEDS_DEVICE + * - .needs_hugetlbfs + - \- + * - removed - TST_NEEDS_DRIVERS
@@ -438,6 +456,9 @@ LTP C And Shell Test API Comparison * - .needs_rofs - \- + * - .needs_abi_bits + - not applicable + * - .needs_root - TST_NEEDS_ROOT
@@ -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
Re: [LTP] [PATCH 2/3] doc: Complete struct tst_test table and shell API docs
Hi Andrea, Cyril, Li,
@Andrea I'd say you mixed 2 APIs: tst_test.sh API (used to be "the new API" but now deprecated by shell loader) and shell loader API. And here come problems.
Quoted 7 lines
Fix incorrect field names in the C/Shell API comparison table in
writing_tests.rst:- .max_runtime -> .runtime (renamed in
a6a369c5eeb4)
- .tst_hugepage -> .hugepages (actual field name)
- .dev_extra_opts, .dev_fs_opts, .dev_fs_type are shell-only variables, not C struct fields; move them to the 'not applicable' section
This part which fixes tst_test.c renames I'd merge right now.
But the rest which is in api_shell_tests.rst it's IMHO wrong because they are for tst_test.sh.
The problem is that since 3c82316c53 ("doc: Add basic shell test description") we consider doc/developers/api_shell_tests.html home for shell loader. See Cyril's feedback to not put there tst_test.sh doc [1]. That's why I rejected my older patch converting tst_test.sh doc to the old file.
but that approach in 3c82316c53 wasn't consistent, because other doc still consider as shell API tst_test.sh:
* doc/developers/ltp_library.rst (mentions tst_test.sh, tst_security.sh and tst_net.sh)
* doc/users/setup_tests.rst (comparison table)
* testcases/network/README.md (git source only, not part of readthedocs)
* Old github doc in doc/old/
@All We should fix it. So what are we going to do with tst_test.sh doc? Maybe admit tst_test.sh etc exists in doc/developers/ltp_library.rst, but document that shell loader is way to go?
And I wonder if the comparison table in doc/developers/api_shell_tests.rst should be deleted or we should put a note that this API is deprecated and users should use shell loader (clickable link to doc/developers/api_shell_tests.html).
And yes, we should probably convert lib/README.md and testcases/network/README.md to sphinx doc, but that's a completely different problem.
[1] https://lore.kernel.org/ltp/[email protected]/
[2] https://lore.kernel.org/ltp/[email protected]/
doc/developers/api_shell_tests.rst
Quoted 19 lines
Add 10 missing struct
tst_testfields to the table: .filesystems, .forks_child, .min_runtime, .needs_abi_bits, .needs_cgroup_nsdelegate, .needs_cgroup_ver, .needs_hugetlbfs, .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.Signed-off-by Andrea Cervesato <[email protected]>--- doc/developers/api_shell_tests.rst | 163 +++++++++++++++++++++++++++++++++++++ doc/developers/writing_tests.rst | 28 ++++++- 2 files changed, 189 insertions(+), 2 deletions(-)doc/developers/api_shell_tests.rst +0
-0
FYI given the above this doc is for a shell loader....
doc/developers/api_shell_tests.rst interrupted by :ref:`tst_brk`. · line 101
Quoted 10 lines
doc/developers/api_shell_tests.rst +6
-0@@ -93,3 +93,166 @@ 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
nit: could you please use clickable link to sources?
:shell_lib:tst_run.sh (Cyril preferred it over :master:testcases/lib/tst_run.sh).
I dared to merge more rename now:016134bf31 ("doc: Use shell_lib prefix to shorten printed file path")
doc/developers/api_shell_tests.rst interrupted by :ref:`tst_brk`. · line 105
Quoted 4 lines
doc/developers/api_shell_tests.rst +4
-0+marked *output* are set by the library for tests to read. + +Test definition (input) +~~~~~~~~~~~~~~~~~~~~~~~
nit: I'd remove "(input(". I did not get what you mean.
... which means many of these below aren't (yet) supported in shell loader. ATM we support only TST_SETUP and TST_CLEANUP. Test function must be named tst_test().
And my WIP "shell loader fixes + du01.sh rewrite"
[3] https://patchwork.ozlabs.org/project/ltp/list/?series=495792&state=*
Quoted 23 lines
doc/developers/api_shell_tests.rst +23
-0+ +``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.
doc/developers/api_shell_tests.rst interrupted by :ref:`tst_brk`. · line 138
Quoted 10 lines
doc/developers/api_shell_tests.rst +10
-0+ +``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).
To be honest, if
Quoted 110 lines
doc/developers/api_shell_tests.rst +110
-0+ +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_TIMEOUT`` + Test timeout in seconds. + +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). +
doc/developers/api_shell_tests.rst interrupted by :ref:`tst_brk`. · line 258
Quoted 10 lines
doc/developers/api_shell_tests.rst +10
-0+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).
To be honest if we want to document tst_test.sh, I'd prefer the examples in my original patch [2].
Quoted 69 lines
doc/developers/writing_tests.rst +23
-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,12 +405,15 @@ 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@@ -414,6 +423,12 @@ LTP C And Shell Test API Comparison * - .needs_cgroup_ctrls - \- + * - .needs_cgroup_nsdelegate + - \- + + * - .needs_cgroup_ver + - \- + * - .needs_checkpoints - TST_NEEDS_CHECKPOINTS@@ -426,6 +441,9 @@ LTP C And Shell Test API Comparison * - .needs_device - TST_NEEDS_DEVICE + * - .needs_hugetlbfs + - \- + * - removed - TST_NEEDS_DRIVERS@@ -438,6 +456,9 @@ LTP C And Shell Test API Comparison * - .needs_rofs - \- + * - .needs_abi_bits + - not applicable + * - .needs_root - TST_NEEDS_ROOT
doc/developers/writing_tests.rst LTP C And Shell Test API Comparison · line 481
Quoted 8 lines
doc/developers/writing_tests.rst +3
-0@@ -453,6 +474,9 @@ LTP C And Shell Test API Comparison * - .restore_wallclock - not applicable + * - .runs_script + - not applicable + * - .sample - \-
And until we decide, I'm ok to update writing_tests.rst (i.e. merge writing_tests.rst part).
Kind regards,
Petr
Signature · 1 line
Mailing list info: https://lists.linux.it/listinfo/ltp
PATCH 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 217 SAFE_* wrapper macros grouped by header and category (file ops, memory, process, signals, networking, pthreads, IPC, clocks, etc.).
This gives test writers a single reference page to discover available safe macros without grepping headers.
--- doc/developers/api_safe_macros.rst | 326 +++++++++++++++++++++++++++++++++++++ doc/index.rst | 4 + 2 files changed, 330 insertions(+)
doc/developers/api_safe_macros.rst new file +326 -0
@@ -0,0 +1,326 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later +.. Copyright (c) Linux Test Project, 2025 + +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_MMAP(addr, length, prot, flags, fd, offset)`` +- ``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)``
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