diff options
-rw-r--r-- | doc/test-writing-guidelines.txt | 40 |
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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |