[dtrace-discuss] dtrace language reference

Charles Martin
Tue, 15 May 2007 01:42:14 -0000

A grammar would certainly be a way to do it.  I certainly referred to
the grammar in K&R back in the day, even pre-function prototypes.  A
complete example at a little more than the "Hello, world" level ---
but not much more --- would help.  Or dig up a copy of the original
AWK paper or the AWK book and follow that example.

Look  this is just a toss-off, but something like this:



INTRODUCTION

Since time immemorial --- at least 1980 --- the traditional way to
introduce a programming language is to start with a first simple
program, intended to give a "feel" for the language and introduce the
basic features.  In the original _C Programming Language_ [ref], and
ever since, this has been done with a basic program called "hello,
world."

Tradition must be respected, so we introduce D, the programming
language of DTrace scripts, with a version of "Hello, world."
Footnotes on the text of the program are marked with a number in
[[double brackets]], eg, [[1]].


----------------------------------------------------------------------
#!/usr/sbin/dtrace -s           [[1]]
/* DTrace Hello World           [[2]]
 *
 * This program introduces the overall syntactical structure of D by
 * means of a small program.  This program:
 * (1) prints the message "Hello, world!" at startup
 * (2) exits.
 */

#pragma D option quiet          [[3]]

dtrace:::BEGIN                  [[4]]
{
    printf("Hello, world!\n");  [[5]]
    exit(0);                    [[6]]
}
----------------------------------------------------------------------

Footnotes:

[[1]] Every dtrace script normally starts with an interpreter line,
      much as do shell scripts and other interpreted language programs
      like Perl and Awk.  The interpreter line starts with #!,
      followed by the path to the interpreter executable, and any
      flags.  If you''re not familiar with this conventino, see [ref].

[[2]] Comments in D are delimited with /* text */, as in C.

[[3]] Text in the body of the D file that starts with a ''#''
denotes an
      interpreter directive.  In this case, the ''pragma''
directive
      here has the same effect as setting the ''-q'' flag on the
dtrace
      command line --- it reduces the amount of additional information
      the interpreter prints.  Pragmas are described on page [...]

[[4]] D programs differ from C programs in that they consist of one or
      more _clauses_, each of which is invoked when certain conditions
      are true.  This clause starts with ''dtrace:::BEGIN''
which tells
      us that the clause will be activated, or "fire" at the very
      beginning of the program.  We will see more details of clauses
      shortly.

[[5]] D includes the familiar printf function.  In general, D has
      syntax purposefully modeled on C.

[[6]] As in C, the exit function ends execution of the DTrace script.
      One surprise lying in wait for the unwary new D programmer is
      that D scripts in general _don''t_ terminate unless told to,
      either by means of an exit call, or by being terminated by a
      SIGINT (^C) fro9m the terminal.

----------- END --------------

Obviously this is rough (is ^C a SIGINT or a SIGTERM? 25 years and I
still always have to look that up) and limited by plain text, but it''s
an idea.  But just this much of an introduction would have cut my
initial learning curve by about a day, especially since I have to go
to meetings and talk to junior engineers and so get lots of
interruptions.

On 5/14/07, Michael Shapiro <mws at zion.eng.sun.com>
wrote:
>
> > Guys, it really *isn''t* all there.  I''ve got a
couple of bugs in
> > already on finding the definitions of various pragmas; I just looked
> > and the section Jon mentioned doesn''t ... well, to start with
it
> > doesn''t exist in the docs.sun.com version, but the two
sections that
> > seem MECE and to sum to it don''t really say anything about
comments
> > either --- although there are examples of C slash-star comments.  But
> > then there are things that look like sharp comments, but I know by
> > experimentation that they work as comments sometimes and other not.
> > (I was misled by the similarity to Awk to think it was a sharp-comment
> > language instead of a C comment language.)
> >
> > I guess the underlying point here is that it''d be nice if
there were a
> > syntax summary somewhere.
>
> Comments are described in Chapter 1 in the examples, but I guess we need
> to call that out more explicitly.  In terms of syntax reference, Chapters
> 1-10 are effectively the complete reference.  Please file bugs on things
> that are omitted, and our apologies.  In terms of a "syntax
summary" not
> sure what you''re looking for -- list of examples?  A copy of the
grammar?
> Maybe if you give us a quick sketch of what you think would be helpful
> we can try to incorporate that into the web site and/or DTrace guide.
>
> -Mike
>
> --
> Mike Shapiro, Solaris Kernel Development. blogs.sun.com/mws/
>


--
The key to long life is to immediately forget things. --- Joshu Sasaki
Roshi, on his 100th birthday