doc: document tst_run_cmd

Signed-off-by: Stanislav Kholmanskikh <stanislav.kholmanskikh@oracle.com>
Acked-by: Cyril Hrubis <chrubis@suse.cz>

1 files changed, 40 insertions, 0 deletions

diff --git a/doc/test-writing-guidelines.txt b/doc/test-writing-guidelines.txt
index b220e4352..c1b1d360f 100644
--- a/doc/test-writing-guidelines.txt
+++ b/doc/test-writing-guidelines.txt
@@ -997,6 +997,46 @@ exactly as 'umount(2)' but retries several times on a failure.
 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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~