ld.lld.1: document the rest of the -z options

[kib]

usr.bin/clang/lld/ld.lld.1

374

This is not a description of the option, rather it is the description of some not very important consequences of the object structure of the option is used.

379

dso also can have this flag set.

396

This description explains the object structure but not the flag intent. The flag sets the program main thread' stack size. The way it is done, by setting the size of the PT_GNU_STACK segment, is a detail that can be mentioned, but only as a curious addition.

[emaste]

usr.bin/clang/lld/ld.lld.1

374

The exact description of the option is the previous sentence, but this description explains the end use-case of the option, i.e., why the user might want to use it. Shall we document PT_GNU_RELRO handling in rtld(1) or elf(5) perhaps?

379

Do you think as part of object initialization might convey the right intent? The current sentence is still true for dsos I'd argue, but does not cover dlopened ones.

396

So just "Set the main thread's stack size to _size_." in your opinion?

I like referencing the implementation details so that users can follow the trail to understand what the option actually does -- for example "--enable-new-dtags" ought to explain what new dtags are.

Thus perhaps

Set the main thread's stack size to _size_. The size is recorded in the PT_GNU_STACK program segment.

[kib]

usr.bin/clang/lld/ld.lld.1

374

No, the previous section is also an implementation detail.

It probably can be explained as 'Do not mark some part of the GOT read-only, after the initial relocations are processed.' Then the existing text might provide a details if user is so curious.

379

Either that, or 'during initial relocation of the object'.

396

Yes, it is better. 'The stack size is recorded as the size of PT_GNU_STACK ...'.

[emaste]

improvements from kib

usr.bin/clang/lld/ld.lld.1

379

Ok, I think I will go with my version - relocation processing during initial relocation seems like it might be confusing as to what the two relocation phases are.

[arichardson]

usr.bin/clang/lld/ld.lld.1

374

Global variables such as const int* foo = &x;end up in .data.rel.ro and also the .eh_frame section needs to be relro on MIPS. For CHERI we also have another sections that is relro. I would not mention the GOT here since this also applies to other sections.

How about "Do not indicate that portions of the object should be mapped read-only after the initial relocation have been processed"

Also I'm not sure whether we should be using segment header or program header here. I believe most tools use program header? Maybe "The resulting object will not contain the PT_GNU_RELRO program header." ?

[emaste]

These changes will be included in the work to upstream the man page, tracked in https://reviews.llvm.org/D42963