freebsd-src/lib/libc/sys/mprotect.2

.\" 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.
.\" 3. 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.
.\"
.\"	@(#)mprotect.2	8.1 (Berkeley) 6/9/93
.\" $FreeBSD$
.\"
.Dd June 20, 2019
.Dt MPROTECT 2
.Os
.Sh NAME
.Nm mprotect
.Nd control the protection of pages
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In sys/mman.h
.Ft int
.Fn mprotect "void *addr" "size_t len" "int prot"
.Sh DESCRIPTION
The
.Fn mprotect
system call
changes the specified pages to have protection
.Fa prot .
Not all implementations will guarantee protection on a page basis;
the granularity of protection changes may be as large as an entire region.
A region is the virtual address space defined by the start
and end addresses of a
.Vt "struct vm_map_entry" .
.Pp
Currently these protection bits are known,
which can be combined, OR'd together:
.Pp
.Bl -tag -width ".Dv PROT_WRITE" -compact
.It Dv PROT_NONE
No permissions at all.
.It Dv PROT_READ
The pages can be read.
.It Dv PROT_WRITE
The pages can be written.
.It Dv PROT_EXEC
The pages can be executed.
.El
.Pp
In addition to these protection flags,
.Fx
provides the ability to set the maximum protection of a region
(which prevents
.Nm
from upgrading the permissions).
This is accomplished by
.Em or Ns 'ing
one or more
.Dv PROT_
values wrapped in the
.Dv PROT_MAX()
macro into the
.Fa prot
argument.
.Sh RETURN VALUES
.Rv -std mprotect
.Sh ERRORS
The
.Fn mprotect
system call will fail if:
.Bl -tag -width Er
.It Bq Er EACCES
The calling process was not allowed to change
the protection to the value specified by
the
.Fa prot
argument.
.It Bq Er EINVAL
The virtual address range specified by the
.Fa addr
and
.Fa len
arguments is not valid.
.It Bq Er EINVAL
The
.Fa prot
argument contains unhandled bits.
.It Bq Er EINVAL
The
.Fa prot
argument contains permissions which are not a subset of the specified
maximum permissions.
.El
.Sh SEE ALSO
.Xr madvise 2 ,
.Xr mincore 2 ,
.Xr msync 2 ,
.Xr munmap 2
.Sh HISTORY
The
.Fn mprotect
system call was first documented in
.Bx 4.2
and first appeared in
.Bx 4.4 .
.Pp
The
.Dv PROT_MAX
functionality was introduced in
.Fx 13 .
BSD 4.4 Lite Lib Sources 1994-05-27 05:00:24 +00:00			`.\" 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.`
Renumber copyright clause 4 Renumber cluase 4 to 3, per what everybody else did when BSD granted them permission to remove clause 3. My insistance on keeping the same numbering for legal reasons is too pedantic, so give up on that point. Submitted by: Jan Schaumann <jschauma@stevens.edu> Pull Request: https://github.com/freebsd/freebsd/pull/96 2017-02-28 23:42:47 +00:00			`.\" 3. Neither the name of the University nor the names of its contributors`
BSD 4.4 Lite Lib Sources 1994-05-27 05:00:24 +00:00			`.\" 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.`
			`.\"`
			`.\" @(#)mprotect.2 8.1 (Berkeley) 6/9/93`
$Id$ -> $FreeBSD$ 1999-08-28 00:22:10 +00:00			`.\" $FreeBSD$`
BSD 4.4 Lite Lib Sources 1994-05-27 05:00:24 +00:00			`.\"`
Extend mmap/mprotect API to specify the max page protections. A new macro PROT_MAX() alters a protection value so it can be OR'd with a regular protection value to specify the maximum permissions. If present, these flags specify the maximum permissions. While these flags are non-portable, they can be used in portable code with simple ifdefs to expand PROT_MAX() to 0. This change allows (e.g.) a region that must be writable during run-time linking or JIT code generation to be made permanently read+execute after writes are complete. This complements W^X protections allowing more precise control by the programmer. This change alters mprotect argument checking and returns an error when unhandled protection flags are set. This differs from POSIX (in that POSIX only specifies an error), but is the documented behavior on Linux and more closely matches historical mmap behavior. In addition to explicit setting of the maximum permissions, an experimental sysctl vm.imply_prot_max causes mmap to assume that the initial permissions requested should be the maximum when the sysctl is set to 1. PROT_NONE mappings are excluded from this for compatibility with rtld and other consumers that use such mappings to reserve address space before mapping contents into part of the reservation. A final version this is expected to provide per-binary and per-process opt-in/out options and this sysctl will go away in its current form. As such it is undocumented. Reviewed by: emaste, kib (prior version), markj Additional suggestions from: alc Obtained from: CheriBSD Sponsored by: DARPA, AFRL Differential Revision: https://reviews.freebsd.org/D18880 2019-06-20 18:24:16 +00:00			`.Dd June 20, 2019`
BSD 4.4 Lite Lib Sources 1994-05-27 05:00:24 +00:00			`.Dt MPROTECT 2`
			`.Os`
			`.Sh NAME`
			`.Nm mprotect`
			`.Nd control the protection of pages`
Introduce ".Lb" macro to libc manpages. More libraries manpages updates following. 2000-04-21 09:42:15 +00:00			`.Sh LIBRARY`
			`.Lb libc`
BSD 4.4 Lite Lib Sources 1994-05-27 05:00:24 +00:00			`.Sh SYNOPSIS`
mdoc(7) police: Use the new .In macro for #include statements. 2001-10-01 16:09:29 +00:00			`.In sys/mman.h`
Add RETURN VALUES and ERRORS sections. 1997-01-11 23:20:29 +00:00			`.Ft int`
mprotect(): Change prototype to comply to POSIX. Our mprotect() function seems to take a "const void " address to the pages whose permissions need to be adjusted. POSIX uses "void ". Simply stick to the POSIX one to prevent us from writing unportable code. PR: 211423 (exp-run) Tested by: antoine@ (Thanks!) 2016-08-03 06:33:04 +00:00			`.Fn mprotect "void *addr" "size_t len" "int prot"`
BSD 4.4 Lite Lib Sources 1994-05-27 05:00:24 +00:00			`.Sh DESCRIPTION`
			`The`
			`.Fn mprotect`
			`system call`
			`changes the specified pages to have protection`
			`.Fa prot .`
			`Not all implementations will guarantee protection on a page basis;`
			`the granularity of protection changes may be as large as an entire region.`
Document protection bits. PR: 46252 Submitted by: Jeroen Ruigrok van der Werven <asmodai@wxs.nl> 2002-12-23 19:25:03 +00:00			`A region is the virtual address space defined by the start`
			`and end addresses of a`
			`.Vt "struct vm_map_entry" .`
			`.Pp`
			`Currently these protection bits are known,`
			`which can be combined, OR'd together:`
mdoc(7) police: markup laundry. 2003-02-23 01:47:49 +00:00			`.Pp`
			`.Bl -tag -width ".Dv PROT_WRITE" -compact`
			`.It Dv PROT_NONE`
Document protection bits. PR: 46252 Submitted by: Jeroen Ruigrok van der Werven <asmodai@wxs.nl> 2002-12-23 19:25:03 +00:00			`No permissions at all.`
mdoc(7) police: markup laundry. 2003-02-23 01:47:49 +00:00			`.It Dv PROT_READ`
Document protection bits. PR: 46252 Submitted by: Jeroen Ruigrok van der Werven <asmodai@wxs.nl> 2002-12-23 19:25:03 +00:00			`The pages can be read.`
mdoc(7) police: markup laundry. 2003-02-23 01:47:49 +00:00			`.It Dv PROT_WRITE`
Document protection bits. PR: 46252 Submitted by: Jeroen Ruigrok van der Werven <asmodai@wxs.nl> 2002-12-23 19:25:03 +00:00			`The pages can be written.`
mdoc(7) police: markup laundry. 2003-02-23 01:47:49 +00:00			`.It Dv PROT_EXEC`
Document protection bits. PR: 46252 Submitted by: Jeroen Ruigrok van der Werven <asmodai@wxs.nl> 2002-12-23 19:25:03 +00:00			`The pages can be executed.`
			`.El`
Extend mmap/mprotect API to specify the max page protections. A new macro PROT_MAX() alters a protection value so it can be OR'd with a regular protection value to specify the maximum permissions. If present, these flags specify the maximum permissions. While these flags are non-portable, they can be used in portable code with simple ifdefs to expand PROT_MAX() to 0. This change allows (e.g.) a region that must be writable during run-time linking or JIT code generation to be made permanently read+execute after writes are complete. This complements W^X protections allowing more precise control by the programmer. This change alters mprotect argument checking and returns an error when unhandled protection flags are set. This differs from POSIX (in that POSIX only specifies an error), but is the documented behavior on Linux and more closely matches historical mmap behavior. In addition to explicit setting of the maximum permissions, an experimental sysctl vm.imply_prot_max causes mmap to assume that the initial permissions requested should be the maximum when the sysctl is set to 1. PROT_NONE mappings are excluded from this for compatibility with rtld and other consumers that use such mappings to reserve address space before mapping contents into part of the reservation. A final version this is expected to provide per-binary and per-process opt-in/out options and this sysctl will go away in its current form. As such it is undocumented. Reviewed by: emaste, kib (prior version), markj Additional suggestions from: alc Obtained from: CheriBSD Sponsored by: DARPA, AFRL Differential Revision: https://reviews.freebsd.org/D18880 2019-06-20 18:24:16 +00:00			`.Pp`
			`In addition to these protection flags,`
			`.Fx`
			`provides the ability to set the maximum protection of a region`
			`(which prevents`
			`.Nm`
			`from upgrading the permissions).`
			`This is accomplished by`
			`.Em or Ns 'ing`
			`one or more`
			`.Dv PROT_`
			`values wrapped in the`
			`.Dv PROT_MAX()`
			`macro into the`
			`.Fa prot`
			`argument.`
Add RETURN VALUES and ERRORS sections. 1997-01-11 23:20:29 +00:00			`.Sh RETURN VALUES`
Use the ``.Rv -std'' mdoc(7) macro in appropriate cases. Reviewed by: ru 2001-08-09 13:32:13 +00:00			`.Rv -std mprotect`
Add RETURN VALUES and ERRORS sections. 1997-01-11 23:20:29 +00:00			`.Sh ERRORS`
			`The`
			`.Fn mprotect`
mdoc(7) police: Tidy up the syscall language. Stop calling system calls "function calls". Use "The .Fn system call" a-la "The .Nm utility". When referring to a non-BSD implementation in the HISTORY section, call syscall a function, to be safe. 2002-12-18 09:22:32 +00:00			`system call will fail if:`
Add RETURN VALUES and ERRORS sections. 1997-01-11 23:20:29 +00:00			`.Bl -tag -width Er`
mprotect.2: sort errors alphabetically Reported by: brooks MFC after: 3 days 2020-02-26 18:46:41 +00:00			`.It Bq Er EACCES`
			`The calling process was not allowed to change`
			`the protection to the value specified by`
			`the`
			`.Fa prot`
			`argument.`
Add RETURN VALUES and ERRORS sections. 1997-01-11 23:20:29 +00:00			`.It Bq Er EINVAL`
			`The virtual address range specified by the`
			`.Fa addr`
			`and`
			`.Fa len`
			`arguments is not valid.`
Extend mmap/mprotect API to specify the max page protections. A new macro PROT_MAX() alters a protection value so it can be OR'd with a regular protection value to specify the maximum permissions. If present, these flags specify the maximum permissions. While these flags are non-portable, they can be used in portable code with simple ifdefs to expand PROT_MAX() to 0. This change allows (e.g.) a region that must be writable during run-time linking or JIT code generation to be made permanently read+execute after writes are complete. This complements W^X protections allowing more precise control by the programmer. This change alters mprotect argument checking and returns an error when unhandled protection flags are set. This differs from POSIX (in that POSIX only specifies an error), but is the documented behavior on Linux and more closely matches historical mmap behavior. In addition to explicit setting of the maximum permissions, an experimental sysctl vm.imply_prot_max causes mmap to assume that the initial permissions requested should be the maximum when the sysctl is set to 1. PROT_NONE mappings are excluded from this for compatibility with rtld and other consumers that use such mappings to reserve address space before mapping contents into part of the reservation. A final version this is expected to provide per-binary and per-process opt-in/out options and this sysctl will go away in its current form. As such it is undocumented. Reviewed by: emaste, kib (prior version), markj Additional suggestions from: alc Obtained from: CheriBSD Sponsored by: DARPA, AFRL Differential Revision: https://reviews.freebsd.org/D18880 2019-06-20 18:24:16 +00:00			`.It Bq Er EINVAL`
			`The`
			`.Fa prot`
			`argument contains unhandled bits.`
			`.It Bq Er EINVAL`
			`The`
			`.Fa prot`
			`argument contains permissions which are not a subset of the specified`
			`maximum permissions.`
Forgot a .El macro. 1997-01-11 23:26:44 +00:00			`.El`
BSD 4.4 Lite Lib Sources 1994-05-27 05:00:24 +00:00			`.Sh SEE ALSO`
			`.Xr madvise 2 ,`
Add RETURN VALUES and ERRORS sections. 1997-01-11 23:20:29 +00:00			`.Xr mincore 2 ,`
			`.Xr msync 2 ,`
			`.Xr munmap 2`
BSD 4.4 Lite Lib Sources 1994-05-27 05:00:24 +00:00			`.Sh HISTORY`
			`The`
			`.Fn mprotect`
Add PROT_MAX to the HISTORY section. In the case of mmap(), add a HISTORY section. Mention that mmap() and mprotect()'s documentation predates an implementation. The implementation first saw wide use in 4.3-Reno, but there seems to be no easy way to express that in mdoc so stick with 4.4BSD. Reviewed by: emaste Requested by: cem Sponsored by: DARPA, AFRL Differential Revision: https://reviews.freebsd.org/D20713 2019-06-20 21:52:30 +00:00			`system call was first documented in`
			`.Bx 4.2`
			`and first appeared in`
Correctly use .Fn instead of .Nm to reference function names in a bunch of man pages. Use the correct .Bx (BSD UNIX) or .At (AT&T UNIX) macros instead of explicitly specifying the version in the text in a bunch of man pages. 1996-08-22 23:31:07 +00:00			`.Bx 4.4 .`
Add PROT_MAX to the HISTORY section. In the case of mmap(), add a HISTORY section. Mention that mmap() and mprotect()'s documentation predates an implementation. The implementation first saw wide use in 4.3-Reno, but there seems to be no easy way to express that in mdoc so stick with 4.4BSD. Reviewed by: emaste Requested by: cem Sponsored by: DARPA, AFRL Differential Revision: https://reviews.freebsd.org/D20713 2019-06-20 21:52:30 +00:00			`.Pp`
			`The`
			`.Dv PROT_MAX`
			`functionality was introduced in`
			`.Fx 13 .`