Re: Documentation for the syscall tapsets?

[fche at redhat dot com (Frank Ch. Eigler)]

"Theodore Ts'o" <tytso@mit.edu> writes:

> So I've been starting to play around with systemtap, and I started
> by downloading the "disktop.stp" script.

Great.

> [...]
> probe syscall.execve {
>       printf("%s\n", argstr);
> }
>
> But the only way I came up with it was by "cheating", and looking at
> the tapset sources for syscall.stp in order to find out what magical
> variables were set by the syscall.execve probe.  [...]  there is
> nothing to define the probes for syscall, other than to "Read The
> Source, Luke.

Unfortunately, that's still true.  We have had a long-standing bug
(#2111) for just that.  That tapset is large enough that manual man
page writing seems impractical, but also no one has done systematic
javadoc-style markup.  However, there is definitely a general pattern
for syscall.* probes that we could at least summarize in the
stapprobes man page - and will do promptly.

On the bright side, the Read The Source part is not so bad.  You can
use "stap -l syscall.*" to get a list of probes, and then grep for
them in the tapset directories.  It would be useful and not too hard
to extend "-l" to also list variables defined in each probe/alias.

It turns out too that because of the compactness of the language,
reading the tapset script code is not much worse (as in more wordy,
unclear, or incomplete) than documentation of it would be.

- FChE