[LTP] [PATCH 2/9] doc: Correct guide and API descriptions
Andrea Cervesato
andrea.cervesato@suse.de
Thu Sep 10 10:33:42 CEST 2026
From: Andrea Cervesato <andrea.cervesato@suse.com>
Fix tutorial command options, the cleanup descriptor handling example,
and typo fixes. Correct the CPP variable name in the build system guide
and fix grammar and section references in INSTALL. Complete the argv
documentation for tst_cmd(), fix /proc paths and exit condition in
process state documentation, and correct comparison macro and NUMA types.
Signed-off-by: Andrea Cervesato <andrea.cervesato@suse.com>
---
INSTALL | 10 +++++-----
doc/developers/build_system.rst | 2 +-
doc/developers/test_case_tutorial.rst | 25 ++++++++++++++-----------
include/tse_numa.h | 2 +-
include/tst_cmd.h | 2 ++
include/tst_process_state.h | 8 ++++----
include/tst_test_macros.h | 24 ++++++++++++------------
7 files changed, 39 insertions(+), 34 deletions(-)
diff --git a/INSTALL b/INSTALL
index b5c89de32..2a6b5aac2 100644
--- a/INSTALL
+++ b/INSTALL
@@ -113,7 +113,7 @@ groups. If these IDs do not exist, certain tests will fail. The respective
user and group IDs should be the same, i.e. if `nobody's' user ID is 99, then
its group ID should also be 99. The names of the groups are irrelevant.
- The installation directory is /opt/ltp by default. Please see
-"Using autoconf" above and specify the appropriate path via --prefix.
+"Configuration" above and specify the appropriate path via --prefix.
DESTDIR= is also honored for install and will install into $DESTDIR/$prefix,
if you want to install into a chroot or a rootfs for instance.
@@ -139,7 +139,7 @@ contributions are welcome.
3. Build and install everything, as described above. Note the minimum software
requirements above before doing so.
-4. The network tests related installation see testcases/network/README.md.
+4. For network test installation, see testcases/network/README.md.
Cross compiling
---------------
@@ -150,7 +150,7 @@ For correct pkgconf / pkg-config detection you need to set
PKG_CONFIG_SYSROOT_DIR=$SYSROOT
After configure has run, it will generate include/mk/config.mk. You can tweak
-settings in there if need be, but you should not specificy settings on the
+settings in there if need be, but you should not specify settings on the
command-line when running make.
32 bit build on 64 bit machine
@@ -161,7 +161,7 @@ You need to set CFLAGS=-m32 LDFLAGS=-m32 and PKG_CONFIG_LIBDIR
* RPM based distributions (openSUSE, Fedora, etc.)
PKG_CONFIG_LIBDIR=/usr/lib/pkgconfig CFLAGS=-m32 LDFLAGS=-m32 ./configure
-* Debian / Ubuntu and derivates
+* Debian / Ubuntu and derivatives
PKG_CONFIG_LIBDIR=/usr/lib/i386-linux-gnu/pkgconfig CFLAGS=-m32 LDFLAGS=-m32 ./configure
* Arch Linux
@@ -174,7 +174,7 @@ LTP contains few kernel modules and tests which are using them.
These require to be built with the same kernel headers as the running kernel (SUT).
Sometimes the best way to achieve this is to compile them on the SUT.
-Due Linux Kernel Driver Interface unstability [1], error during building kernel
+Due to Linux Kernel Driver Interface instability [1], an error during building kernel
modules does not break the build. Make errors fatal can be done by FORCE_MODULES=1
make variable.
diff --git a/doc/developers/build_system.rst b/doc/developers/build_system.rst
index 8af431517..e62db7d97 100644
--- a/doc/developers/build_system.rst
+++ b/doc/developers/build_system.rst
@@ -135,7 +135,7 @@ been fulfilled (libraries, headers, etc).
* - $(CC)
- The system C compiler
- * - $(CCP)
+ * - $(CPP)
- The system C preprocessor
* - $(CFLAGS)
diff --git a/doc/developers/test_case_tutorial.rst b/doc/developers/test_case_tutorial.rst
index 930e0f989..5e0736f49 100644
--- a/doc/developers/test_case_tutorial.rst
+++ b/doc/developers/test_case_tutorial.rst
@@ -205,7 +205,7 @@ please do:
This should build the test and then run it. However, even though the test is
in :master:`testcases/kernel/syscalls` directory it won't be automatically run
-as part of the syscalls test group (e.g. not run via ``kirk -f math``).
+as part of the syscalls test group (e.g. not run via ``kirk -f syscalls``).
For this we need to add it to the runtest file. So open :master:`runtest/syscalls`
and add the lines starting with a ``+``.
@@ -292,7 +292,7 @@ Check coding style with ``make check``.
Install the LTP and run the test with runtest
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Run ``statx01`` on its own, also using ``-I0`` amd ``-I10``.
+Run ``statx01`` on its own, also using ``-i 10`` and ``-I 10``.
Call the system call
--------------------
@@ -435,7 +435,7 @@ there is a system in place to handle it.
.min_kver = "4.11",
};
-The ``TEST`` macro sets ``TST_RET`` to the return value of ``tst_statx()`` and
+The ``TEST`` macro sets ``TST_RET`` to the return value of ``sys_statx()`` and
``TST_ERR`` to the value of ``errno`` immediately after the functions
return. This is mainly just for convenience, although it potentially could
have other uses.
@@ -589,6 +589,9 @@ again on the hard-link, then ``stat`` the file".
#define LNAME "file_to_stat_link"
+ static int fd = -1;
+ static int lfd = -1;
+
...
static void setup(void)
@@ -600,10 +603,10 @@ again on the hard-link, then ``stat`` the file".
static void cleanup(void)
{
- if (lfd != 0)
+ if (lfd != -1)
SAFE_CLOSE(lfd);
- if (fd != 0)
+ if (fd != -1)
SAFE_CLOSE(fd);
}
@@ -646,8 +649,8 @@ Nor do we want to call ``cleanup`` recursively. So during ``cleanup``
``tst_brk``, and consequently the ``SAFE`` functions, do not cause the test to
exit with ``TBROK``. Instead they just print an error message with ``TWARN``.
-It is not entirely necessary to check if the file descriptors have a none zero
-value before attempting to close them. However it avoids a bunch of spurious
+It is not entirely necessary to check if the file descriptors are not -1
+before attempting to close them. However it avoids a bunch of spurious
warning messages if we fail to open ``file_to_stat``. Test case failures can be
difficult to interpret at the best of times, so avoid filling the log with
noise.
@@ -804,7 +807,7 @@ branch is ``tutorial-rebase2`` which I just created. I have already done one
``tutorial``.
As usual my commit history is starting to look like a bit of mess! There is
-even a commit in there which should not be in the this branch (Remove old API
+even a commit in there which should not be in this branch (Remove old API
argument), however it can be ignored for now and 'cherry picked' into a new branch
later.
@@ -821,7 +824,7 @@ of all I want to 'squash' (amalgamate) all the commits appended with
This begins an interactive ``rebase`` where commit ``5ca6427b78`` is the earliest
commit we want to edit. The ``^`` symbol after the commit hash, specifies the
commit before this one. The interactive ``rebase`` command takes the last commit
-we want to keep unaltered as it's argument (in other words it takes a
+we want to keep unaltered as its argument (in other words it takes a
non-inclusive range).
Upon entering a similar command you will be presented with a text file
@@ -993,8 +996,8 @@ Obviously testing the patch is one way of finding errors. You can apply patches
using :manpage:`git-am(1)`. Then it is just a case of compiling and running the
tests.
-Finally, reading and attempting to comment on other peoples patches, gives
-you a better understanding of the reviewers perspective. This is better for
+Finally, reading and attempting to comment on other people's patches, gives
+you a better understanding of the reviewer's perspective. This is better for
the project and for you.
Style and organizational issues are best left to after you have found logical
diff --git a/include/tse_numa.h b/include/tse_numa.h
index 839512b2a..4cbef63b7 100644
--- a/include/tse_numa.h
+++ b/include/tse_numa.h
@@ -109,7 +109,7 @@ enum tse_numa_types {
* tse_get_nodemap() - Allocates and returns numa node map, which is an array of numa nodes which
* contain desired resources e.g. memory.
*
- * @type: Bitflags of enum tst_numa_types specifying desired resources.
+ * @type: Bitflags of enum tse_numa_types specifying desired resources.
* @min_mem_kb: Minimal free RAM on memory nodes, if given node has less than
* requested amount of free+buffers memory it's not included in
* the resulting list of nodes.
diff --git a/include/tst_cmd.h b/include/tst_cmd.h
index 77fbbbc86..4829d0aed 100644
--- a/include/tst_cmd.h
+++ b/include/tst_cmd.h
@@ -72,6 +72,8 @@ static inline int tst_cmd_fds(const char *const argv[],
* tst_cmd() - Executes tst_cmd_fds() and redirects its output to a file.
*
* @argv: A list of two (at least program name + NULL) or more pointers that
+ * represent the argument list to the new program. The array of pointers
+ * must be terminated by a NULL pointer.
* @stdout_path: Path where to redirect stdout. Set NULL if redirection is
* not needed.
* @stderr_path: Path where to redirect stderr. Set NULL if redirection is
diff --git a/include/tst_process_state.h b/include/tst_process_state.h
index b0f640b06..674c54b0f 100644
--- a/include/tst_process_state.h
+++ b/include/tst_process_state.h
@@ -22,7 +22,7 @@
* @state: A state to wait for.
* @msec_timeout: A timeout for the wait.
*
- * Polls `/proc/$PID/state` for a process state changes.
+ * Polls `/proc/$PID/stat` for process state changes.
*
* Possible process states (see :manpage:`ps(1)`):
*
@@ -32,7 +32,7 @@
* - **Z** Zombie process.
* - **T** Process is traced.
* - **t** Tracing stopped.
- * - **X** Process id dead.
+ * - **X** Process is dead.
*/
#define TST_PROCESS_STATE_WAIT(pid, state, msec_timeout) \
tst_process_state_wait(__FILE__, __LINE__, NULL, \
@@ -41,7 +41,7 @@
/**
* TST_PROCESS_EXIT_WAIT() - Waits while pid is present on the system.
*
- * Loops until `kill($PID, 0)` succeds or timeout is reached.
+ * Loops until `kill($PID, 0)` fails with `ESRCH`, or timeout is reached.
*
* @pid: A process pid.
* @msec_timeout: A timeout for the wait.
@@ -52,7 +52,7 @@
/**
* TST_THREAD_STATE_WAIT() - Waits for a thread state change.
*
- * Polls `/proc/self/task/$TID/state` for a thread state change.
+ * Polls `/proc/self/task/$TID/stat` for a thread state change.
*
* Possible thread states are the same as for TST_PROCESS_STATE_WAIT().
*
diff --git a/include/tst_test_macros.h b/include/tst_test_macros.h
index 12bd9d47e..9a93331d5 100644
--- a/include/tst_test_macros.h
+++ b/include/tst_test_macros.h
@@ -880,10 +880,10 @@ const char *tst_errno_names(char *buf, const int *exp_errs, int exp_errs_cnt);
TST_EXP_EQ_SILENT_(VAL_A, #VAL_A, VAL_B, #VAL_B, unsigned long long, "%llu")
/**
- * TST_EXP_EQ_SZ() - Compare two unsigned size_t values.
+ * TST_EXP_EQ_SZ() - Compare two size_t values.
*
- * @VAL_A: unsigned long long value A.
- * @VAL_B: unsigned long long value B.
+ * @VAL_A: size_t value A.
+ * @VAL_B: size_t value B.
*
* Reports a pass if values are equal and a fail otherwise.
*/
@@ -898,10 +898,10 @@ const char *tst_errno_names(char *buf, const int *exp_errs, int exp_errs_cnt);
} while (0)
/**
- * TST_EXP_EQ_SZ_SILENT() - Compare two unsigned size_t values, silent variant.
+ * TST_EXP_EQ_SZ_SILENT() - Compare two size_t values, silent variant.
*
- * @VAL_A: unsigned long long value A.
- * @VAL_B: unsigned long long value B.
+ * @VAL_A: size_t value A.
+ * @VAL_B: size_t value B.
*
* Unlike TST_EXP_EQ_SZ() does not print :c:enum:`TPASS <tst_res_flags>` on
* success, only prints :c:enum:`TFAIL <tst_res_flags>` on failure.
@@ -910,10 +910,10 @@ const char *tst_errno_names(char *buf, const int *exp_errs, int exp_errs_cnt);
TST_EXP_EQ_SILENT_(VAL_A, #VAL_A, VAL_B, #VAL_B, size_t, "%zu")
/**
- * TST_EXP_EQ_SSZ() - Compare two unsigned ssize_t values.
+ * TST_EXP_EQ_SSZ() - Compare two ssize_t values.
*
- * @VAL_A: unsigned long long value A.
- * @VAL_B: unsigned long long value B.
+ * @VAL_A: ssize_t value A.
+ * @VAL_B: ssize_t value B.
*
* Reports a pass if values are equal and a fail otherwise.
*/
@@ -928,10 +928,10 @@ const char *tst_errno_names(char *buf, const int *exp_errs, int exp_errs_cnt);
} while (0)
/**
- * TST_EXP_EQ_SSZ_SILENT() - Compare two unsigned ssize_t values, silent variant.
+ * TST_EXP_EQ_SSZ_SILENT() - Compare two ssize_t values, silent variant.
*
- * @VAL_A: unsigned long long value A.
- * @VAL_B: unsigned long long value B.
+ * @VAL_A: ssize_t value A.
+ * @VAL_B: ssize_t value B.
*
* Unlike TST_EXP_EQ_SSZ() does not print :c:enum:`TPASS <tst_res_flags>` on
* success, only prints :c:enum:`TFAIL <tst_res_flags>` on failure.
--
2.51.0
More information about the ltp
mailing list