manual: Document mprotect and introduce section on memory protection
This commit is contained in:
Florian Weimer
parent
f6e965ee94
commit
0f74bbf513
|
|
@ -1,3 +1,11 @@
|
|||
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,
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in a new issue