ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/ipcshmgt.htm

488 lines
16 KiB
HTML
Raw Normal View History

2024-04-02 14:02:31 +00:00
<!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>shmget()-Get ID of Shared Memory Segment with Key</title>
<!-- Begin Header Records ========================================== -->
<!-- Direct1 SCRIPT J converted by B2H R4.1 (346) (CMS) by V2KEA304 -->
<!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 -->
<!-- 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 -->
<!-- Edited by Kersten Feb 02 -->
<!-- This file has undergone html cleanup on 05/01/02 by JET -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body>
<!--End Header Records -->
<!-- Java sync-link -->
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
</script>
<a name="Top_Of_Page"></a>
<h2>shmget()--Get ID of Shared Memory Segment with Key</h2>
<div class="box" style="width: 70%;"><br>
&nbsp;&nbsp;Syntax<br>
<pre>
#include &lt;sys/shm.h&gt;
#include &lt;sys/stat.h&gt;
int shmget(key_t <em>key</em>, size_t <em>size</em>, int <em>shmflg</em>);
</pre>
<br>
&nbsp;&nbsp;Service Program Name: QP0ZUSHR<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>shmget()</strong> function either creates a new shared memory
segment or returns the shared memory identifier associated with the <em>key</em>
parameter for an existing shared memory segment. A new shared memory segment is
created if one of the following is true:
<ul>
<li>The <em>key</em> parameter is equal to IPC_PRIVATE.<br>
<br>
</li>
<li>The <em>key</em> parameter does not already have a shared memory identifier
associated with it and the IPC_CREAT flag is specified in the <em>shmflg</em> parameter.<br>
</li>
</ul>
<p>The system maintains status information about a shared memory segment which can be
retrieved with the <a href="ipcshmct.htm">shmctl()</a> function. When a new
shared memory segment is created, the system initializes the members of the
<samp>shmid_ds</samp> structure as follows:
<ul>
<li><samp>shm_perm.cuid</samp> and <samp>shm_perm.uid</samp> are set
equal to the effective user ID of the calling thread.<br>
<br>
</li>
<li><samp>shm_perm.cgid</samp> and <samp>shm_perm.gid</samp> are set
equal to the effective group ID of the calling thread.<br>
<br>
</li>
<li>The low-order 9 bits of <samp>shm_perm.mode</samp> are set equal to the
low-order 9 bits of the <em>shmflg</em> parameter.<br>
<br>
</li>
<li><samp>shm_segsz</samp> is set to the value specified in the <em>
size</em> parameter.<br>
<br>
</li>
<li><samp>shm_ctime</samp> is set to the current time.<br>
<br>
</li>
<li><samp>shm_lpid</samp>, <samp>shm_nattch</samp>, <samp>shm_atime</samp>, and
<samp>shm_dtime</samp> are set to zero.<br>
<br>
</li>
</ul>
<p>There are two types of shared memory segments: teraspace shared memory segments and
nonteraspace shared memory segments. A teraspace shared memory segment is accessed by
adding the shared memory segment to a job's teraspace.
A nonteraspace shared memory segment creates shared memory using i5/OS
space objects.</p>
<p>Shared memory segments larger than 16&nbsp;773&nbsp;120 bytes (16 MB minus
4096 bytes) should be created as teraspace shared memory segments.
The maximum size of a teraspace shared memory segment is
4&nbsp;294&nbsp;967&nbsp;295 bytes (4GB - 1). The maximum size of a resizeable
teraspace shared memory segment is 268&nbsp;435&nbsp;456 bytes (256 MB).</p>
<p>The maximum size of a nonteraspace shared memory segments is
16&nbsp;776&nbsp;960 bytes (16 MB - 256 bytes). When the
operating system accesses a nonteraspace shared memory segment that has a size
in the range 16&nbsp;773&nbsp;120 bytes (16 MB minus 4096 bytes) to
16&nbsp;776&nbsp;960 bytes (16 MB minus 256 bytes), a performance degradation
will be observed.</p>
<p>The size of the shared memory segment can be changed after it is created using the
<a href="ipcshmct.htm">shmctl()</a> function. The size can only be changed if it is
nonteraspace shared memory segment or if it is a teraspace shared memory segment and
SHM_RESIZE_NP is specified in the <em>shmflg</em> parameter.</p>
<br>
<h3>Parameters</h3>
<dl>
<dt><strong>key</strong></dt>
<dd>(Input) The key associated with the shared memory segment. A key of
IPC_PRIVATE (0x00000000) guarantees that a unique shared memory segment
is created. A key can also be specified by the caller or generated by the
<a href="p0zftok.htm">ftok()</a> function.<br>
<br>
</dd>
<dt><strong>size</strong></dt>
<dd>(Input) The size of the shared memory segment being created. If an existing shared
memory segment is being accessed, <em>size</em> may be zero.<br>
<br>
</dd>
<dt><strong>shmflg</strong></dt>
<dd>(Input) Operation and permission flags. The value of the <em>shmflg</em> parameter
is either zero or is obtained by performing an OR operation on one or more of the
following constants:<p>
<dl>
<dt><strong>S_IRUSR (0x00000100)</strong></dt>
<dd>Allow the owner of the shared memory segment to attach to it in read mode.<p></dd>
<dt><strong>S_IWUSR (0x00000080)</strong></dt>
<dd>Allow the owner of the shared memory segment to attach to it in write mode.<p></dd>
<dt><strong>S_IRGRP (0x00000020)</strong></dt>
<dd>Allow the group of the shared memory segment to attach to it in read mode.<p></dd>
<dt><strong>S_IWGRP (0x00000010)</strong></dt>
<dd>Allow the group of the shared memory segment to attach to it in write mode.<p></dd>
<dt><strong>S_IROTH (0x00000004)</strong></dt>
<dd>Allow others to attach to the shared memory segment in read mode.<p></dd>
<dt><strong>S_IWOTH (0x00000002)</strong></dt>
<dd>Allow others to attach to the shared memory segment in write mode.<p></dd>
<dt><strong>IPC_CREAT (0x00000200)</strong></dt>
<dd>Create the shared memory segment if it does not exist.<p></dd>
<dt><strong>IPC_EXCL (0x00000400)</strong></dt>
<dd>Return an error if the IPC_CREAT flag is set and the shared memory segment already exists.<p></dd>
<dt><strong>SHM_TS_NP (0x00010000)</strong></dt>
<dd>If creating a new shared memory segment, make the shared memory segment a
teraspace shared memory segment. When a job attaches to the shared memory
segment, the shared memory segment will be added to the job's teraspace.
Some compilers permit the user to indicate that the teraspace versions of
storage functions should be used. For example, if a C module is compiled using
CRTCMOD TERASPACE(*YES *TSIFC), this flag will be set automatically.
<p>If accessing an existing shared memory segment, only specify this constant
if it was specified when the shared memory segment was created.<p>
</dd>
<dt><strong>SHM_RESIZE_NP (0x00040000)</strong></dt>
<dd>If creating a new teraspace shared memory segment, allow the size of the
shared memory segment to be changed with the <a href="ipcshmct.htm">shmctl()</a>
function. The maximum size of this teraspace shared memory segment is
268&nbsp;435&nbsp;456 bytes (256 MB). This
flag is ignored for nonteraspace shared memory segments. A nonteraspace shared
memory segment may always be resized up to 16&nbsp;773&nbsp;120 bytes (16 MB -
4096 bytes).<p></dd>
<dt><strong>SHM_MAP_FIXED_NP (0x00100000)</strong></dt>
<dd>If creating a new teraspace shared memory segment, make all jobs that successfully
attach to the shared memory segment attach to the shared memory segment at the same
address. The shared memory segment may not be attached in read-only mode. This
flag is ignored for nonteraspace shared memory segments.
<p>If accessing an existing shared memory segment, only specify this constant
if it was specified when the shared memory segment was created.<p>
</dd>
</dl>
</dd>
</dl>
<br>
<br>
<h3>Authorities</h3>
<p><strong><a name="TBLAHGET1">Authorization Required for
shmget()</a></strong></p>
<table border cellpadding="5">
<!-- cols="60 20 20" -->
<tr>
<th align="left" valign="bottom">Object Referred to</th>
<th align="left" valign="bottom">Authority Required</th>
<th align="left" valign="bottom">errno</th>
</tr>
<tr>
<td align="left" valign="top">Shared memory segment to be created</td>
<td align="left" valign="top">None</td>
<td align="left" valign="top">None</td>
</tr>
<tr>
<td align="left" valign="top">Existing shared memory segment to be
accessed</td>
<td align="left" valign="top">See Note</td>
<td align="left" valign="top">EACCES</td>
</tr>
</table>
<p><strong>Note:</strong> If the thread is accessing a shared memory segment
that already exists, the mode specified in the last 9 bits of the <em>shmflg</em>
parameter must be a subset of the mode of the existing shared memory segment.</p>
<br>
<h3>Return Value</h3>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>value</em></td>
<td align="left" valign="top"><strong>shmget()</strong>was successful. The
value returned is the shared memory identifier associated with the <em>key</em> parameter.</td>
</tr>
<tr>
<td align="left" valign="top"><em>-1</em></td>
<td align="left" valign="top"><strong>shmget()</strong> was not successful. The
<em>errno</em> variable is set to indicate the error.</td>
</tr>
</table>
<br>
<br>
<h3>Error Conditions</h3>
<p>If <strong>shmget()</strong> is not successful, <em>errno</em> usually
indicates one of the following errors. Under some conditions, <em>errno</em>
could indicate an error other than those listed here.</p>
<dl>
<dt><em>[EACCES]</em></dt>
<dd>
<p>Permission denied.</p>
<p>An attempt was made to access an object in a way forbidden by its object
access permissions.</p>
<p>The thread does not have access to the specified file, directory, component,
or path.</p>
<p>A shared memory identifier exists for the parameter <em>key</em>, but
permissions specified in the low-order 9 bits of <em>semflg</em>
are not a subset of the current permissions.</p>
<p>Shared memory operations are not permitted because the QSHRMEMCTL system
value is set to 0.</p>
</dd>
<dt><em>[EDAMAGE]</em></dt>
<dd>
<p>A damaged object was encountered.</p>
<p>The shared memory segment has been damaged by a previous shared memory operation.</p>
</dd>
<dt><em>[EEXIST]</em></dt>
<dd>
<p>File exists.</p>
<p>The file specified already exists and the specified operation requires that
it not exist.</p>
<p>The named file, directory, or path already exists.</p>
<p>A shared memory identifier exists for the <em>key</em> parameter and both
the IPC_CREAT and IPC_EXCL flags are set in the <em>shmflg</em> parameter.</p>
</dd>
<dt><em>[EINVAL]</em></dt>
<dd>
<p>The value specified for the argument is not correct.</p>
<p>A function was passed incorrect argument values, or an operation was
attempted on an object and the operation specified is not supported for that
type of object.</p>
<p>An argument value is not valid, out of range, or NULL.</p>
<p>One of the following has occurred:</p>
<ul>
<li>The value of the <em>size</em> parameter is less than the system-imposed
minimum or greater than the system-imposed maximum.</li>
<li>A shared memory identifier exists for the <em>key</em> parameter and the
size of the segment associated with it is less than <em>size</em> and <em>
size</em> is not zero.</li>
<li>A shared memory identifier exists for the <em>key</em> parameter and the
SHM_MAP_FIXED_NP or SHM_TS_NP attributes of the shared memory segment do not
match the flags set in the <em>shmflg</em> parameter.</li>
</ul><br>
</dd>
<dt><em>[ENOENT]</em></dt>
<dd>
<p>No such path or directory.</p>
<p>The directory or a component of the path name specified does not exist.</p>
<p>A named file or directory does not exist or is an empty string.</p>
<p>A shared memory identifier does not exist for the <em>key</em> parameter
and the IPC_CREAT flag is not set in the <em>shmflg</em> parameter.</p>
</dd>
<dt><em>[ENOMEM]</em></dt>
<dd>
<p>Storage allocation request failed.</p>
<p>A function needed to allocate storage, but no storage is available.</p>
<p>A new shared memory segment is being created and the amount of available
physical memory is not sufficient to fulfill the request.</p>
</dd>
<dt><em>[ENOSPC]</em></dt>
<dd>
<p>No space available.</p>
<p>The requested operations required additional space on the device and there
is no space left. This could also be caused by exceeding the user profile
storage limit when creating or transferring ownership of an object.</p>
<p>Insufficient space remains to hold the intended file, directory, or
link.</p>
<p>A shared memory identifier cannot be created because the system limit on
the maximum number of allowed shared memory identifiers would be
exceeded.</p>
</dd>
<dt><em>[EUNKNOWN]</em></dt>
<dd>
<p>Unknown system state.</p>
<p>The operation failed because of an unknown system state. See any messages in
the job log and correct any errors that are indicated, then retry the
operation.</p>
</dd>
</dl>
<br>
<h3>Error Messages</h3>
<p>None.</p>
<br>
<h3><a name="USAGE_NOTES">Usage Notes</a></h3>
<ol>
<li>The best way to generate a unique key is to use the <a href="p0zftok.htm">ftok()</a>
function.<br>
<br>
</li>
<li>When the operating system accesses a nonteraspace shared memory segment that has a size
in the range 16&nbsp;773&nbsp;120 bytes (16 MB minus 4096 bytes) to
16&nbsp;776&nbsp;960 bytes (16 MB minus 256 bytes), a performance degradation
will be observed. Use a teraspace shared memory segment if the size of the segment
is larger than 16&nbsp;773&nbsp;120 bytes.<br>
<br>
</li>
<li>Use the <a href="ipcshmat.htm">shmat()</a> function to get addressability
to the shared memory segment after the shared memory identifier is obtained.<br>
<br>
</li>
<li>The storage for a shared memory segment is not allocated until it is
attached to a job. A job will not be able to attach to a shared memory
segment that is larger than the amount of storage available on the system.<br>
<br>
</li>
<li>Jobs cannot attach a nonteraspace shared memory segment in read-only
or write-only mode. Consequently, permissions that specify read-only or
write-only will always result in <strong>shmat()</strong> returning with a
return value of -1 and <em>errno</em> set to EOPNOTSUPP. Jobs
are permitted to attach a teraspace shared memory segment in read-only
mode.<br>
<br>
</li>
</ol>
<br>
<h3>Related Information</h3>
<ul>
<li>The &lt;<strong>sys/shm.h</strong>&gt; file (see <a href="unix13.htm">
Header Files for UNIX-Type Functions</a>)<br>
<br>
</li>
<li><a href="p0zftok.htm">ftok()</a>--Generate IPC Key from File Name<br>
<br>
</li>
<li><a href="ipcshmat.htm">shmat()</a>--Attach Shared Memory Segment to Current
Process<br>
<br>
</li>
<li><a href="ipcshmct.htm">shmctl()</a>--Perform Shared Memory Control
Operations<br>
<br>
</li>
<li><a href="ipcshmdt.htm">shmdt()</a>--Detach Shared Memory Segment from
Calling Process</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>For an example of using this function, see <a href="../apiref/apiexusmem.htm">
Using Semaphores and Shared Memory</a> in Examples: APIs.</p>
<br>
<hr>
API introduced: V3R6
<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>