From patchwork Fri Jun 14 18:46:05 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: DJ Delorie X-Patchwork-Id: 1948111 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@legolas.ozlabs.org Authentication-Results: legolas.ozlabs.org; dkim=pass (1024-bit key; unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=EIT3c8dN; dkim-atps=neutral Authentication-Results: legolas.ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=sourceware.org (client-ip=8.43.85.97; helo=server2.sourceware.org; envelope-from=libc-alpha-bounces+incoming=patchwork.ozlabs.org@sourceware.org; receiver=patchwork.ozlabs.org) Received: from server2.sourceware.org (server2.sourceware.org [8.43.85.97]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature ECDSA (secp384r1) server-digest SHA384) (No client certificate requested) by legolas.ozlabs.org (Postfix) with ESMTPS id 4W17Xk4sXSz20X9 for ; Sat, 15 Jun 2024 04:46:30 +1000 (AEST) Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id CA2213882126 for ; Fri, 14 Jun 2024 18:46:28 +0000 (GMT) X-Original-To: libc-alpha@sourceware.org Delivered-To: libc-alpha@sourceware.org Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by sourceware.org (Postfix) with ESMTPS id 484843882100 for ; Fri, 14 Jun 2024 18:46:10 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 484843882100 Authentication-Results: sourceware.org; dmarc=pass (p=none dis=none) header.from=redhat.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=redhat.com ARC-Filter: OpenARC Filter v1.0.0 sourceware.org 484843882100 Authentication-Results: server2.sourceware.org; arc=none smtp.remote-ip=170.10.129.124 ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1718390773; cv=none; b=BLvYnFG3w9G/UAhDMFeBAQLrblvmTecYTqhPViUoNGeXid7geNLjX4hoVnB4qdNGhAPFgD39PezSS3C7y4h7HXdtUidAzUocrBZARZljGn9EI1HIgEUhpZZIuA8V+jfJ6wI4vK905GNtgyagaW2NozXwAalpmjME0EP6L6RQXo0= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1718390773; c=relaxed/simple; bh=peC7PCOgNZag1in7ZC+YrHS5L0RHeBQqW1ph+lMgh00=; h=DKIM-Signature:From:To:Subject:Date:Message-ID:MIME-Version; b=N9GywCOdNcApmzIb22LyHKLR1T/Cr8tYg7Y+YT4ozGa624Z9chTmkpa9Mmtw6dM7IvokCLLH7k9W5qjFj7LsqH4mF0/Qt6+Hh4B1r2bWnmcHku8zWjO7uK3i0n88l+ELy/ri+1dmT+UNNs0NxaX6fffj1yz9d1G7y9odXOE8KKU= ARC-Authentication-Results: i=1; server2.sourceware.org DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1718390769; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to; bh=wKKCSr7Y5sFOX7+GAPsVau7kvmInlbT1nOrhVb6ma4A=; b=EIT3c8dNdwaAKKTdW2W97bXpKxVU5Me/AERraaRM0rcFfcKwrU9BZCgJibfq/dst0TuGZY LPKG9nKhARl0GDj+IgdXwAHPzyWtQnxDuWOi8XEjgJ4MriOZgf4T7fDBdaUBw8VaHrhGKQ kZcC6Cx21JSjArYO47RrBQpFfxWMGGI= Received: from mx-prod-mc-03.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-463-avh8R4bzMYyNDbzMJoFQYA-1; Fri, 14 Jun 2024 14:46:08 -0400 X-MC-Unique: avh8R4bzMYyNDbzMJoFQYA-1 Received: from mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.17]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-03.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id A118819560AE for ; Fri, 14 Jun 2024 18:46:07 +0000 (UTC) Received: from greed.delorie.com (unknown [10.22.9.158]) by mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 48B671956058 for ; Fri, 14 Jun 2024 18:46:07 +0000 (UTC) Received: from greed.delorie.com.redhat.com (localhost [127.0.0.1]) by greed.delorie.com (8.16.1/8.16.1) with ESMTP id 45EIk5BL1499709 for ; Fri, 14 Jun 2024 14:46:05 -0400 From: DJ Delorie To: libc-alpha@sourceware.org Subject: [v4] Update mmap() flags and errors lists In-Reply-To: <87tthwszmt.fsf@oldenburg.str.redhat.com> (message from Florian Weimer on Fri, 14 Jun 2024 10:21:46 +0200) Date: Fri, 14 Jun 2024 14:46:05 -0400 Message-ID: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.0 on 10.30.177.17 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com X-Spam-Status: No, score=-9.3 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, RCVD_IN_DNSWL_NONE, RCVD_IN_MSPIKE_H4, RCVD_IN_MSPIKE_WL, RCVD_IN_SBL_CSS, SPF_HELO_NONE, SPF_NONE, TXREP, T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: libc-alpha@sourceware.org X-Mailman-Version: 2.1.30 Precedence: list List-Id: Libc-alpha mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libc-alpha-bounces+incoming=patchwork.ozlabs.org@sourceware.org [v4: tweaked text on MAP_FIXED_NOREPLACE, MAP_POPULATE, MAP_32BIT, and ENOMEM] Extend the list of MAP_* macros to include all macros available to the average program (gcc -E -dM | grep MAP_*) Extend the list of errno codes. diff --git a/manual/llio.texi b/manual/llio.texi index 0d1a32e3e1..7edec3e8d7 100644 --- a/manual/llio.texi +++ b/manual/llio.texi @@ -1574,10 +1574,15 @@ permitted. They include @code{PROT_READ}, @code{PROT_WRITE}, and 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. +The @var{flags} parameter contains flags that control the nature of +the map. One of @code{MAP_SHARED}, @code{MAP_SHARED_VALIDATE}, or +@code{MAP_PRIVATE} must be specified. Additional flags may be bitwise +OR'd to further define the mapping. -They include: +Note that, aside from @code{MAP_PRIVATE} and @code{MAP_SHARED}, not +all flags are supported on all versions of all operating systems. +Consult the kernel-specific documentation for details. The flags +include: @vtable @code @item MAP_PRIVATE @@ -1599,9 +1604,19 @@ Note that actual writing may take place at any time. You need to use @code{msync}, described below, if it is important that other processes using conventional I/O get a consistent view of the file. +@item MAP_SHARED_VALIDATE +Similar to @code{MAP_SHARED} except that additional flags will be +validated by the kernel, and the call will fail if an unrecognized +flag is provided. With @code{MAP_SHARED} using a flag on a kernel +that doesn't support it causes the flag to be ignored. +@code{MAP_SHARED_VALIDATE} should be used when the behavior of all +flags is required. + @item MAP_FIXED This forces the system to use the exact mapping address specified in -@var{address} and fail if it can't. +@var{address} and fail if it can't. Note that if the new mapping +would overlap an existing mapping, the overlapping portion of the +existing map is unmapped. @c One of these is official - the other is obviously an obsolete synonym @c Which is which? @@ -1642,10 +1657,78 @@ The @code{MAP_HUGETLB} flag is specific to Linux. @c There is a mechanism to select different hugepage sizes; see @c include/uapi/asm-generic/hugetlb_encode.h in the kernel sources. -@c Linux has some other MAP_ options, which I have not discussed here. -@c MAP_DENYWRITE, MAP_EXECUTABLE and MAP_GROWSDOWN don't seem applicable to -@c user programs (and I don't understand the last two). MAP_LOCKED does -@c not appear to be implemented. +@item MAP_32BIT +Require addresses that can be accessed with a signed 32 bit pointer, +i.e., within the first 2 GiB. Ignored if MAP_FIXED is specified. + +@item MAP_DENYWRITE +@itemx MAP_EXECUTABLE +@itemx MAP_FILE + +Provided for compatibility. Ignored by the Linux kernel. + +@item MAP_FIXED_NOREPLACE +Similar to @code{MAP_FIXED} except the call will fail with +@code{EEXIST} if the new mapping would overwrite an existing mapping. +To test for this, specify MAP_FIXED_NOREPLACE without MAP_FIXED, and +check the actual address returned. If it does not match the address +passed, then this flag is not supported. + +@item MAP_GROWSDOWN +This flag is used to make stacks, and is typically only needed inside +the program loader to set up the main stack for the running process. +The mapping is created according to the other flags, except an +additional page just prior to the mapping is marked as a ``guard +page''. If a write is attempted inside this guard page, that page is +mapped, the mapping is extended, and a new guard page is created. +Thus, the mapping continues to grow towards lower addresses until it +encounters some other mapping. + +Note that accessing memory beyond the guard page will not trigger this +feature. In gcc, use @code{-fstack-clash-protection} to ensure the +guard page is always touched. + +@item MAP_LOCKED +A hint that requests that mapped pages are locked in memory (i.e. not +paged out). Note that this is a request and not a requirement; use +@code{mlock} if locking is required. + +@item MAP_POPULATE +@itemx MAP_NONBLOCK +These two are opposites. @code{MAP_POPULATE} is a hint that requests +that the kernel read-ahead a file-backed mapping, causing more pages +to be mapped before they're needed. @code{MAP_NONBLOCK} is a hint +that requests that the kernel @emph{not} attempt such, only mapping +pages when they're actually needed. Note that neither of these hints +affects future paging activity, use @code{mlock} if such needs to be +controlled. + +@item MAP_NORESERVE +Asks the kernel to not reserve physical backing for a mapping. This +would be useful for, for example, a very large but sparsely used +mapping which need not be limited in span by available RAM or swap. +Note that writes to such a mapping may cause a @code{SIGSEGV} if the +amount of backing required eventualy exceeds system resources. + +On Linux, this flag's behavior may be overwridden by +@file{/proc/sys/vm/overcommit_memory} as documented in the proc(5) man +page. + +@item MAP_STACK +Ensures that the resulting mapping is suitable for use as a program +stack. For example, the use of huge pages might be precluded. + +@item MAP_SYNC +This flag is used to map persistent memory devices into the running +program in such a way that writes to the mapping are immediately +written to the device as well. Unlike most other flags, this one will +fail unless @code{MAP_SHARED_VALIDATE} is also given. + +@item MAP_UNINITIALIZED +This flag allows the kernel to map anonymous pages without zeroing +them out first. This is, of course, a security risk, and will only +work if the kernel is built to allow it (typically, on single-process +embedded systems). @end vtable @@ -1656,6 +1739,24 @@ Possible errors include: @table @code +@item EACCES + +@var{filedes} was not open for the type of access specified in @var{protect}. + +@item EAGAIN + +The system has temporarily run out of resources. + +@item EBADF + +The @var{fd} passes is invalid, and a valid file descriptor is +required (i.e. MAP_ANONYMOUS was not specified). + +@item EEXIST + +@code{MAP_FIXED_NOREPLACE} was specified and an existing mapping was +found overlapping the requested address range. + @item EINVAL Either @var{address} was unusable (because it is not a multiple of the @@ -1664,23 +1765,33 @@ applicable page size), or inconsistent @var{flags} were given. If @code{MAP_HUGETLB} was specified, the file or system does not support large page sizes. -@item EACCES +@item ENODEV -@var{filedes} was not open for the type of access specified in @var{protect}. +This file is of a type that doesn't support mapping. @item ENOMEM -Either there is not enough memory for the operation, or the process is -out of address space. - -@item ENODEV - -This file is of a type that doesn't support mapping. +There is not enough memory for the operation, the process is out of +address space, or there are too many mappings. On Linux, the maximum +number of mappings can be controlled via +@file{/proc/sys/vm/max_map_count} or, if your OS supports it, via +the @code{vm.max_map_count} @code{sysctl} setting. @item ENOEXEC The file is on a filesystem that doesn't support mapping. +@item EPERM + +@code{PROT_EXEC} was requested but the file is on a filesystem that +was mounted with execution denied. + +@item EOVERFLOW + +Either the offset into the file plus the length of the mapping causes +internal page counts to overflow, or the offset requested exceeds the +length of the file. + @c On Linux, EAGAIN will appear if the file has a conflicting mandatory lock. @c However mandatory locks are not discussed in this manual. @c