From patchwork Fri Nov 24 16:59:43 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Florian Weimer X-Patchwork-Id: 24502 Received: (qmail 77871 invoked by alias); 24 Nov 2017 16:59:47 -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 77792 invoked by uid 89); 24 Nov 2017 16:59:47 -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, SPF_HELO_PASS, T_RP_MATCHES_RCVD autolearn=ham version=3.3.2 spammy=birth, Together, resident, Executing X-HELO: mx1.redhat.com Date: Fri, 24 Nov 2017 17:59:43 +0100 To: libc-alpha@sourceware.org Subject: [PATCH] mlockall: Document MCL_ONFAULT flag User-Agent: Heirloom mailx 12.5 7/5/10 MIME-Version: 1.0 Message-Id: <20171124165943.EEF034071C775@oldenburg.str.redhat.com> From: fweimer@redhat.com (Florian Weimer) 2017-11-24 Florian Weimer * manual/memory.texi (Page Lock Functions): Document MCL_ONFAULT. diff --git a/manual/memory.texi b/manual/memory.texi index 1b431bf5da..d96e9881de 100644 --- a/manual/memory.texi +++ b/manual/memory.texi @@ -3404,31 +3404,52 @@ other bits must be zero. @vtable @code @item MCL_CURRENT +@standards{POSIX.1b, sys/mman.h} Lock all pages which currently exist in the calling process' virtual address space. @item MCL_FUTURE +@standards{POSIX.1b, sys/mman.h} Set a mode such that any pages added to the process' virtual address space in the future will be locked from birth. This mode does not affect future address spaces owned by the same process so exec, which replaces a process' address space, wipes out @code{MCL_FUTURE}. @xref{Executing a File}. +@item MCL_ONFAULT +@standards{Linux, sys/mman.h} +Together with @code{MCL_CURRENT}, only those which are already in memory +are locked immediately. Additional pages in the range are automatically +locked in case of a page fault and allocation of memory. That is, all +existing mappings behave as if @code{MLOCK_ONFAULT} had been specified +for them using @code{mlock2}. + +Together with @code{MCL_FUTURE}, new mappings behave as if +@code{MLOCK_ONFAULT} is specified for them using @code{mlock2} (that is, +they are not immediately locked into memory, but will be on a page +fault). @end vtable When the function returns successfully, and you specified -@code{MCL_CURRENT}, all of the process' pages are backed by (connected -to) real frames (they are resident) and are marked to stay that way. -This means the function may cause page-ins and have to wait for them. +@code{MCL_CURRENT} without @code{MCL_ONFAULT}, all of the process' pages +are backed by (connected to) real frames (they are resident) and are +marked to stay that way. This means the function may cause page-ins and +have to wait for them. When the process is in @code{MCL_FUTURE} mode because it successfully -executed this function and specified @code{MCL_CURRENT}, any system call -by the process that requires space be added to its virtual address space -fails with @code{errno} = @code{ENOMEM} if locking the additional space -would cause the process to exceed its locked page limit. In the case -that the address space addition that can't be accommodated is stack -expansion, the stack expansion fails and the kernel sends a -@code{SIGSEGV} signal to the process. +executed this function and specified @code{MCL_FUTURE} without +@code{MCL_ONFAULT}, any system call by the process that requires space +be added to its virtual address space fails with @code{errno} = +@code{ENOMEM} if locking the additional space would cause the process to +exceed its locked page limit. In the case that the address space +addition that can't be accommodated is stack expansion, the stack +expansion fails and the kernel sends a @code{SIGSEGV} signal to the +process. + +When you specify the additional @code{MCL_ONFAULT}, no page-ins occur +with @code{MCL_CURRENT}, and with @code{MCL_FUTURE}, new allocations do +not initially count against the locked page limit (until a page fault +happens and they are locked into memory). When the function fails, it does not affect the lock status of any pages or the future locking mode.