Re: [PATCH] manual: Document mprotect and introduce section on memory protection

[Florian Weimer <fw at deneb dot enyo dot de>]

* Rical Jasan:

>> Right, the wording isn't correct.
>> 
>> “
>> The file for a file-based mapping was not opened with open flags which
>> are compatible with @var{protection}.
>> “”
>> 
>>> Is there
>>> somewhere we can reference what is special about file-based mappings
>>> such that they can prevent the use of mprotect?  How is this different
>>> from EPERM, below?  The content below the @deftypefun makes it sound
>>> like this might only be returned by some systems.
>> 
>> Maybe we should just say “non-anonymous mappings“ instead?
>> 
>> You can map device memory using files under /dev and /proc, even
>> starting with regular files, and strange things can happen there.  These
>> are technically file-based mappings because that's how you create them,
>> but they are very different from what files would behave like.
>
> Given the is-or-isn't nature of "[non-]anonymous", that could work.  If
> "file-based" is equivalent to "non-anonymous" and we stuck with the
> latter, that'd be fine, but my concern is the (lack of) introduction of
> these terms.  "Anonymous mapping" only appears once in the manual, isn't
> introduced with an @dfn, and doesn't have an @cindex to find it by; and
> this is the first occurrence of "file-based mapping".
>
> I can submit a patch that introduces and indexes the anonymous mapping
> concept where it's mentioned in llio.texi, but I don't know where we
> would provide a similarly cursory mention of file-based mappings.
> Ultimately, I'd rather see this patch go in than get stalled on my own
> unfamiliarity with the vernacular, and if "file-based" is how you as the
> author would naturally refer to it, that's probably best.

We could document the MAP_FILE flag used by some systems, where a call
to mmap must either specify MAP_FILE or MAP_ANONYMOUS (or its older
name, MAP_ANON).

>> -@vindex PROT_READ
>> -@vindex PROT_WRITE
>> -@vindex PROT_EXEC
>>  @var{protect} contains flags that control what kind of access is
>>  permitted.  They include @code{PROT_READ}, @code{PROT_WRITE}, and
>> -@code{PROT_EXEC}, which permit reading, writing, and execution,
>> -respectively.  Inappropriate access will cause a segfault (@pxref{Program
>> -Error Signals}).
>> -
>> -Note that most hardware designs cannot support write permission without
>> -read permission, and many do not distinguish read and execute permission.
>> -Thus, you may receive wider permissions than you ask for, and mappings of
>> -write-only files may be denied even if you do not use @code{PROT_READ}.
>
> Coming back to this now, is there a reason not to leave this paragraph in?

It's redundant with the new section on memory protection.

>> +When a page is mapped using @code{mmap}, page protection flags can be
>> +specified using the protection flags argument.  @xref{Memory-mapped
>> +I/O}.
>> +
>> +The following flags are available:
>> +
>> +@vtable @code
>> +@item PROT_WRITE
>> +@standards{POSIX, sys/mman.h}
>
> I skipped over this before since we haven't canonicalized standards yet,
> but can you provide a specific POSIX version (e.g., POSIX.1-2001)?

I can't check easily.  I don't have the paper standards, and I don't
know where the only versions were changed retroactively.

>> +The memory is reserved, but cannot be read, written, or executed.  If
>> +this flag is specified in a call to @code{mmap}, a virtual memory area
>> +will be set aside for future use in the process, and @code{mmap} calls
>> +without the @code{MAP_FIXED} flag will not use it for subsequent
>> +allocations.  For anonymous mappings, the kernel will not reserve any
>> +physical memory for the allocation at the time the mapping is created.
>
> Just to make sure I'm reading this correctly, if you do use PROT_NONE
> and don't use MAP_ANON, the kernel may allocate the backing storage.

Yes, the special is case for MAP_ANON(YMOUS) only.  I don't know what
happens with a file on a hugetlbfs file system, for example.

>> +@var{protection} is a combination of the @code{PROT_*} flags described
>> +above.
>> +
>
> The return values of the function are also missing:
>
> "@code{mprotect} returns @code{0} on success or @code{-1} on error."

Do we use @code{-1} or @math{-1}?  Existing practice is incosistent.

>> +The following @code{errno} error conditions are defined for this
>> +function:
>> +
>> +@table @code
>> +@item ENOMEM
>> +The system was not able to allocate resources to fulfill the request.
>> +This can happen if there is not enough physical memory in the system for
>> +the allocation of backing storage (if the memory was initially mapped
>> +with @code{PROT_NONE}).  The error can also occur if the new protection
>
> Can we simply drop the parenthetical "if" here?

Sure, I dropped it.

Do you think this can go in as-is (with this and the return value
documentation change)?

PS: It is easier for me to response from my work mail account if you
trim your response and leave out irrelevant parts.