[PATCH] trace-cmd: document expected behaviour of execvp for record command

[Paulo Miguel Almeida <paulo.miguel.almeida.rodenas@gmail.com>]

In tracecmd/trace-record.c:<run_cmd>, trace-cmd record -F <executable>
is launched via the libc's execvp() routine.

If you run a command which is meant to be found in one of the entries
of the PATH env var then you should see <n> invocations of the
__x64_sys_execve() syscall where <n> will be equal to the number of
attempts that execvp() routine had done until it could find the
executable.

While the routine works as expected, its behaviour can seem a bit
cryptic for untrained eyes and makes one wonder whether there is
something wrong in any of the parts involved in the tracing operation.
Some time after one digs into trace-cmd's and libc's code base, one
realises that everything is working as expected but documenting it could
save other people's time :-)

Document the expected behaviour ftrace users should see depending on
the way -F <executable> is used.

Signed-off-by: Paulo Miguel Almeida <paulo.miguel.almeida.rodenas@gmail.com>
---
Additional context:

- absolute path example:

	# trace-cmd record -p function_graph \
		-g __x64_sys_execve -O nofuncgraph-irqs \
	        -n __cond_resched --max-graph-depth 1  \
		-F /usr/bin/echo "ftrace" > /dev/null
	
	# trace-cmd report 
	echo-172994 [000] 185539.798539: funcgraph_entry:      ! 803.376 us |  __x64_sys_execve();

- PATH-dependent path example:

	# trace-cmd record -p function_graph \
		-g __x64_sys_execve -O nofuncgraph-irqs \
		-n __cond_resched --max-graph-depth 1  \
		-F echo "ftrace" > /dev/null

	# trace-cmd report
        echo-172656 [002] 185009.671586: funcgraph_entry:      ! 288.732 us |  __x64_sys_execve();
        echo-172656 [002] 185009.671879: funcgraph_entry:      ! 158.337 us |  __x64_sys_execve();
        echo-172656 [002] 185009.672042: funcgraph_entry:      ! 161.843 us |  __x64_sys_execve();
        echo-172656 [002] 185009.672207: funcgraph_entry:      ! 157.656 us |  __x64_sys_execve();
        echo-172656 [002] 185009.672369: funcgraph_entry:      ! 156.343 us |  __x64_sys_execve();
        echo-172656 [002] 185009.672529: funcgraph_entry:      ! 863.629 us |  __x64_sys_execve();

---
 Documentation/trace-cmd/trace-cmd-record.1.txt | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/trace-cmd/trace-cmd-record.1.txt b/Documentation/trace-cmd/trace-cmd-record.1.txt
index b709e48..a000cbe 100644
--- a/Documentation/trace-cmd/trace-cmd-record.1.txt
+++ b/Documentation/trace-cmd/trace-cmd-record.1.txt
@@ -113,6 +113,10 @@ OPTIONS
     Using *-F* will let you trace only events that are caused by the given
     command.
 
+    Note: if the specified filename is neither absolute or relative then libc
+    will invoke execve() syscall for every entry in the colon-separated list of
+    directory pathnames specified in the PATH environment variable.
+
 *-P* 'pid'::
      Similar to *-F* but lets you specify a process ID to trace.
 
-- 
2.38.1