[LTP] [PATCH 0/3] Minor programming doc improvements

[LTP] [PATCH 0/3] Minor programming doc improvements

[Petr Vorel]

Petr Vorel (3):
  doc/C-Test-API: Reword SAFE_CMD()
  include: Add SAFE_CMD() programming doc
  include/tst_cmd.h: Improve programming doc

 doc/C-Test-API.asciidoc   |  5 +++--
 include/tst_cmd.h         | 23 ++++++++++++++---------
 include/tst_safe_macros.h | 13 ++++++++++++-
 3 files changed, 29 insertions(+), 12 deletions(-)

-- 
2.42.0


-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

[LTP] [PATCH 1/3] doc/C-Test-API: Reword SAFE_CMD()

[Petr Vorel]

Signed-off-by: Petr Vorel <pvorel@suse.cz>
---
 doc/C-Test-API.asciidoc | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/doc/C-Test-API.asciidoc b/doc/C-Test-API.asciidoc
index dab811564..f9f20bb74 100644
--- a/doc/C-Test-API.asciidoc
+++ b/doc/C-Test-API.asciidoc
@@ -1332,8 +1332,9 @@ return value is '255' if 'execvp()' failed with 'ENOENT' and '254' otherwise.
 'stdout_path' and 'stderr_path' determine where to redirect the program
 stdout and stderr I/O streams.
 
-The 'SAFE_CMD()' macro can be used automatic handling non-zero exits (exits
-with 'TBROK') and 'ENOENT' (exits with 'TCONF').
+'SAFE_CMD()' is a wrapper for 'tst_cmd()' which can be used for automatic
+handling non-zero exit (exits with 'TBROK') and 'ENOENT' (the program not in
+'$PATH', exits with 'TCONF').
 
 .Example
 [source,c]
-- 
2.42.0


-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

[LTP] [PATCH 2/3] include: Add SAFE_CMD() programming doc

[Petr Vorel]

Signed-off-by: Petr Vorel <pvorel@suse.cz>
---
 include/tst_safe_macros.h | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/include/tst_safe_macros.h b/include/tst_safe_macros.h
index 0cf3d7878..6f3289944 100644
--- a/include/tst_safe_macros.h
+++ b/include/tst_safe_macros.h
@@ -646,9 +646,20 @@ int safe_unshare(const char *file, const int lineno, int flags);
 int safe_setns(const char *file, const int lineno, int fd, int nstype);
 #define SAFE_SETNS(fd, nstype) safe_setns(__FILE__, __LINE__, (fd), (nstype))
 
+/*
+ * SAFE_CMD() is a wrapper for tst_cmd(). It runs a command passed via argv[]
+ * and handles non-zero exit (exits with 'TBROK') and 'ENOENT' (the program not
+ * in '$PATH', exits with 'TCONF').
+ *
+ * @param argv[] a 'NULL' terminated array of strings starting with the program
+ * name which is followed by optional arguments.
+ * @param stdout_path: path where to redirect stdout. Set NULL if redirection is
+ * not needed.
+ * @param stderr_path: path where to redirect stderr. Set NULL if redirection is
+ * not needed.
+ */
 void safe_cmd(const char *file, const int lineno, const char *const argv[],
 	const char *stdout_path, const char *stderr_path);
-
 #define SAFE_CMD(argv, stdout_path, stderr_path) \
 	safe_cmd(__FILE__, __LINE__, (argv), (stdout_path), (stderr_path))
 /*
-- 
2.42.0


-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

[LTP] [PATCH 3/3] include/tst_cmd.h: Improve programming doc

[Petr Vorel]

Signed-off-by: Petr Vorel <pvorel@suse.cz>
---
 include/tst_cmd.h | 23 ++++++++++++++---------
 1 file changed, 14 insertions(+), 9 deletions(-)

diff --git a/include/tst_cmd.h b/include/tst_cmd.h
index 1f39f690f..939825646 100644
--- a/include/tst_cmd.h
+++ b/include/tst_cmd.h
@@ -18,14 +18,16 @@ enum tst_cmd_flags {
 
 /*
  * vfork() + execvp() specified program.
- * @argv: a list of two (at least program name + NULL) or more pointers that
+ *
+ * @param 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_fd: file descriptor where to redirect stdout. Set -1 if
+ * @param stdout_fd File descriptor where to redirect stdout. Set -1 if
  * redirection is not needed.
- * @stderr_fd: file descriptor where to redirect stderr. Set -1 if
+ * @param stderr_fd File descriptor where to redirect stderr. Set -1 if
  * redirection is not needed.
- * @flags: enum tst_cmd_flags
+ * @param flags enum tst_cmd_flags.
+ * @return The exit status of the program.
  */
 int tst_cmd_fds_(void (cleanup_fn)(void),
 			const char *const argv[],
@@ -33,12 +35,15 @@ int tst_cmd_fds_(void (cleanup_fn)(void),
 			int stderr_fd,
 			enum tst_cmd_flags flags);
 
-/* Executes tst_cmd_fds() and redirects its output to a file
- * @stdout_path: path where to redirect stdout. Set NULL if redirection is
+/*
+ * Executes tst_cmd_fds() and redirects its output to a file.
+ *
+ * @param 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
+ * @param stderr_path Path where to redirect stderr. Set NULL if redirection is
  * not needed.
- * @flags: enum tst_cmd_flags
+ * @param flags enum tst_cmd_flags.
+ * @return The exit status of the program.
  */
 int tst_cmd_(void (cleanup_fn)(void),
 		const char *const argv[],
@@ -87,7 +92,7 @@ static inline int tst_cmd(void (cleanup_fn)(void),
 #endif
 
 /* Wrapper function for system(3), ignorcing SIGCHLD signal.
- * @command: the command to be run.
+ * @param command The command to be run.
  */
 int tst_system(const char *command);
 
-- 
2.42.0


-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

Re: [LTP] [PATCH 0/3] Minor programming doc improvements

[Marius Kittler]

Hi, I couldn't spot any typos so it looks good to me. (I haven't checked 
whether it is factually correct.)

Reviewed-by: Marius Kittler <mkittler@suse.de>




-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

Re: [LTP] [PATCH 0/3] Minor programming doc improvements

[Andrea Cervesato via ltp]

Hi!

The whole patch is fine for me. Please merge and keep also Marius comment.

Reviewed-by: Andrea Cervesato <andrea.cervesato@suse.com>

On 11/3/23 13:34, Petr Vorel wrote:
> Petr Vorel (3):
>  doc/C-Test-API: Reword SAFE_CMD()
>  include: Add SAFE_CMD() programming doc
>  include/tst_cmd.h: Improve programming doc
>
> doc/C-Test-API.asciidoc   |  5 +++--
> include/tst_cmd.h         | 23 ++++++++++++++---------
> include/tst_safe_macros.h | 13 ++++++++++++-
> 3 files changed, 29 insertions(+), 12 deletions(-)
>
Thanks!
Andrea


-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

Re: [LTP] [PATCH 0/3] Minor programming doc improvements

[Petr Vorel]

Hi Andrea, Marius,

> Hi!

> The whole patch is fine for me. Please merge and keep also Marius comment.

Thanks for your review, merged!

I overlooked that because I watch more patchwork than the mailing list itself.
I really need to look more into mailing list.

Could you, please, also reply to all when comment on mailing lists?
Cover letters does not your RBT (only patches themselves) + some non-regular
contributors may have unsubscribed or random people who got Cced may never has
been subscribed. Also kernel developers may not subscribe at all, because all
mailing lists on lore don't require subscription for posting messages (I've met
kernel developers posting without a subscription for this reason).

Kind regards,
Petr

-- 
Mailing list info: https://lists.linux.it/listinfo/ltp