From patchwork Tue Nov 14 14:26:14 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Florian Weimer X-Patchwork-Id: 837878 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (mailfrom) smtp.mailfrom=sourceware.org (client-ip=209.132.180.131; helo=sourceware.org; envelope-from=libc-alpha-return-87078-incoming=patchwork.ozlabs.org@sourceware.org; receiver=) Authentication-Results: ozlabs.org; dkim=pass (1024-bit key; secure) header.d=sourceware.org header.i=@sourceware.org header.b="etWPKs9+"; dkim-atps=neutral Received: from sourceware.org (server1.sourceware.org [209.132.180.131]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 3ybqZD1pqSz9sBZ for ; Wed, 15 Nov 2017 01:26:28 +1100 (AEDT) DomainKey-Signature: a=rsa-sha1; c=nofws; d=sourceware.org; h=list-id :list-unsubscribe:list-subscribe:list-archive:list-post :list-help:sender:date:to:subject:mime-version:content-type :content-transfer-encoding:message-id:from; q=dns; s=default; b= O0MIcHdw49GhOclz8SHTlCUjlUioKEKPOiefRKYm0/TzCkfInUlEfwiU4SwWMtbm 9Zdgsnfr3ZylURRItYZflQ2LeQ0wL6ukPjhbNBxDCGll2KP/Z4EKfN5MZZYSWIL1 bf3ZYS+nMGZsmpYXZDuwptIN+06HmytUkMfBl59Ta80= DKIM-Signature: v=1; a=rsa-sha1; c=relaxed; d=sourceware.org; h=list-id :list-unsubscribe:list-subscribe:list-archive:list-post :list-help:sender:date:to:subject:mime-version:content-type :content-transfer-encoding:message-id:from; s=default; bh=oKgQiR 82NiMd5S9EfSAiU62La4A=; b=etWPKs9+iw5yRCh7kLzlYn1ppOT/verfu1R6Nl 8T6OSsf3VoqdjDrr5Na1UD6BSnZZj1zg+CekXnA2wUr1JnK90fq1+vvz9GCJGB2d mB96KFmBeD35n8GAOCNddqfuUYO5t42iUQcGDq13li8gUGZQlyhD0vHBqQYNRdkz PikJI= Received: (qmail 130912 invoked by alias); 14 Nov 2017 14:26:20 -0000 Mailing-List: contact libc-alpha-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: libc-alpha-owner@sourceware.org Delivered-To: mailing list libc-alpha@sourceware.org Received: (qmail 129411 invoked by uid 89); 14 Nov 2017 14:26:19 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-26.7 required=5.0 tests=BAYES_00, GIT_PATCH_0, GIT_PATCH_1, GIT_PATCH_2, GIT_PATCH_3, KB_WAM_FROM_NAME_SINGLEWORD, RP_MATCHES_RCVD, SPF_HELO_PASS autolearn=ham version=3.3.2 spammy=brk, Pages, neighbors, faults X-HELO: mx1.redhat.com Date: Tue, 14 Nov 2017 15:26:14 +0100 To: libc-alpha@sourceware.org Subject: [PATCH] manual: Document mprotect and introduce section on memory protection User-Agent: Heirloom mailx 12.5 7/5/10 MIME-Version: 1.0 Message-Id: <20171114142614.BFCBD4010386D@oldenburg.str.redhat.com> From: fweimer@redhat.com (Florian Weimer) 2017-11-14 Florian Weimer manual: Document mprotect * manual/memory.texi (Memory Protection): New section. * manual/llio.texi (Memory-mapped I/O): Reference this section. Remove duplicate documentation of PROT_* flags. diff --git a/manual/llio.texi b/manual/llio.texi index 10ad546723..e635c0eaa8 100644 --- a/manual/llio.texi +++ b/manual/llio.texi @@ -1411,19 +1411,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} reserve 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..9a9340cace 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,120 @@ 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 availabe. + +@table @code +@item PROT_WRITE +@vindex PROT_WRITE +The memory can be written to. + +@item PROT_READ +@vindex PROT_READ +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 +@vindex PROT_EXEC +The memory can be used 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 +@vindex PROT_NONE +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, though. +@end table + +The operating system may keep of these flags separately even if the +underlying hardware treats them the same for the purposes of access +checking (as it happens with @code{PROT_READ} and @code{PROT_EXEC} on +some platforms). + +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 using @samp{sysconf (_SC_PAGE_SIZE)}. +@xref{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_}* described above. + +@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 +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 flags which match +@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 make a region of memory executable could fail if the initial +protection flags where @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