Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752933AbdLDCOU (ORCPT ); Sun, 3 Dec 2017 21:14:20 -0500 Received: from mail-pf0-f194.google.com ([209.85.192.194]:41745 "EHLO mail-pf0-f194.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752887AbdLDCOS (ORCPT ); Sun, 3 Dec 2017 21:14:18 -0500 X-Google-Smtp-Source: AGs4zMaWmKEMM/DxJB5hlsqU/fonNFSlF1aBTcBI5/qQ7Kq0ModMeAzgxOKez3yiXpCPoG/KPSrv3g== From: john.hubbard@gmail.com X-Google-Original-From: jhubbard@nvidia.com To: Michael Kerrisk Cc: linux-man , linux-api@vger.kernel.org, Michael Ellerman , linux-mm@kvack.org, LKML , linux-arch@vger.kernel.org, Jann Horn , Matthew Wilcox , Michal Hocko , John Hubbard Subject: [PATCH v2] mmap.2: MAP_FIXED updated documentation Date: Sun, 3 Dec 2017 18:14:11 -0800 Message-Id: <20171204021411.4786-1-jhubbard@nvidia.com> X-Mailer: git-send-email 2.15.1 X-NVConfidentiality: public Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Length: 3242 Lines: 85 From: John Hubbard Previously, MAP_FIXED was "discouraged", due to portability issues with the fixed address. In fact, there are other, more serious issues. Also, in some limited cases, this option can be used safely. Expand the documentation to discuss both the hazards, and how to use it safely. The "Portability issues" wording is lifted directly from Matthew Wilcox's review. The notes about other libraries creating mappings is also from Matthew (lightly edited). The suggestion to explain how to use MAP_FIXED safely is from Jann Horn. Suggested-by: Matthew Wilcox Suggested-by: Jann Horn Signed-off-by: John Hubbard --- Changed from v1: -- Covered topics recommended by Matthew Wilcox and Jann Horn, in their recent review: the hazards of overwriting pre-exising mappings, and some notes about how to use MAP_FIXED safely. -- Rewrote the commit description accordingly. man2/mmap.2 | 38 ++++++++++++++++++++++++++++++++++++-- 1 file changed, 36 insertions(+), 2 deletions(-) diff --git a/man2/mmap.2 b/man2/mmap.2 index 385f3bfd5..9038256d4 100644 --- a/man2/mmap.2 +++ b/man2/mmap.2 @@ -222,8 +222,42 @@ part of the existing mapping(s) will be discarded. If the specified address cannot be used, .BR mmap () will fail. -Because requiring a fixed address for a mapping is less portable, -the use of this option is discouraged. +.IP +This option is extremely hazardous (when used on its own) and moderately +non-portable. +.IP +Portability issues: a process's memory map may change significantly from one +run to the next, depending on library versions, kernel versions and random +numbers. +.IP +Hazards: this option forcibly removes pre-existing mappings, making it easy +for a multi-threaded process to corrupt its own address space. +.IP +For example, thread A looks through /proc//maps and locates an available +address range, while thread B simultaneously acquires part or all of that same +address range. Thread A then calls mmap(MAP_FIXED), effectively overwriting +thread B's mapping. +.IP +Thread B need not create a mapping directly; simply making a library call +that, internally, uses dlopen(3) to load some other shared library, will +suffice. The dlopen(3) call will map the library into the process's address +space. Furthermore, almost any library call may be implemented using this +technique. +Examples include brk(2), malloc(3), pthread_create(3), and the PAM libraries +(http://www.linux-pam.org). +.IP +Given the above limitations, one of the very few ways to use this option +safely is: mmap() a region, without specifying MAP_FIXED. Then, within that +region, call mmap(MAP_FIXED) to suballocate regions. This avoids both the +portability problem (because the first mmap call lets the kernel pick the +address), and the address space corruption problem (because the region being +overwritten is already owned by the calling thread). +.IP +Newer kernels +(Linux 4.16 and later) have a +.B MAP_FIXED_SAFE +option that avoids the corruption problem; if available, MAP_FIXED_SAFE +should be preferred over MAP_FIXED. .TP .B MAP_GROWSDOWN This flag is used for stacks. -- 2.15.1