procctl.2: Editing pass

[jhb]

Summary

• Add some missing .Pp macros after the end of literal blocks and some lists to ensure there is a blank line before the following text.

• Use an indent of Ds for nested lists to reduce excessive indentation and make the bodies of the nested list items easier to read.

• Various and sundry rewordings and clarifications.

[jhb]

I had started with just trying to add the missing blank lines, but then the indentation thing was something man was warning about when rendering as postscript and I ended up down a rabbit hole of other tweaks. I think many of these tweaks are slightly more readable or simpler to understand, but that may just be a matter of taste.

[emaste]

Some minor notes

lib/libsys/procctl.2

141

there's a lengthy list in betwen, so maybe it's worth being a bit verbose and having some repetition: "If this control is enabled," instead of otherwise.

238

We should mention the end of the chain perhaps

480

485–486

540–541

maybe unwrap this

587

589–590

I'm not sure what the canonical way to describe VA mapping in this context but "filled" maybe is a bit odd.

593–598

or "upon access to a page" maybe, one access gets you one signal right?

[emaste]

I think many of these tweaks are slightly more readable or simpler to understand, but that may just be a matter of taste.

I think overall the tweaks improve readability / understanding. Agree some of them are a matter of taste; your edits are an improvement IMO but I've commented on a couple of things that I think still have a reasonable improvement over your take.

[kib]

lib/libsys/procctl.2

86

unsplit this line?

166

Perhaps apply the same way to explain that there is the elfctl flag for the binary, as was used for ASLR?

238

It is the next sentence.

248–249

301

347

un-split the line

439

I would not say that dumping core is abnormal exit, but perhaps my view is too kernel-focused. Also, wouldn't this open question about dumping core in other cases? (I know that there is no other cases, but it makes an impression for reader).

504–506

It does not disable signal delivery, it only stops delivering the SIGTRAP described above.

587

Might be the 'end' needs some explanation.
It is bottom for grow-down, and top for grow-up.

589–590

backed

726

un-split

931–933

[jhb]

lib/libsys/procctl.2

141

The issue here is that it's more like:

If this control is enabled, the prot argument to mmap(2) is not PROT_NONE, and the elfctl(1) noprotomax flag is not set, the implicit protection is equal...

That is, in code it's:

 if (x || y || z)
    maxprot = _PROT_ALL;
else
    maxprot = prot;

That said, maybe it's worth reworking this a bit further to first identify the two cases (RWX vs == prot) and then outline when those cases are used.

301

Hmm, why the leading \? I wasn't aware of needing that (and there are several other "-1" literals in this file I'll need to fix if so).

439

Hmmm, I guess PT_COREDUMP is already covered by ptrace(2) (that is another case of coredumps that is presumably also prevented by this control though it is implicit by blocking PT_ATTACH). It is true that for a userspace programmer using this API, "abnormal exit" is redundant with a core dump so I can drop that part.

504–506

Yes, I will add an explicit SIGTRAP to clarify.

587

I think "the end of the growth area" is sufficient. I'm not sure we have any stacks that grow up on FreeBSD after the removal of ia64?

593–598

Yes, each access raises a synchronous signal. I can maybe make that a bit more explicit.

937

I wonder if it is worth adding a note up above about ASLR and just saying "ASLR support was added" here. The other note might read something like:

ASLR support provides minimal security in practice as it is based on secrets and is non-deterministic and comes at the cost of address space fragmentation.

One could also perhaps say that ASLR makes debugging harder, but I think that's not really true anymore for the most part? Is there any performance overhead from having PIE binaries instead of PDE binaries?

[jhb]

Suggestions and feedback from Konstantin and Ed

[kib]

lib/libsys/procctl.2

301

In the Heirloom troff user manual, 2. Font and Character Size Control 2.1. Character set.

ASCII Input             Character
−                          minus
Printed by troff      Character
–                         hyphen
The characters ´, `, and – may be input by \´, \`, and \– respectively or by their names.

587

s/end/bottom/. Apparently, grow-up stacks are not exposed to userspace.

[jhb]

Escape all minus signs

[kib]

lib/libsys/procctl.2

86

Do you plan to fix this?

[emaste]

lib/libsys/procctl.2

141

Oh yes, of course.

150

I.e., it's not possible to create a non-upgradable PROT_NONE

[jhb]

lib/libsys/procctl.2

86

Since I didn't change these lines at all I was planning to leave it alone to avoid adding noise in the diff.

150

I believe that is true, yes. However, you can use MAP_GUARD for a mapping you can't upgrade protections on via mprotect(2) alone (you have to install a new mapping via mmap(2) with MAP_FIXED).

[jhb]

lib/libsys/procctl.2

587

So maybe just "A stack gap is one or more virtual pages at the bottom of a MAP_STACK mapped region..."?

[kib]

lib/libsys/procctl.2

86

Can be a separate commit in the series.

587

Sounds good. Do we all agree that addresses grow from smaller to larger, up?

Might be 'at the bottom (lower address) of a MAP_STACK...'

[jhb]

lib/libsys/procctl.2

587

The larger world of computer science does not agree and uses top/bottom for both ends at times (in particular non-call stacks tend to use top as the newest item). In some ways "end of the growth area" is probably clearer and less ambiguous than either "top" or "bottom".

[kib]

lib/libsys/procctl.2

587

I am fine with any wording you prefer there.