#include <sys/ipc.h> key_t ftok(const char *path, int id);
The ftok() function generates an IPC key based on the combination of path and id.
Identifier-based interprocess communication facilities require you to supply a key to the msgget(), semget(), shmget() subroutines to obtain interprocess communication identifiers. The ftok() function is one mechanism to generate these keys.
If the values for path and id are the same as a previous call to ftok() and the file named by path was not deleted and re-created in between calls to ftok(), ftok() will return the same key.
The ftok() function returns different keys if different values of path and id are used.
Only the low-order 8-bits of id are significant. The remaining bits are ignored by ftok().
See QlgFtok--Generate IPC Key from File Name (using NLS-enabled path name) for a description and an example of supplying the path in any CCSID.
Authorization Required for ftok() (excluding QOPT)
| Object Referred to | Authority Required | errno |
|---|---|---|
| Each directory in the path name preceding the object | *X | EACCES |
| Object | None | None |
Authorization Required for ftok() in the QOPT File System
| Object Referred to | Authority Required | errno |
|---|---|---|
| Volume containing directory or object | *USE | EACCES |
| Directory or object within volume | None | None |
| value | ftok() was successful. |
| (key_t)-1 | ftok() was not successful. The errno variable is set to indicate the error. |
If ftok() is not successful, errno indicates one of the following errors.
Permission denied.
An attempt was made to access an object in a way forbidden by its object access permissions.
The thread does not have access to the specified file, directory, component, or path.
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.
Operation would have caused the process to be suspended.
A file ID could not be assigned when linking an object to a directory.
The file ID table is missing or damaged.
To recover from this error, run the Reclaim Storage (RCLSTG) command as soon as possible.
The object name specified is not correct.
Resource busy.
An attempt was made to use a system resource that is not available at this time.
Conversion error.
One or more characters could not be converted from the source CCSID to the target CCSID.
A damaged object was encountered.
A referenced object is damaged. The object cannot be used.
The address used for an argument is not correct.
In attempting to use an argument in a call, the system detected an address that is not valid.
While attempting to access a parameter passed to this function, the system detected an address that is not valid.
File ID conversion of a directory failed.
Try to run the Reclaim Storage (RCLSTG) command to recover from this error.
Interrupted function call.
The value specified for the argument is not correct.
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.
An argument value is not valid, out of range, or NULL.
Input/output error.
A physical I/O error occurred.
A referenced object may be damaged.
A loop exists in the symbolic links.
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.
A path name is too long.
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 pathconf() function.
No such path or directory.
The directory or a component of the path name specified does not exist.
A named file or directory does not exist or is an empty string.
Storage allocation request failed.
A function needed to allocate storage, but no storage is available.
There is not enough memory to perform the requested function.
No space available.
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.
Insufficient space remains to hold the intended file, directory, or link.
Not a directory.
A component of the specified path name existed, but it was not a directory when a directory was expected.
Some component of the path name is not a directory, or is an empty string.
Function is not allowed in a job that is running with multiple threads.
Operation not supported.
The operation, though supported in general, is not supported for the requested object or the requested arguments.
Operation not permitted.
You must have appropriate privileges or be the owner of the object or other resource to do the requested operation.
Object is read only.
You have attempted to update an object that can be read only.
File or object handle rejected by server.
If you are accessing a remote file through the Network File System, the file may have been deleted at the server.
Unknown system state.
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.
See Code disclaimer information for information pertaining to code examples.
The following example uses ftok() and semget() functions.
#include <sys/ipc.h>
#include <sys/sem.h>
#include <errno.h>
#include <stdio.h>
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;
}
| Top | UNIX-Type APIs | APIs by category |