stack(9): dynamic allocation is not necessary

[vangyzen]

Summary

The man page said dynamic allocation was required, but struct stack
can be allocated in any way, including on the stack. Make this clear,
and explain how to initialize the struct.

While I'm here, stack_save does not require any lock.

MFC after: 1 week
Sponsored by: Dell EMC Isilon

[pauamma_gundo.com]

English in addition LGTM. Can't speak for consistency with actual KPI.

share/man/man9/stack.9

113

Audience check: would people reading this know (or know how to find out easily) which platforms lack it and how to work around that?

[markj]

share/man/man9/stack.9

91

This is a bit confusing since calling stack_save() or stack_save_td() would be "creating" a trace per the previous sentence. I'd maybe remove the previous sentence and say something to the effect of, "A struct stack can be defined on the stack and initialized using stack_zero(), or dynamically allocated using stack_create().` etc.

[vangyzen]

share/man/man9/stack.9

91

Good point.

I also want to clarify that initialization is not needed before stack_save*(), since there are comments in multiple consumers asking this question.

113

For platform support, yes, I think so. I had never looked at this implementation before, and I found the answer in about ten seconds. A workaround really depends on the context, so that seems out of scope here.

[vangyzen]

• reword with markj

[pauamma_gundo.com]

If it passes the audience check, and since the language looks good, it works as a manual page, barring subject-matter expert concerns.