422 lines
11 KiB
Groff
422 lines
11 KiB
Groff
.\" Copyright (c) 1991, 1993
|
|
.\" The Regents of the University of California. All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 4. Neither the name of the University nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" @(#)mmap.2 8.4 (Berkeley) 5/11/95
|
|
.\" $FreeBSD: src/lib/libc/sys/mmap.2,v 1.56 2007/01/09 00:28:15 imp Exp $
|
|
.\"
|
|
.Dd February 14, 2020
|
|
.Dt MMAP 2
|
|
.Os
|
|
.Sh NAME
|
|
.Nm mmap
|
|
.Nd allocate memory, or map files or devices into memory
|
|
.Sh LIBRARY
|
|
.Lb libc
|
|
.Sh SYNOPSIS
|
|
.In sys/mman.h
|
|
.Ft void *
|
|
.Fn mmap "void *addr" "size_t len" "int prot" "int flags" "int fd" "off_t offset"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Fn mmap
|
|
system call causes the pages starting at
|
|
.Fa addr
|
|
and continuing for at most
|
|
.Fa len
|
|
bytes to be mapped from the object described by
|
|
.Fa fd ,
|
|
starting at byte offset
|
|
.Fa offset .
|
|
If
|
|
.Fa offset
|
|
or
|
|
.Fa len
|
|
is not a multiple of the pagesize, the mapped region may extend past the
|
|
specified range.
|
|
Any extension beyond the end of the mapped object will be zero-filled.
|
|
.Pp
|
|
The
|
|
.Fa addr
|
|
argument is used by the system to determine the starting address of the mapping,
|
|
and its interpretation is dependent on the setting of the MAP_FIXED flag.
|
|
If MAP_FIXED is specified in
|
|
.Fa flags ,
|
|
the system will try to place the mapping at the specified address,
|
|
possibly removing a
|
|
mapping that already exists at that location.
|
|
If MAP_FIXED is not specified,
|
|
then the system will attempt to use the range of addresses starting at
|
|
.Fa addr
|
|
if they do not overlap any existing mappings,
|
|
including memory allocated by
|
|
.Xr malloc 3
|
|
and other such allocators.
|
|
Otherwise,
|
|
the system will choose an alternate address for the mapping (using an implementation
|
|
dependent algorithm)
|
|
that does not overlap any existing
|
|
mappings.
|
|
In other words,
|
|
without
|
|
.Dv MAP_FIXED
|
|
the system will attempt to find an empty location in the address space if the
|
|
specified address range has already been mapped by something else.
|
|
If
|
|
.Fa addr
|
|
is zero and MAP_FIXED is not specified,
|
|
then an address will be selected by the system so as not to overlap
|
|
any existing mappings in the address space.
|
|
In all cases,
|
|
the actual starting address of the region is returned.
|
|
If MAP_FIXED is specified,
|
|
a successful
|
|
.Fa mmap
|
|
deletes any previous mapping in the allocated address range.
|
|
Previous mappings are never deleted if MAP_FIXED is not specified.
|
|
.Pp
|
|
The protections (region accessibility) are specified in the
|
|
.Fa prot
|
|
argument by
|
|
.Em or Ns 'ing
|
|
the following values:
|
|
.Pp
|
|
.Bl -tag -width PROT_WRITE -compact
|
|
.It Dv PROT_NONE
|
|
Pages may not be accessed.
|
|
.It Dv PROT_READ
|
|
Pages may be read.
|
|
.It Dv PROT_WRITE
|
|
Pages may be written.
|
|
.It Dv PROT_EXEC
|
|
Pages may be executed.
|
|
.El
|
|
.Pp
|
|
Note that, due to hardware limitations, on some platforms PROT_WRITE may
|
|
imply PROT_READ, and PROT_READ may imply PROT_EXEC. Portable programs
|
|
should not rely on these flags being separately enforceable.
|
|
.Pp
|
|
When the hardened runtime is enabled
|
|
.Po
|
|
See the links in the
|
|
.Sx SEE ALSO
|
|
section
|
|
.Pc ,
|
|
the protections cannot be both
|
|
.Dv PROT_WRITE
|
|
and
|
|
.Dv PROT_EXEC
|
|
without also having the flag
|
|
.Dv MAP_JIT
|
|
and the process possessing the
|
|
.Dv com.apple.security.cs.allow-jit
|
|
entitlement
|
|
.Pp
|
|
The
|
|
.Fa flags
|
|
argument specifies the type of the mapped object, mapping options and
|
|
whether modifications made to the mapped copy of the page are private
|
|
to the process (copy-on-write) or are to be shared with other references.
|
|
Sharing, mapping type and options are specified in the
|
|
.Fa flags
|
|
argument by
|
|
.Em or Ns 'ing
|
|
the following values:
|
|
.Bl -tag -width MAP_HASSEMAPHORE
|
|
.It Dv MAP_ANONYMOUS
|
|
Synonym for
|
|
.Dv MAP_ANON.
|
|
.It Dv MAP_ANON
|
|
Map anonymous memory not associated with any specific file.
|
|
The
|
|
.Fa offset
|
|
argument is ignored.
|
|
Mac OS X specific: the file descriptor used for creating
|
|
.Dv MAP_ANON
|
|
regions can be used to pass some Mach VM flags, and can
|
|
be specified as \-1 if no such flags are associated with
|
|
the region. Mach VM flags are defined in
|
|
.In mach/vm_statistics.h
|
|
and the ones that currently apply
|
|
to
|
|
.Nm mmap
|
|
are:
|
|
.Pp
|
|
VM_FLAGS_PURGABLE to create Mach purgable (i.e. volatile) memory.
|
|
.Pp
|
|
VM_MAKE_TAG(tag) to associate an 8-bit tag with the region.
|
|
.br
|
|
.In mach/vm_statistics.h
|
|
defines some preset tags (with a VM_MEMORY_ prefix).
|
|
Users are encouraged to use tags between 240 and 255.
|
|
Tags are used by tools such as
|
|
.Xr vmmap 1
|
|
to help identify specific memory regions.
|
|
.It Dv MAP_FILE
|
|
Mapped from a regular file. (This is
|
|
the default mapping type, and need not be specified.)
|
|
.It Dv MAP_FIXED
|
|
Do not permit the system to select a different address than the one
|
|
specified.
|
|
If the specified address cannot be used,
|
|
.Fn mmap
|
|
will fail.
|
|
If
|
|
.Dv MAP_FIXED
|
|
is specified,
|
|
.Fa addr
|
|
must be a multiple of the pagesize.
|
|
If a
|
|
.Dv MAP_FIXED
|
|
request is successful, the mapping established by
|
|
.Fn mmap
|
|
replaces any previous mappings for the process' pages in the range from
|
|
.Fa addr
|
|
to
|
|
.Fa addr
|
|
+
|
|
.Fa len .
|
|
Use of this option is discouraged.
|
|
.It Dv MAP_HASSEMAPHORE
|
|
Notify the kernel that the region may contain semaphores and that special
|
|
handling may be necessary.
|
|
.It Dv MAP_PRIVATE
|
|
Modifications are private (copy-on-write).
|
|
.It Dv MAP_SHARED
|
|
Modifications are shared.
|
|
.It Dv MAP_NOCACHE
|
|
Pages in this mapping are not retained in the kernel's memory cache.
|
|
If the system runs low on memory, pages in MAP_NOCACHE mappings will be among
|
|
the first to be reclaimed.
|
|
This flag is intended for mappings that have little locality and
|
|
provides a hint to the kernel that pages in this mapping are unlikely to be needed
|
|
again in the near future.
|
|
.It Dv MAP_JIT
|
|
Allow mapping pages both
|
|
.Dv PROT_WRITE
|
|
and
|
|
.Dv PROT_EXEC
|
|
when the hardened runtime is enabled. Without this flag an attempt to create a
|
|
mapping with both
|
|
.Dv PROT_WRITE
|
|
and
|
|
.Dv PROT_EXEC
|
|
set will fail with
|
|
.Dv MAP_FAILED
|
|
on macOS. A writable, but not executable mapping
|
|
is returned on iOS, watchOS and tvOS.
|
|
.Pp
|
|
Usage of this flag requires the caller to have the
|
|
.Dv com.apple.security.cs.allow-jit
|
|
entitlement on macOS.
|
|
.It Dv MAP_32BIT
|
|
Directs
|
|
.Fn mmap
|
|
to place the mapping into the first 4 Gigabytes of the process's address space. If
|
|
there is no free virtual address space in this range,
|
|
.Fn mmap
|
|
will return
|
|
.Dv MAP_FAILED.
|
|
.Pp
|
|
Note that in order for this flag to yield addresses below 4GiB, the program's
|
|
PAGEZERO must be reduced in size, since the default PAGEZERO size for 64-bit
|
|
programs is at least 4GiB.
|
|
.El
|
|
.Pp
|
|
Conforming applications must specify either MAP_PRIVATE or MAP_SHARED.
|
|
.Pp
|
|
The
|
|
.Xr close 2
|
|
system call does not unmap pages, see
|
|
.Xr munmap 2
|
|
for further information.
|
|
.Pp
|
|
The current design does not allow a process to specify the location of
|
|
swap space.
|
|
In the future we may define an additional mapping type,
|
|
.Dv MAP_SWAP ,
|
|
in which
|
|
the file descriptor argument specifies a file or device to which swapping
|
|
should be done.
|
|
.Sh RETURN VALUES
|
|
Upon successful completion,
|
|
.Fn mmap
|
|
returns a pointer to the mapped region.
|
|
Otherwise, a value of
|
|
.Dv MAP_FAILED
|
|
is returned and
|
|
.Va errno
|
|
is set to indicate the error.
|
|
.Sh ERRORS
|
|
The
|
|
.Fn mmap
|
|
system call
|
|
will fail if:
|
|
.Bl -tag -width Er
|
|
.It Bq Er EACCES
|
|
The flag
|
|
.Dv PROT_READ
|
|
was specified as part of the
|
|
.Fa prot
|
|
argument and
|
|
.Fa fd
|
|
was not open for reading.
|
|
The flags
|
|
.Dv MAP_SHARED
|
|
and
|
|
.Dv PROT_WRITE
|
|
were specified as part of the
|
|
.Fa flags
|
|
and
|
|
.Fa prot
|
|
argument and
|
|
.Fa fd
|
|
was not open for writing.
|
|
.It Bq Er EBADF
|
|
The
|
|
.Fa fd
|
|
argument
|
|
is not a valid open file descriptor.
|
|
.It Bq Er EINVAL
|
|
.Dv MAP_FIXED
|
|
was specified and the
|
|
.Fa addr
|
|
argument was not page aligned, or part of the desired address space
|
|
resides out of the valid address space for a user process.
|
|
.It Bq Er EINVAL
|
|
.Fa flags
|
|
does not include either MAP_PRIVATE or MAP_SHARED.
|
|
.It Bq Er EINVAL
|
|
.Fa flags
|
|
includes bits that are not part of any valid flags value.
|
|
.It Bq Er EINVAL
|
|
The
|
|
.Fa len
|
|
argument
|
|
was negative or zero. Historically, the system call would not return an error
|
|
if the argument was zero.
|
|
See other potential additional restrictions in the
|
|
COMPATIBILITY section below.
|
|
.It Bq Er EINVAL
|
|
The
|
|
.Fa offset
|
|
argument
|
|
was not page-aligned based on the page size as returned by getpagesize(3).
|
|
.It Bq Er ENODEV
|
|
.Dv MAP_ANON
|
|
has not been specified and the file
|
|
.Fa fd
|
|
refers to does not support mapping.
|
|
.It Bq Er ENOMEM
|
|
.Dv MAP_FIXED
|
|
was specified and the
|
|
.Fa addr
|
|
argument was not available.
|
|
.Dv MAP_FIXED
|
|
was specified and the address range specified exceeds the address space
|
|
limit for the process.
|
|
.Dv MAP_ANON
|
|
was specified and insufficient memory was available.
|
|
.It Bq Er ENXIO
|
|
Addresses in the specified range are invalid for
|
|
.Fa fd .
|
|
.It Bq Er EOVERFLOW
|
|
Addresses in the specified range exceed the maximum offset
|
|
set for
|
|
.Fa fd .
|
|
.El
|
|
.Sh ENTITLEMENTS
|
|
The following entitlements only have an effect when the hardened runtime is
|
|
enabled.
|
|
.Bl -tag -width Er
|
|
.It Dv com.apple.security.cs.allow-jit
|
|
A Boolean value that indicates whether the app may create writable and
|
|
executable memory using the
|
|
.Dv MAP_JIT
|
|
.Fa flag .
|
|
.It Dv com.apple.security.cs.allow-unsigned-executable-memory
|
|
A Boolean value that indicates whether the app may create writable and
|
|
executable memory without the restrictions imposed by using the
|
|
.Dv MAP_JIT
|
|
.Fa flag .
|
|
.It Dv com.apple.security.cs.disable-executable-page-protection
|
|
A Boolean value that indicates whether to disable all code signing
|
|
protections while launching an application, and during its execution.
|
|
.El
|
|
.Sh LEGACY SYNOPSIS
|
|
.Fd #include <sys/types.h>
|
|
.Fd #include <sys/mman.h>
|
|
.Pp
|
|
The include file
|
|
.In sys/types.h
|
|
is necessary.
|
|
.Sh COMPATIBILITY
|
|
.Fn mmap
|
|
now returns with
|
|
.Va errno
|
|
set to EINVAL in places that historically succeeded.
|
|
The rules have changed as follows:
|
|
.Bl -bullet
|
|
.It
|
|
The
|
|
.Fa flags
|
|
parameter must specify either MAP_PRIVATE or MAP_SHARED.
|
|
.It
|
|
The
|
|
.Fa len
|
|
parameter must not be 0.
|
|
.It
|
|
The
|
|
.Fa off
|
|
parameter must be a multiple of pagesize,
|
|
as returned by
|
|
.Fn sysconf .
|
|
.El
|
|
.Pp
|
|
On macOS 10.14 Mojave the hardened runtime restricts pages from having both
|
|
the
|
|
.Dv PROT_WRITE
|
|
and
|
|
.Dv PROT_EXEC
|
|
protections without the caller also setting the
|
|
.Dv MAP_JIT
|
|
.Fa flag
|
|
and possessing the
|
|
.Dv com.apple.security.cs.allow-jit
|
|
entitlement.
|
|
.Sh SEE ALSO
|
|
.Xr madvise 2 ,
|
|
.Xr mincore 2 ,
|
|
.Xr minherit 2 ,
|
|
.Xr mlock 2 ,
|
|
.Xr mprotect 2 ,
|
|
.Xr msync 2 ,
|
|
.Xr munlock 2 ,
|
|
.Xr munmap 2 ,
|
|
.Xr shmat 2 ,
|
|
.Xr getpagesize 3
|
|
.Ss Apple Developer Documentation
|
|
https://developer.apple.com/documentation/security/hardened_runtime_entitlements
|