FTOK(3C) Standard C Library Functions FTOK(3C)
NAME
ftok - generate an IPC key
SYNOPSIS
#include <sys/ipc.h>
key_t ftok(
const char *path,
int id);
DESCRIPTION
The
ftok() function returns a key based on
path and
id that is usable
in subsequent calls to
msgget(2),
semget(2) and
shmget(2). The
path argument must be the pathname of an existing file that the process is
able to
stat(2).
The
ftok() function will return the same key value for all paths that
name the same file, when called with the same
id value, and will
return different key values when called with different
id values.
If the file named by
path is removed while still referred to by a
key, a call to
ftok() with the same
path and
id returns an error. If
the same file is recreated, then a call to
ftok() with the same
path and
id is likely to return a different key.
Only the low order 8-bits of
id are significant. The behavior of
ftok() is unspecified if these bits are 0.
RETURN VALUES
Upon successful completion,
ftok() returns a key. Otherwise,
ftok() returns
(key_t)-1 and sets
errno to indicate the error.
ERRORS
The
ftok() function will fail if:
EACCES Search permission is denied for a component of the
path prefix.
ELOOP Too many symbolic links were encountered in resolving
path.
ENAMETOOLONG The length of the
path argument exceeds
{PATH_MAX} or
a pathname component is longer than
{NAME_MAX}.
ENOENT A component of
path does not name an existing file or
path is an empty string.
ENOTDIR A component of the path prefix is not a directory.
The
ftok() function may fail if:
ENAMETOOLONG Pathname resolution of a symbolic link produced an
intermediate result whose length exceeds
{PATH_MAX}.
USAGE
For maximum portability,
id should be a single-byte character.
Another way to compose keys is to include the project ID in the most
significant byte and to use the remaining portion as a sequence
number. There are many other ways to form keys, but it is necessary
for each system to define standards for forming them. If some
standard is not adhered to, it will be possible for unrelated
processes to unintentionally interfere with each other's operation.
It is still possible to interfere intentionally. Therefore, it is
strongly suggested that the most significant byte of a key in some
sense refer to a project so that keys do not conflict across a given
system.
NOTES
Since the
ftok() function returns a value based on the
id given and
the file serial number of the file named by
path in a type that is no
longer large enough to hold all file serial numbers, it may return
the same key for paths naming different files on large filesystems.
ATTRIBUTES
See
attributes(7) for descriptions of the following attributes:
+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | Standard |
+--------------------+-----------------+
|MT-Level | MT-Safe |
+--------------------+-----------------+
SEE ALSO
msgget(2),
semget(2),
shmget(2),
stat(2),
attributes(7),
standards(7) February 17, 2023 FTOK(3C)
