This is the mail archive of the systemtap@sourceware.org mailing list for the systemtap project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: Language Reference, updated


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


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]