diff options
| -rw-r--r-- | ChangeLog | 8 | ||||
| -rw-r--r-- | manual/llio.texi | 14 | ||||
| -rw-r--r-- | manual/memory.texi | 122 |
3 files changed, 133 insertions, 11 deletions
@@ -1,5 +1,13 @@ 2017-11-19 Florian Weimer <fweimer@redhat.com> + manual: Document mprotect + * manual/memory.texi (Memory Protection): New section. + * manual/llio.texi (Memory-mapped I/O): Remove duplicate + documentation of PROT_* flags and reference the Memory Protection + section instead. + +2017-11-19 Florian Weimer <fweimer@redhat.com> + * manual/llio.texi (I/O Primitives): Move preadv, preadv64, pwritev, pwritev64, preadv2, preadv64v2, pwritev2, pwritev64v2 ... (Scatter-Gather): ... to here. Remove misleading comment. diff --git a/manual/llio.texi b/manual/llio.texi index ff88805369..7dd4e0680d 100644 --- a/manual/llio.texi +++ b/manual/llio.texi @@ -1401,19 +1401,11 @@ is created, which is not removed by closing the file. address is automatically removed. The address you give may still be changed, unless you use the @code{MAP_FIXED} flag. -@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}. +@code{PROT_EXEC}. The special flag @code{PROT_NONE} reserves a region +of address space for future use. The @code{mprotect} function can be +used to change the protection flags. @xref{Memory Protection}. @var{flags} contains flags that control the nature of the map. One of @code{MAP_SHARED} or @code{MAP_PRIVATE} must be specified. diff --git a/manual/memory.texi b/manual/memory.texi index 51a5f4e83c..3f5dd90260 100644 --- a/manual/memory.texi +++ b/manual/memory.texi @@ -17,6 +17,7 @@ and allocation of real memory. * Memory Concepts:: An introduction to concepts and terminology. * Memory Allocation:: Allocating storage for your program data * Resizing the Data Segment:: @code{brk}, @code{sbrk} +* Memory Protection:: Controlling access to memory regions. * Locking Pages:: Preventing page faults @end menu @@ -3047,7 +3048,128 @@ of the data segment is. @end deftypefun +@node Memory Protection +@section Memory Protection +@cindex memory protection +@cindex page protection +@cindex protection flags +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} +The memory can be written to. + +@item PROT_READ +@standards{POSIX, sys/mman.h} +The memory can be read. On some architectures, this flag implies that +the memory can be executed as well (as if @code{PROT_EXEC} had been +specified at the same time). + +@item PROT_EXEC +@standards{POSIX, sys/mman.h} +The memory can be used to store instructions which can then be executed. +On most architectures, this flag implies that the memory can be read (as +if @code{PROT_READ} had been specified). + +@item PROT_NONE +@standards{POSIX, sys/mman.h} +This flag must be specified on its own. + +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. +@end vtable + +The operating system may keep track of these flags separately even if +the underlying hardware treats them the same for the purposes of access +checking (as happens with @code{PROT_READ} and @code{PROT_EXEC} on some +platforms). On GNU systems, @code{PROT_EXEC} always implies +@code{PROT_READ}, so that users can view the machine code which is +executing on their system. + +Inappropriate access will cause a segfault (@pxref{Program Error +Signals}). + +After allocation, protection flags can be changed using the +@code{mprotect} function. + +@deftypefun int mprotect (void *@var{address}, size_t @var{length}, int @var{protection}) +@standards{POSIX, sys/mman.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} + +A successful call to the @code{mprotect} function changes the protection +flags of at least @var{length} bytes of memory, starting at +@var{address}. + +@var{address} must be aligned to the page size for the mapping. The +system page size can be obtained by calling @code{sysconf} with the +@code{_SC_PAGESIZE} parameter (@pxref{Sysconf Definition}). The system +page size is the granularity in which the page protection of anonymous +memory mappings and most file mappings can be changed. Memory which is +mapped from special files or devices may have larger page granularity +than the system page size and may require larger alignment. + +@var{length} is the number of bytes whose protection flags must be +changed. It is automatically rounded up to the next multiple of the +system page size. + +@var{protection} is a combination of the @code{PROT_*} flags described +above. + +The @code{mprotect} function returns @math{0} on success and @math{-1} +on failure. + +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. The error can also occur if the new +protection flags would cause the memory region to be split from its +neighbors, and the process limit for the number of such distinct memory +regions would be exceeded. + +@item EINVAL +@var{address} is not properly aligned to a page boundary for the +mapping, or @var{length} (after rounding up to the system page size) is +not a multiple of the applicable page size for the mapping, or the +combination of flags in @var{protection} is not valid. + +@item EACCES +The file for a file-based mapping was not opened with open flags which +are compatible with @var{protection}. + +@item EPERM +The system security policy does not allow a mapping with the specified +flags. For example, mappings which are both @code{PROT_EXEC} and +@code{PROT_WRITE} at the same time might not be allowed. +@end table +@end deftypefun + +If the @code{mprotect} function is used to make a region of memory +inaccessible by specifying the @code{PROT_NONE} protection flag and +access is later restored, the memory retains its previous contents. + +On some systems, it may not be possible to specify additional flags +which were not present when the mapping was first created. For example, +an attempt to make a region of memory executable could fail if the +initial protection flags were @samp{PROT_READ | PROT_WRITE}. + +In general, the @code{mprotect} function can be used to change any +process memory, no matter how it was allocated. However, portable use +of the function requires that it is only used with memory regions +returned by @code{mmap} or @code{mmap64}. @node Locking Pages @section Locking Pages |