Yeah, I was thinking that maybe apropos(1) likes the use of marcos in code examples and so style.mdoc should be updated to reflect that.

Perhaps that's a fun project for another time. If you don't like the current style here, I'll just use the one recommended by style.mdoc(7).

It should come up for "fbt" because the document name is "dtrace_fbt". The issue is that it will come up for "name", "function", and "module".

Well sir it's not that I don't like it, it's that the maintainers of the language say it's wrong and it should not be done in the link I provided above on the mdoc/mandoc projects homepage.

This one also doesn't need to have so much whitespace, it breaks legibility on narrower consoles.

If we figure out how to split that I'm all for doing that.

Haha, okay then, let's not do it like this. If we ever change our mind, we can revisit that. I'll not use macros in code blocks.

TODO

Hmm, any idea why -lv does not mention malloc(9)'s third argument?

console
# dtrace -n 'fbt::malloc:return' -lv
   ID   PROVIDER            MODULE                          FUNCTION NAME
31954        fbt            kernel                            malloc return

        Probe Description Attributes
                Identifier Names: Private
                Data Semantics:   Private
                Dependency Class: Unknown

        Argument Attributes
                Identifier Names: Private
                Data Semantics:   Private
                Dependency Class: ISA

        Argument Types
                args[0]: int
                args[1]: void *

I've added a section about probe arguments.

An example of dtrace -lv is still a todo.

I've removed mdoc macros from code listings.

I've narrowed all the examples of count aggregations to the same width.

XXX: I should probably advertise typed args first instead of the untyped argX variables..

"Almost every" is misleading. It lets one trace functions which are not inlined, but many functions are inlined. One way to say this would be, "... the entry and return of almost every function corresponding to an ELF symbol in the kernel and loaded kernel modules."

In that command you're printing the arguments for the return probe. dtrace -n 'fbt::malloc:entry' -lv should show you the function arguments.

Is arg0 supposed to be the D syntax? If so, it should probably be args[0] instead. arg0 is a raw 64-bit integer, while args[0] has the same type as the probe argument. For instance, fbt::malloc:entry {print(*arg1);} won't work, but fbt::malloc:entry {print(*args[1]);} will.

If you use args[N] syntax, then the arguments will be typed according to the function's signature, as I noted above.

Okay I've been playing with this: the name of the command is dtrace, the command modifier fbt tells dtrace to use function boundary tracing, : is the delimiter, and the three subsequent arguments are arguments. Right?

This renders as:
dtrace "fbt:module:function:name"

Nice try! :D But you'd need -n for that.

So, it'd need to be something like:

dtrace -n "fbt:module:function:name { ... }"

at the very least.

Also, DTrace scripts can live in files as well, so it does not feel right to suggest the intended use of FBT is only for DTrace one-liner on the command line.

The synopsis section always feels a bit hacky if it describes something that's not a shell command, a C function, or a kernel module.

Also, remember that Dq might render as stylized quotes. Qq would be better here.

I still believe that the current synopsis is the most optimal of all we came up so far.

Thanks! Applied

Thanks. I've added dtrace -lv example.

Fair point. I'll address that in the next revision.

AFAIK, a single period is alright if etc. is at the end of a sentence.

https://english.stackexchange.com/questions/8382/when-etc-is-at-the-end-of-a-phrase-do-you-place-a-period-after-it

I rewrote this part.

I rewrote this part.

Added!

The part about FBT's stability has been moved to CAVEATS. It also added a small example.

Isn't this redundant? We could write this like "args[0], ...".

Seems redundant as the table below gives the same information.

Not sure.

We could, but a table is easier to navigate. Also, we explain return probe args in a table as well, so it's consistent. I agree that it is a bit verbose, but I'd like to avoid saying just that "functions arguments are args[0], ...".

I kind of like the idea that the paragraph is easy to read and gives some more details and the table provides a quick reference. I'm not sure how I'd golf that into less text without sacrificing readability.