Is there anything like a formal language reference for D? I keep running into little weird things (like commenting) that I can''t find documented anywhere. Thanks Charlie Martin -- The key to long life is to immediately forget things. --- Joshu Sasaki Roshi, on his 100th birthday
Hi Charlie,> Is there anything like a formal language reference for D? I keep > running into little weird things (like commenting) that I can''t find > documented anywhere.The Solaris Dynamic Tracing Guide should answer your questions: http://docs.sun.com/app/docs/doc/817-6223 It''s slightly out of date on some of the newer pieces of DTrace but it should act as your formal reference. Comments are discussed in Chapter 1 under the "Variables and Arithmetic Expressions" section. I think the Contents and/or Index in the guide aren''t very complete and maybe this is your issue here. Feel free to log doc bugs if you see things that need improving. Cheers. Jon.
> Is there anything like a formal language reference for D? I keep > running into little weird things (like commenting) that I can''t find > documented anywhere.It''s all in the Solaris Dynamic Tracing Guide at docs.sun.com. -Mike -- Mike Shapiro, Solaris Kernel Development. blogs.sun.com/mws/
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. On 5/14/07, Michael Shapiro <mws at zion.eng.sun.com> wrote:> > > Is there anything like a formal language reference for D? I keep > > running into little weird things (like commenting) that I can''t find > > documented anywhere. > > It''s all in the Solaris Dynamic Tracing Guide at docs.sun.com. > > -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
> 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/
Personally, I''ve always used the C language as my D language guide, and then referred to the DTrace guide for the language differences. Chip
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:
<!-- Here''s a shot. Time-stamp: "2007-05-14 19:37" -->
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
On 5/14/07, Charles Martin <chasrmartin at gmail.com> wrote:> 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. ABefore you mentioned K&R, it was exactly the reference I was thinking of. The second edition (with function prototypes - I''m not that old) and "UNIX in a Nutshell" (2nd edition - I''m not that young either) served me quite well in my early years.> Look this is just a toss-off, but something like this:Excellent example. The great thing about K&R and the Nutshell books was that it was easy to find a simplified example and get an explanation of why it works. Especially in the case of the nutshell books, it was easy to see the various options available with special notes about incompatibilities between implementations. A DTrace Nutshell book would be great to track the improvements over time. Mike -- Mike Gerdts http://mgerdts.blogspot.com/
I''ld like to be able to run my dtrace program for an amount of seconds that I give as a command line argument, is there a standard cut-n-paste boilerplate method for this...?... I can pass the amount at the end of the command-line, and within my dtrace program it will be available as "$1", but then what kind of probe can I write that will fire at $1 seconds plus the BEGIN time, and will cause all my END probes to fire. what I don''t want to do is have a probe that calls exit(), because the docs say that the END probes will not be invoked in this case, but I have END probes sprinkled throughout my program, which is a concatentaion of a lot of mostly separate programs, hence I need the END probes to trigger. thanks, -Pete.
On Mon, May 14, 2007 at 08:47:10PM -0700, Peter Lawrence wrote:> I''ld like to be able to run my dtrace program for an amount of seconds > that I give as a command line argument, is there a standard cut-n-paste > boilerplate method for this...?... I can pass the amount at the end of the > command-line, and within my dtrace program it will be available as "$1", > but then what kind of probe can I write that will fire at $1 seconds plus > the BEGIN time, and will cause all my END probes to fire.tick-1sec /i++ == $1/ { exit(0); }> what I don''t want to do is have a probe that calls exit(), because the > docs say that the END probes will not be invoked in this case, but > I have END probes sprinkled throughout my program, which is a concatentaion > of a lot of mostly separate programs, hence I need the END probes to > trigger.What docs are you looking at? Calling exit() causes END to fire -- and has for a long, long time. From the exit() subsection of the Special Actions section of the "Actions and Subroutines" chapter: When exit() is called, only DTrace actions already underway on other CPUs will be taken; no subsequent actions will be taken on any CPU. The only exception to this is the END probe, which will be called after the DTrace consumer has processed the exit() action and indicated that tracing should stop. - Bryan -------------------------------------------------------------------------- Bryan Cantrill, Solaris Kernel Development. http://blogs.sun.com/bmc
On 5/14/07, Mike Gerdts <mgerdts at gmail.com> wrote:> and "UNIX in a Nutshell" (2nd edition - I''m not that young either)Yeah, yeah, rub it in. I just figured out that I''m a little more than a year short of being in computing for 40 years. -- The key to long life is to immediately forget things. --- Joshu Sasaki Roshi, on his 100th birthday
Charles,
you forgot to note that the "-s" in the "#!" line
isn''t
optional (a fact which is extremely annoying, as it is inconsistent
with all other scripting languages that I''m aware of).
:-)!
-Pete
Martin wrote On 05/14/07 06:42 PM,:> 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:
>
> <!-- Here''s a shot. Time-stamp: "2007-05-14 19:37"
-->
>
> 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/
>>
>
>
>
Bryan,
I''m probably mis-reading this, but here''s what it says
on your
<dtrace.eng/usage.html>
END. Probe triggered after tracing has stopped due to an explicit termination of
tracing from the DTrace consumer. When using dtrace(1M), the END probe is
triggered after receipt of a SIGINT or SIGTERM (e.g., ^C). The END probe is not
triggered after an exit action.
perhaps its the "exit action" that I''m making assumptions
about...?...
-Pete.
Cantrill wrote On 05/14/07 09:23 PM,:> On Mon, May 14, 2007 at 08:47:10PM -0700, Peter Lawrence wrote:
>
>>I''ld like to be able to run my dtrace program for an amount of
seconds
>>that I give as a command line argument, is there a standard cut-n-paste
>>boilerplate method for this...?... I can pass the amount at the end of
the
>>command-line, and within my dtrace program it will be available as
"$1",
>>but then what kind of probe can I write that will fire at $1 seconds
plus
>>the BEGIN time, and will cause all my END probes to fire.
>
>
> tick-1sec
> /i++ == $1/
> {
> exit(0);
> }
>
>
>
>>what I don''t want to do is have a probe that calls exit(),
because the
>>docs say that the END probes will not be invoked in this case, but
>>I have END probes sprinkled throughout my program, which is a
concatentaion
>>of a lot of mostly separate programs, hence I need the END probes to
>>trigger.
>
>
> What docs are you looking at? Calling exit() causes END to fire -- and
> has for a long, long time. From the exit() subsection of the Special
Actions
> section of the "Actions and Subroutines" chapter:
>
> When exit() is called, only DTrace actions already underway on other
> CPUs will be taken; no subsequent actions will be taken on any CPU.
> The only exception to this is the END probe, which will be called after
> the DTrace consumer has processed the exit() action and indicated that
> tracing should stop.
>
> - Bryan
>
> --------------------------------------------------------------------------
> Bryan Cantrill, Solaris Kernel Development. http://blogs.sun.com/bmc
Peter Lawrence wrote:> Charles, > you forgot to note that the "-s" in the "#!" line isn''t > optional (a fact which is extremely annoying, as it is inconsistent > with all other scripting languages that I''m aware of).(n)awk has the same requirement: #!/usr/bin/nawk -f bla ... if you take away the -f, you get a syntax error. Michael -- Michael Schuster Recursion, n.: see ''Recursion''
Michael,
even if this is true, the problem becomes one of documentation.
it is darn hard to figure out from the Solaris DTrace Guide. instead of
being in the intro where "how to run" dtrace is covered, the
information
is burried fifteen chapters later.
and here''s the nawk man page info on its "-f" option:
If -f progfile is specified, the files named by each of the
progfile option-arguments must be text files containing an
nawk program.
The standard input are used only if no file operands are
specified, or if a file operand is -.
it doesn''t say anything about needing the "-f" in a
"#!" script file,
in fact this information is no-where in the nawk man page.
The point of the whole email is really this, while there may be a
convention about requiring "-f" or "-s" in a "#!"
script program
file for some languages, it is never adequately documented, and
is always counter-intuitive.
Try this yourself, write a dtrace script without the "-s" and try
to figure out what you did wrong by reading the diagnostic error
messages output. and notice what happens to the diagnostics when
you either do or don''t have other options in the "#!" line.
within a "#!" script file the "-s" option is totally
redundant,
what else could the rest of the file be .....?????.....
-Pete Lawrence.
Schuster wrote On 05/15/07 11:27 AM,:> Peter Lawrence wrote:
>
>>Charles,
>> you forgot to note that the "-s" in the "#!"
line isn''t
>>optional (a fact which is extremely annoying, as it is inconsistent
>>with all other scripting languages that I''m aware of).
>
>
> (n)awk has the same requirement:
>
> #!/usr/bin/nawk -f
> bla ...
>
> if you take away the -f, you get a syntax error.
>
> Michael
True enough. I also remember being thwarted by --- and needing to ask this list about --- the -w flag. Jeez, I''m tempted to write a book proposal, just because if i wrote a book I''d have to figure all this stuff out..... On 5/15/07, Peter Lawrence <Peter.Lawrence at sun.com> wrote:> Charles, > you forgot to note that the "-s" in the "#!" line isn''t > optional (a fact which is extremely annoying, as it is inconsistent > with all other scripting languages that I''m aware of). > > :-)! > > -Pete > > > > Martin wrote On 05/14/07 06:42 PM,: > > 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: > > > > <!-- Here''s a shot. Time-stamp: "2007-05-14 19:37" --> > > > > 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
> I''m probably mis-reading this, but here''s what it says on your > <dtrace.eng/usage.html>That is _not_ the documentation -- you are looking at the ancient Sun-internal DTrace web site, which should be used _only_ for historical purposes. (You''ll note that dtrace.eng redirects you to the DTrace community page.)> END. Probe triggered after tracing has stopped due to an explicit termination of > tracing from the DTrace consumer. When using dtrace(1M), the END probe is > triggered after receipt of a SIGINT or SIGTERM (e.g., ^C). The END probe is not > triggered after an exit action.Yes, this _was_ true -- until June 2003. It has not been this way for four years, which is about the same time that that usage page has been deprecated in lieu of the documentation. Please, read and refer to the _documentation_, not ancient internal web sites... - Bryan -------------------------------------------------------------------------- Bryan Cantrill, Solaris Kernel Development. http://blogs.sun.com/bmc