friedkiwi/ibm-information-center
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
0332907f0f
ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/mprotect.htm

417 lines
12 KiB
HTML
Raw Blame History

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
<title>mprotect()--Change Access Protection for Memory Mapping</title>
<!-- Begin Header Records -->
<!-- All rights reserved. Licensed Materials Property of IBM -->
<!-- US Government Users Restricted Rights -->
<!-- Use, duplication or disclosure restricted by -->
<!-- GSA ADP Schedule Contract with IBM Corp. -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!-- MPROTECT SCRIPT A converted by B2H R4.1 (346) (CMS) by V2CDIJAB -->
<!-- at RCHVMW2 on 19 Sep 2000 at 14:23:34 -->
<!-- Change History: -->
<!-- 011108 JTROUS Changes from CL Review 1, V5R2 -->
<!-- 0205?? JET This file has undergone html cleanup -->
<!-- 020918 Rosckes: Add ENOTAVAIL errno description, V5R3 -->
<!-- 050404 JTROUS: fix enums, no change flag, V5R4 -->
<!-- 050404 JTROUS Add note on tagged pointers, V5R4 -->
<!-- End Header Records -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body>
<!-- Java sync-link -->
<script language="Javascript" src="../rzahg/synch.js" type="text/javascript">
</script>
<a name="Top_Of_Page"></a>
<h2>mprotect()--Change Access Protection for Memory Mapping</h2>
<div class="box" style="width: 60%;">
<br>
&nbsp;&nbsp;Syntax<br>
<pre>
#include &lt;sys/types.h&gt;
#include &lt;sys/mman.h&gt;
int mprotect( void <em>*addr</em>,
size_t <em>len</em>,
int <em>protection</em>);
</pre>
&nbsp;&nbsp;Service Program Name: QP0LLIB1<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Yes<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The <strong>mprotect()</strong> function is used to change the access
protection of a memory mapping to that specified by <em>protection</em>. All
whole pages of the process's address space, that were established by the
<strong>mmap()</strong> function, addressed from <em>addr</em> continuing for a
length of <em>len</em> will be affected by the change of access protection. You
may specify PROT_NONE, PROT_READ, PROT_WRITE, or the inclusive or of PROT_READ
and PROT_WRITE as values for the <em>protect</em> parameter.</p>
<br>
<h3>Parameters</h3>
<dl>
<dt><strong><em>addr</em></strong></dt>
<dd>(Input) The starting address of the memory region for which the access is
to be changed.
<p>The <em>addr</em> argument must be a multiple of the page size. The
<a href="sysconf.htm">sysconf()</a> function may be used to determine the system page size.<br>
<br>
</p>
</dd>
<dt><strong><em>len</em></strong></dt>
<dd>(Input) The length in bytes of the address range.<br>
<br>
</dd>
<dt><strong><em>protection</em></strong></dt>
<dd>(Input) The desired access protection. You may specify PROT_NONE,
PROT_READ, PROT_WRITE, or the inclusive or of PROT_READ AND PROT_WRITE as
values for the <em>protection</em> argument.
<p>No access through the memory mapping will be permitted if PROT_NONE is
specified.</p>
<p>Storage associated with the mapping cannot be altered unless the PROT_WRITE
value is specified.</p>
<p>For shared mappings, PROT_WRITE requires that the file descriptor used to
establish the map had been opened for write access. A shared mapping is a
mapping created with the <strong><em>MAP_SHARED</em></strong> value of the flag
parameter of the <strong>mmap()</strong> function.</p>
<p>Since private mappings do not alter the underlying file, PROT_WRITE may be
specified for a mapping that had been created MAP_PRIVATE and had been opened
for read access.</p>
<p>The following table shows the symbolic constants allowed for the protection
argument.</p>
<table border cellpadding="5" width="80%">
<tr>
<th align="left" valign="top">Symbolic Constant</th>
<th align="left" valign="top">Decimal<br>
Value</th>
<th align="left" valign="bottom">Description</th>
</tr>
<tr>
<td align="left" valign="top" width="20%">PROT_WRITE</td>
<td align="center" valign="top" width="15%">2</td>
<td align="left" valign="top" width="65%">Write access allowed.</td>
</tr>
<tr>
<td align="left" valign="top">PROT_READ</td>
<td align="center" valign="top">2</td>
<td align="left" valign="top">Read access allowed.</td>
</tr>
<tr>
<td align="left" valign="top">PROT_NONE</td>
<td align="center" valign="top">8</td>
<td align="left" valign="top">No access allowed.</td>
</tr>
</table>
<br>
</dd>
</dl>
<br>
<h3>Authorities</h3>
<p>No authorization is required.</p>
<br>
<h3>Return Value</h3>
<p>Upon successful completion, the <strong>mprotect()</strong> function returns
0. Upon failure, -1 is returned and errno is set to the appropriate error
number.</p>
<br>
<h3>Error Conditions</h3>
<p>When the <strong>mprotect()</strong> function fails, it returns -1 and sets
there errno variable as follows.</p>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<th align="left" valign="bottom">Error condition</th>
<th align="left" valign="bottom">Additional information</th>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EACCES">EACCES</a>]</em></td>
<td align="left" valign="top">
<p>If you are accessing a remote file through the Network File System, update
operations to file permissions at the server are not reflected at the client
until updates to data that is stored locally by the Network File System take
place. (Several options on the Add Mounted File System (ADDMFS) command
determine the time between refresh operations of local data.) Access to a
remote file may also fail due to different mappings of user IDs (UID) or group
IDs (GID) on the local and remote systems.</p>
<p>The <em>protection</em> argument specifies a protection that violates the
access permission the process has to the underlying mapped file.</p>
<p>If the QSHRMEMCTL system value was 0 at the time the mapping was created,
then this continues to limit the allowed access until the mapping is destroyed.
An attempt to change the protection of a shared mapping to PROT_WRITE when the
QSHRMEMCTL system value had been zero at the time of map creation will result
in an errno of EACCES.</p>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EINVAL">EINVAL</a>]</em></td>
<td align="left" valign="top">
<p>For example, the <em>addr</em> argument is not a multiple of the page size.
This error number also may indicate that the value of the <em>len</em>
argument is 0.</p>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENOMEM">ENOMEM</a>]</em></td>
<td align="left" valign="top">
<p>The <em>addr</em> argument is out of the allowed range.</p>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENOTAVAIL">ENOTAVAIL</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENOTSUP">ENOTSUP</a>]</em></td>
<td align="left" valign="top">
<p>For <strong>mprotect()</strong> this can be caused by an invalid combination
of access requests on the <em>protection</em> parameter.</p>
</td>
</tr>
</table>
<br>
<br>
<h3>Error Messages</h3>
<p>The following messages may be sent from this function.</p>
<table width="100%">
<tr>
<th align="left" valign="top">Message ID</th>
<th align="left" valign="top">Error Message Text</th>
</tr>
<tr>
<td width="15%" valign="top">CPE3418 E</td>
<td width="85%" valign="top">Possible APAR condition or hardware failure.</td>
</tr>
<tr>
<td valign="top">CPFA0D4 E</td>
<td valign="top">File system error occurred. Error number &amp;1.</td>
</tr>
<tr>
<td valign="top">CPF3CF2 E</td>
<td valign="top">Error(s) occurred during running of &amp;1 API.</td>
</tr>
<tr>
<td valign="top">CPF9872 E</td>
<td valign="top">Program or service program &amp;1 in library &amp;2 ended.
Reason code &amp;3.</td>
</tr>
</table>
<br>
<br>
<h3>Usage Notes</h3>
<ol>
<li>The address pointer that was returned by <strong>mmap()</strong> can only
be used with the V4R4M0 or later versions of the following languages:
<ul>
<li>ILE COBOL</li>
<li>ILE RPG</li>
<li>ILE C if the TERASPACE parameter is used when compiling the program.</li>
</ul>
<br>
</li>
<li>
<img src="delta.gif" alt="Start of change">
The application cannot write or store any data via the memory mapping which
includes any tagged (16-byte) pointers because the pointer attribute will be lost.
Some examples of tagged pointers include space pointers, system pointers,
invocation pointers etc..
<p>If the DTAMDL(*LLP64) parameter is used when compiling an ILE C program,
this limitation does not apply as the pointers will be 8 byte pointers, and their
pointer attribute will be preserved.
<img src="deltaend.gif" alt="End of change">
</li>
</ol>
<br>
<h3>Related Information</h3>
<ul>
<li><a href="creat.htm">creat()</a>--Create or Rewrite File
</li>
<li><a href="creat64.htm">creat64()</a>--Create or Rewrite a File (Large File
Enabled)
</li>
<li><a href="mmap.htm">mmap()</a>--Memory Map a Stream File
</li>
<li><a href="munmap.htm">munmap()</a>--Remove Memory Mapping
</li>
<li><a href="msync.htm">msync()</a>--Synchronize Modified Data with Mapped
File</li>
<li><a href="open.htm">open()</a>--Open File
</li>
<li><a href="open64.htm">open64()</a>--Open File (Large File Enabled)
</li>
<li><a href="sysconf.htm">sysconf()</a>--Get system configuration variables</li>
</ul>
<br>
<h3>Example</h3>
<p>See <a href="../apiref/aboutapis.htm#codedisclaimer">Code disclaimer information</a>
for information pertaining to code examples.</p>
<p>The following example creates a file, produces a memory mapping of the file
using <strong>mmap()</strong>, and then changes the protection of the file
using <strong>mprotect()</strong>.</p>
<pre>
#include &lt;errno.h&gt;
#include &lt;fcntl.h&gt;
#include &lt;unistd.h&gt;
#include &lt;stdio.h&gt;
#include &lt;stdlib.h&gt;
#include &lt;string.h&gt;
#include &lt;sys/types.h&gt;
#include &lt;sys/mman.h&gt;
main(void) {
size_t bytesWritten =0;
int fd;
int PageSize;
char text&Yacute; = "This is a test";
if ( (PageSize = sysconf(_SC_PAGE_SIZE)) &lt; 0) {
perror("sysconf() Error=");
return -1;
}
fd = open("/tmp/mmprotectTest",
(O_CREAT | O_TRUNC | O_RDWR),
(S_IRWXU | S_IRWXG | S_IRWXO) );
if ( fd &lt; 0 ) {
perror("open() error");
return fd;
}
off_t lastoffset = lseek( fd, 0, SEEK_SET);
bytesWritten = write(fd, text, strlen(text));
if (bytesWritten != strlen(text) ) {
perror("write error. ");
return -1;
}
lastoffset = lseek( fd, PageSize-1, SEEK_SET);
bytesWritten = write(fd, " ", 1); /* grow file to 1 page. */
if ( bytesWritten != 1 ) {
perror("write error. ");
return -1;
}
/* mmap the file. */
void *address;
int len;
off_t my_offset = 0;
len = PageSize; /* Map one page */
address =
mmap(NULL, len, PROT_NONE, MAP_SHARED, fd, my_offset);
if ( address == MAP_FAILED ) {
perror("mmap error. " );
return -1;
}
if ( mprotect( address, len, PROT_WRITE) &lt; 0 ) {
perror("mprotect failed with error:");
return -1;
}
else (void) printf("%s",address);
close(fd);
unlink("/tmp/mmprotectTest");
}
</pre>
<hr>
API introduced: V5R1
<hr>
<center>
<table cellpadding="2" cellspacing="2">
<tr align="center">
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
"unix.htm">UNIX-Type APIs</a> | <a href="aplist.htm">APIs by category</a></td>
</tr>
</table>
</center>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink