This is the mail archive of the
systemtap@sourceware.org
mailing list for the systemtap project.
Re: Language Reference, updated
- From: "Frank Ch. Eigler" <fche at redhat dot com>
- To: Robb Romans <robb at linux dot vnet dot ibm dot com>
- Cc: SystemTap <systemtap at sources dot redhat dot com>, Mike Mason <mmlnx at us dot ibm dot com>
- Date: Tue, 13 Feb 2007 14:54:21 -0500
- Subject: Re: Language Reference, updated
- References: <200611221532.39260.robb@linux.vnet.ibm.com> <457EFCF6.1020001@us.ibm.com> <87y7nkgj2l.fsf@skyhawk.austin.ibm.com> <8764a7w598.fsf@skyhawk.austin.ibm.com>
Robb Romans <robb@linux.vnet.ibm.com> writes:
> In section 3.2.4, "Unused alias variables", where is a good explanation
> for this section?
Do you mean what is an unused alias variable? It is a variable
defined in a probe alias (usually as one of a group of "var = $var"
assignments), which is not actually used by the script probe that
instantiates the alias.
> MM> Section 3.6 Mention use of the deref() macro in embedded C for
> MM> safety. Give an example.
>
> I could use a little help with this. Would anyone be able to provide a
> good working example?
There are examples in the tapset. Josh switched us over to the
"kread" function:
function _struct_timeval:string(addr:long)
%{ /* pure */
struct timeval *tv = (struct timeval *)(unsigned long)THIS->addr;
if (tv == NULL)
strlcpy (THIS->__retvalue, "NULL", MAXSTRINGLEN);
else
snprintf(THIS->__retvalue, MAXSTRINGLEN, "[%ld.%06ld]",
kread(&(tv->tv_sec)), kread(&(tv->tv_usec)));
%}
(However, it is not clear that the NULL-handling case is relevant or
appropriate. If the timeval* coming in from the application is
permitted to be NULL, fine, but if it's meant as a crash-prevention
mechanism in this embedded-C routine, then it's not right.)
> [...]
> MM> Sections 8.4.1 - 8.4.3 Show examples of the output that results
> MM> from using these functions.
>
> I'd like to be provided with self-contained examples that I can
> document, run and capture the output.
If you have a working systemtap build, it should not be hard to make
such examples yourself. Its ease-of-use is the stuff of legend ... or
in any case well tested by newbie users.
> [...] I am confused a bit by the logging functions, their inputs
> and outputs, and syntax. Any clues here would be great.
They are documented in the man pages, and the examples have many
instances.
> MM> Section 9.1.8 Mentions "warning stream", but says nothing about
> MM> what that is or what the result of using this function will be
> MM> (i.e, prints the string with "WARNING:" prepended).
>
> I didn't find what you were referring to here. Do you mean "error
> stream"? Is there a better place to find documentation on these
> functions?
"warning stream" was unnecessary terminology. It should simply say
"standard error" of the stap(run) process.
> MM> Sections 9.2.4 & 9.2.5 Question for mailing list: what's the
> MM> point of having both cpu() and cpuid()? They both appear to
> MM> give the same number (current cpu #).
>
> I didn't see an answer to this. I'll be happy to change the guide to be
> more correct.
Drop cpuid(). It is not listed in stapfuncs.5.
> MM> Section 9.2.21 Explain what is meant by the "target process."
>
> Does this mean the PID of the program being probed?
Sort of - see the "-c PROGRAM" and "-x PID" stap options. The man
page for "-c" should be clarified to point out that the target()
stapfuncs.5 function is set analogously to the -x case.
> MM> Section 9.9 I think we should remove subsystem-specific
> MM> functions from this document. [...]
>
> I didn't see any response to your suggestion. What's the verdict on
> removing these sections?
FWIW, I agree.
- FChE