mprotect Subroutine

Purpose

Modifies access protections for memory mapping or shared memory.

Library

Standard C Library (libc.a)

Syntax

#include <sys/types.h>
#include <sys/mman.h>

int mprotect ( addr, len, prot) void *addr; size_t len; int prot;

Description

The mprotect subroutine modifies the access protection of a mapped file or shared memory region or anonymous memory region created by the mmap subroutine. Processes running in an environment where the MPROTECT_SHM=ON environmental variable is defined can also use the mprotect subroutine to modify the access protection of a shared memory region created by the shmget, ra_shmget, or ra_shmgetv subroutine and attached by the shmat subroutine.

Processes running in an environment where the MPROTECT_TXT=ON environmental variable is defined can use the mprotect subroutine to modify access protections on main text, shared library, and loaded code. There is no requirement for these areas to be mapped using the mmap subroutine prior to their modification by the mprotect subroutine. A private copy of any modification to the application text is made using the copy-on-write semantics. Modifications to the content of application text are not persistent. Modifications to the application text will be propagated to the child processes across fork calls. Subsequent modifications by forker and sibling remain private to each other.

The user who protects shared memory with the mprotect subroutine must be also be either the user who created the shared memory descriptor, the user who owns the shared memory descriptor, or the root user.

The mprotect subroutine can only be used on shared memory regions backed with 4 KB or 64 KB pages; shared memory regions backed by 16 MB and 16 GB pages are not supported by the mprotect subroutine. The page size used to back a shared memory region can be obtained using the vmgetinfo subroutine and specifying VM_PAGE_INFO for the command parameter.

The mprotect subroutine cannot be used for shared memory that has been pre-translated. This includes shared memory regions created with the SHM_PIN flag specified to the shmget subroutine as well as shared memory regions that have been pinned using the shmctl subroutine with the SHM_LOCK flag specified.

Parameters

addr

Specifies the address of the region to be modified. Must be a multiple of the page size backing the memory region.

len

Specifies the length, in bytes, of the region to be modified. For shared memory regions backed with 4 KB pages, the len parameter will be rounded off to the next multiple of the page size. Otherwise, the len parameter must be a multiple of the page size backing the memory region.

prot

Specifies the new access permissions for the mapped region. Legitimate values for the prot parameter are the same as those permitted for the mmap subroutine, as follows:

PROT_READ: Region can be read.
PROT_WRITE: Region can be written.
PROT_EXEC: Region can be executed.
PROT_NONE: Region cannot be accessed. PROT_NONE is not a valid prot parameter for shared memory attached with the shmat subroutine.

Return Values

When successful, the mprotect subroutine returns 0. Otherwise, it returns -1 and sets the errno global variable to indicate the error.

Note: The return value for the mprotect subroutine is 0 if it fails because the region given was not created by mmap unless XPG 1170 behavior is requested by setting the XPG_SUS_ENV environment variable to ON.

Error Codes

If the mprotect subroutine is unsuccessful, the errno global variable might be set to one of the following values:

Attention: If the mprotect subroutine is unsuccessful because of a condition other than that specified by the EINVAL error code, the access protection for some pages in the (addr, addr + len) range might have been changed.

Item	Description
EACCES	The prot parameter specifies a protection that conflicts with the access permission set for the underlying file.
EPERM	The user is not the creator or owner of the shared memory region and is not the root user.
ENOTSUP	The prot parameter specified is not valid for the region specified.
EINVAL	The addr or len parameter is not a multiple of the page size backing the memory region.
ENOMEM	The application has requested Single UNIX Specification, Version 2 compliant behavior, but addresses in the range are not valid for the address space of the process, or the addresses specify one or more pages that are not attached to the user's address space by a previous mmap or shmat subroutine call.
ENOTSUP	The shared memory region specified is backed by 64 KB pages, but the addr or len parameter is not 64 KB aligned, or PROT_NONE protection was specified for a shared memory region, or a pre-translated shared memory region was specified, or a shared memory region backed by 16 MB or 16 GB pages was specified.