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

563 lines
14 KiB
HTML
Raw Normal View History

Add readme and dist folders
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>ftok()--Generate IPC Key from File Name</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 -->
<!-- Direct1 SCRIPT J converted by B2H R4.1 (346) (CMS) by V2KEA304 -->
<!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 -->
<!-- Edited by Kersten Feb 02 -->
<!-- This file has undergone html cleanup on 05/01/02 by JET -->
<!-- 020618 EMIG: updated for NFS threadsafety, V5R3 -->
<!-- 020719 MFENLON: updated for QFileSvr.400 threadsafety, V5R3 -->
<!-- End Header Records -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body>
<!-- Java sync-link -->
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
</script>
<a name="Top_Of_Page"></a>
<h2>ftok()--Generate IPC Key from File Name</h2>
<div class="box" style="width: 60%;">
<br>
&nbsp;&nbsp;Syntax<br>
<pre>
#include &lt;sys/ipc.h&gt;
key_t ftok(const char <em>*path</em>, int <em>id</em>);
</pre>
<br>
&nbsp;&nbsp;Service Program Name: QP0ZCPA<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Conditional; see <a href="#USAGE_NOTES">Usage Notes</a>.<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The <strong>ftok()</strong> function generates an IPC key based on the
combination of <em>path</em> and <em>id</em>.</p>
<p>Identifier-based interprocess communication facilities require you to supply
a key to the <strong>msgget()</strong>, <strong>semget()</strong>, <strong>
shmget()</strong> subroutines to obtain interprocess communication identifiers.
The <strong>ftok()</strong> function is one mechanism to generate these
keys.</p>
<p>If the values for <em>path</em> and <em>id</em> are the same as a previous
call to <strong>ftok()</strong> and the file named by <em>path</em> was not
deleted and re-created in between calls to <strong>ftok()</strong>, <strong>
ftok()</strong> will return the same key.</p>
<p>The <strong>ftok()</strong> function returns different keys if different
values of <em>path</em> and <em>id</em> are used.</p>
<p>Only the low-order 8-bits of <em>id</em> are significant. The remaining bits
are ignored by <strong>ftok()</strong>.</p>
<br>
<h3>Parameters</h3>
<dl>
<dt><strong>path</strong></dt>
<dd>(Input) The path name of the file used in combination with <em>id</em> to
generate the key.
<p>See <a href="p0zftoku.htm">QlgFtok--Generate IPC Key from File Name (using
NLS-enabled path name)</a> for a description and an example of supplying the
<em>path</em> in any CCSID.</p>
</dd>
<dt><strong>id</strong></dt>
<dd>(Input) The integer identifier used in combination with <em>path</em> to
generate the key. Only the low order 8-bits of <em>id</em> are significant. The
remaining bits will be ignored.</dd>
</dl>
<br>
<h3>Authorities</h3>
<p><strong><a name="TBLASTAT1">Authorization Required for ftok() (excluding
QOPT)</a></strong></p>
<table border width="80%" 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">Each directory in the path name preceding the
object</td>
<td align="left" valign="top">*X</td>
<td align="left" valign="top">EACCES</td>
</tr>
<tr>
<td align="left" valign="top">Object</td>
<td align="left" valign="top">None</td>
<td align="left" valign="top">None</td>
</tr>
</table>
<br>
<br>
<p><strong><a name="TBLASTAT4">Authorization Required for ftok() in the QOPT
File System</a></strong></p>
<table border width="80%" 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">Volume containing directory or object</td>
<td align="left" valign="top">*USE</td>
<td align="left" valign="top">EACCES</td>
</tr>
<tr>
<td align="left" valign="top">Directory or object within volume</td>
<td align="left" valign="top">None</td>
<td align="left" valign="top">None</td>
</tr>
</table>
<br>
<br>
<h3>Return Value</h3>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>value</em></td>
<td align="left" valign="top"><strong>ftok()</strong> was successful.</td>
</tr>
<tr>
<td align="left" valign="top"><em>(key_t)-1</em></td>
<td align="left" valign="top"><strong>ftok()</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>ftok()</strong> is not successful, <em>errno</em> indicates one
of the following errors.</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>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>
</dd>
<dt><em>[EAGAIN]</em></dt>
<dd>
<p>Operation would have caused the process to be suspended.</p>
</dd>
<dt><em>[EBADFID]</em></dt>
<dd>
<p>A file ID could not be assigned when linking an object to a directory.</p>
<p>The file ID table is missing or damaged.</p>
<p>To recover from this error, run the Reclaim Storage (RCLSTG) command as soon
as possible.</p>
</dd>
<dt><em>[EBADNAME]</em></dt>
<dd>
<p>The object name specified is not correct.</p>
</dd>
<dt><em>[EBUSY]</em></dt>
<dd>
<p>Resource busy.</p>
<p>An attempt was made to use a system resource that is not available at this
time.</p>
</dd>
<dt><em>[ECONVERT]</em></dt>
<dd>
<p>Conversion error.</p>
<p>One or more characters could not be converted from the source CCSID to the
target CCSID.</p>
</dd>
<dt><em>[EDAMAGE]</em></dt>
<dd>
<p>A damaged object was encountered.</p>
<p>A referenced object is damaged. The object cannot be used.</p>
</dd>
<dt><em>[EFAULT]</em></dt>
<dd>
<p>The address used for an argument is not correct.</p>
<p>In attempting to use an argument in a call, the system detected an address
that is not valid.</p>
<p>While attempting to access a parameter passed to this function, the system
detected an address that is not valid.</p>
</dd>
<dt><em>[EFILECVT]</em></dt>
<dd>
<p>File ID conversion of a directory failed.</p>
<p>Try to run the Reclaim Storage (RCLSTG) command to recover from this
error.</p>
</dd>
<dt><em>[EINTR]</em></dt>
<dd>
<p>Interrupted function call.</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>
</dd>
<dt><em>[EIO]</em></dt>
<dd>
<p>Input/output error.</p>
<p>A physical I/O error occurred.</p>
<p>A referenced object may be damaged.</p>
</dd>
<dt><em>[ELOOP]</em></dt>
<dd>
<p>A loop exists in the symbolic links.</p>
<p>This error is issued if the number of symbolic links encountered is more
than POSIX_SYMLOOP (defined in the limits.h header file). Symbolic links are
encountered during resolution of the directory or path name.</p>
</dd>
<dt><em>[ENAMETOOLONG]</em></dt>
<dd>
<p>A path name is too long.</p>
<p>A path name is longer than PATH_MAX characters or some component of the name
is longer than NAME_MAX characters while _POSIX_NO_TRUNC is in effect. For
symbolic links, the length of the name string substituted for a symbolic link
exceeds PATH_MAX. The PATH_MAX and NAME_MAX values can be determined using the
<strong>pathconf()</strong> function.</p>
</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>
</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>There is not enough memory to perform the requested function.</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>
</dd>
<dt><em>[ENOTDIR]</em></dt>
<dd>
<p>Not a directory.</p>
<p>A component of the specified path name existed, but it was not a directory
when a directory was expected.</p>
<p>Some component of the path name is not a directory, or is an empty
string.</p>
</dd>
<dt><em>[ENOTSAFE]</em></dt>
<dd>
<p>Function is not allowed in a job that is running with multiple threads.</p>
</dd>
<dt><em>[ENOTSUP]</em></dt>
<dd>
<p>Operation not supported.</p>
<p>The operation, though supported in general, is not supported for the
requested object or the requested arguments.</p>
</dd>
<dt><em>[EPERM]</em></dt>
<dd>
<p>Operation not permitted.</p>
<p>You must have appropriate privileges or be the owner of the object or other
resource to do the requested operation.</p>
</dd>
<dt><em>[EROOBJ]</em></dt>
<dd>
<p>Object is read only.</p>
<p>You have attempted to update an object that can be read only.</p>
</dd>
<dt><em>[ESTALE]</em></dt>
<dd>
<p>File or object handle rejected by server.</p>
<p>If you are accessing a remote file through the Network File System, the file
may have been deleted at the server.</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><a name="USAGE_NOTES">Usage Notes</a></h3>
<ol>
<li>This function will fail with error code [ENOTSAFE] when both of the
following conditions occur:<br>
<br>
<ul>
<li>Where multiple threads exist in the job.<br>
<br>
</li>
<li>The object this function is operating on resides in a file system that is
not threadsafe. Only the following file systems are threadsafe for this
function:<br>
<br>
<ul>
<li>Root</li>
<li>QOpenSys</li>
<li>User-defined</li>
<li>QNTC</li>
<li>QSYS.LIB</li>
<li>Independent ASP QSYS.LIB</li>
<li>QOPT</li>
<li>Network File System</li>
<li>QFileSvr.400</li>
</ul>
</li>
</ul>
<br>
<br>
</li>
<li>If the values for <em>path</em> and <em>id</em> are the same as a previous
call to <strong>ftok()</strong> and if the file named by <em>path</em> was
deleted and re-created in between calls to <strong>ftok()</strong>, <strong>
ftok()</strong> will return a different key.<br>
<br>
</li>
<li>The <strong>ftok()</strong> function will return the same key for different
values of <em>path</em> if the path names refer to symbolic links or hard links
whose target files are the same.<br>
<br>
</li>
<li>The <strong>ftok()</strong> function may return the same key for different
values of <em>path</em> if the target files are in different file systems.<br>
<br>
</li>
<li>The <strong>ftok()</strong> function may return the same key for different
values of <em>path</em> if the target file is in a file system that contains
more than 2<sup>24</sup> files.</li>
</ol>
<br>
<h3>Related Information</h3>
<ul>
<li><a href="p0zftoku.htm">QlgFtok</a>--Generate IPC Key from File Name (using
NLS-enabled path name)<br>
<br>
</li>
<li><a href="ipcmsggt.htm">msgget()</a>--Get Message Queue<br>
<br>
</li>
<li><a href="ipcsemgt.htm">semget()</a>--Get Semaphore Set with Key<br>
<br>
</li>
<li><a href="ipcshmgt.htm">shmget()</a>--Get ID of Shared Memory Segment with
Key</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 uses <strong>ftok()</strong> and <strong>
semget()</strong> functions.</p>
<pre>
#include &lt;sys/ipc.h&gt;
#include &lt;sys/sem.h&gt;
#include &lt;errno.h&gt;
#include &lt;stdio.h&gt;
int main(int argc, char *argv[])
{
key_t myKey;
int semid;
/* Use ftok to generate a key associated with a file. */
/* Every process will get the same key back if the */
/* caller calls with the same parameters. */
myKey = ftok("/myApplication/myFile", 42);
if(myKey == -1) {
printf("ftok failed with errno = %d\n", errno);
return -1;
}
/* Call an xxxget() API, where xxx is sem, shm, or msg. */
/* This will create or reference an existing IPC object */
/* with the 'well known' key associated with the file */
/* name used above. */
semid = semget(myKey, 1, 0666 | IPC_CREAT);
if(semid == -1) {
printf("semget failed with errno = %d\n", errno);
return -1;
}
/* ... Use the semaphore as required ... */
return 0;
}
</pre>
<br>
<hr>
API introduced: V4R3
<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 Copy Permalink