doc: document tst_run_cmd
Signed-off-by: Stanislav Kholmanskikh <stanislav.kholmanskikh@oracle.com>
Acked-by: Cyril Hrubis <chrubis@suse.cz>
diff --git a/doc/test-writing-guidelines.txt b/doc/test-writing-guidelines.txt
index b220e43..c1b1d36 100644
--- a/doc/test-writing-guidelines.txt
+++ b/doc/test-writing-guidelines.txt
@@ -997,6 +997,46 @@
IMPORTANT: All testcases should use 'tst_umount()' instead of 'umount(2)' to
umount filesystems.
+2.2.20 Running executables
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+[source,c]
+-------------------------------------------------------------------------------
+#include "test.h"
+
+int tst_run_cmd(void (cleanup_fn)(void),
+ const char *const argv[],
+ const char *stdout_path,
+ const char *stderr_path,
+ int pass_exit_val);
+-------------------------------------------------------------------------------
+
+'tst_run_cmd' is a wrapper for 'vfork() + execvp()' which provides a way
+to execute an external program.
+
+'argv[]' is a NULL-terminated array of strings starting with the program name
+which is followed by optional arguments.
+
+A non-zero 'pass_exit_val' makes 'tst_run_cmd' return the program exit code to
+the caller. A zero for 'pass_exit_val' makes 'tst_run_cmd' exit the tests
+on failure and call 'cleanup_fn' (if not NULL) beforehand.
+
+'stdout_path' and 'stderr_path' determine where to redirect the program
+stdout and stderr I/O streams.
+
+.Example
+[source,c]
+-------------------------------------------------------------------------------
+#include "test.h"
+
+const char *const cmd[] = { "ls", "-l", NULL };
+
+...
+ /* Store output of 'ls -l' into log.txt */
+ tst_run_cmd(cleanup, cmd, "log.txt", NULL, 0);
+...
+-------------------------------------------------------------------------------
+
2.3 Writing a testcase in shell
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~