mmap(2): Clarify that guard is taken from the stack region.

[emaste]

lib/libc/sys/mmap.2

347 ↗

(On Diff #78610)

The guard is

[emaste]

One grammar nit

[emaste]

lib/libc/sys/mmap.2

341 ↗

(On Diff #78610)

I guess pedantically the stack grows to (len - guard size).

How does this sound:

This option creates
a memory region that grows to at most
.Fa len
bytes less the guard size.
The region starts from the stack top and grows down.

[kib]

Ed' changes.

[emaste]

Looks good to me.

[alc]

lib/libc/sys/mmap.2

343 ↗

(On Diff #78614)

I would not use a comma here.

353–356 ↗

(On Diff #78614)

Individually, these two sentences make perfect sense, but taken together they do not. The first sentence is about special "guard" vm map entries that act as reservations for the virtual address region, but the second sentence is about the size of the "red zone" created at the bottom of the virtual address region using the "guard" vm map entry. The size of the former, i.e., the reservation, is NOT determined by the sysctl. But, literally taken together that is what these sentences are saying. In the documentation, I don't think that we should use the word "guard" in describing both the reservation and the red zone. Given its use in the name of the sysctl, I would only use it in conjunction with the red zone.

[kib]

Reword text to distinguish between guard as is, and minimal guard size.

[alc]

After mulling this over for the past day or so, I'd like to propose the following alternative description:

"This option creates a memory region that grows downward on demand and an adjoining guard that both reserves address space for the memory region to grow into and limits the memory region's growth. Together, the memory region and the guard occupy len bytes of the address space. The guard starts at the returned address, and the memory region ends at the returned address plus len bytes. Upon access to the guard, the memory region automatically grows in size, and the guard shrinks by an equal amount. Essentially, the boundary between the guard and the memory region moves downward so that the access falls within the enlarged memory region. However, the guard will never shrink to less than the number of pages specified by the sysctl security.bsd.stack_guard_page, thereby ensuring that a gap for detecting stack overflow always exists between the downward growing memory region and the closest memory region beneath it."

[kib]

In D26908#600942, @alc wrote:

After mulling this over for the past day or so, I'd like to propose the following alternative description:

"This option creates a memory region that grows downward on demand and an adjoining guard that both reserves address space for the memory region to grow into and limits the memory region's growth. Together, the memory region and the guard occupy len bytes of the address space. The guard starts at the returned address, and the memory region ends at the returned address plus len bytes. Upon access to the guard, the memory region automatically grows in size, and the guard shrinks by an equal amount. Essentially, the boundary between the guard and the memory region moves downward so that the access falls within the enlarged memory region. However, the guard will never shrink to less than the number of pages specified by the sysctl security.bsd.stack_guard_page, thereby ensuring that a gap for detecting stack overflow always exists between the downward growing memory region and the closest memory region beneath it."

Sounds good to me. Do you want to prepare the patch based on this text, or should I do it ?

[bcr]

OK from manpages as well.

[markj]

lib/libc/sys/mmap.2

322 ↗

(On Diff #78763)

I'd find this sentence a bit easier to parse if there was a comma after "demand" or if it started with "Creates both a mapped region ... and an adjoining ..."

[alc]

lib/libc/sys/mmap.2

322 ↗

(On Diff #78763)

I'll add "both". I worried that this sentence was too long, but I wanted the first sentence to include "grows downward on demand".