ftok(3c) - osol9

1ftok(3C)                 Standard C Library Functions                 ftok(3C)
2
3
4

NAME

6       ftok - generate an IPC key
7

SYNOPSIS

9       #include <sys/ipc.h>
10
11       key_t ftok(const char *path, int id);
12
13

DESCRIPTION

15       The  ftok()  function returns a key based on path and id that is usable
16       in subsequent calls to msgget(2), semget(2)  and  shmget(2).  The  path
17       argument  must  be the pathname of an existing file that the process is
18       able to stat(2).
19
20
21       The ftok() function will return the same key value for all  paths  that
22       name the same file, when called with the same id value, and will return
23       different key values when called with different id values.
24
25
26       If the file named by path is removed while still referred to by a  key,
27       a  call  to  ftok()  with the same path and id returns an error. If the
28       same file is recreated, then a call to ftok() with the same path and id
29       is likely to return a different key.
30
31
32       Only  the  low  order  8-bits  of  id are significant.  The behavior of
33       ftok() is unspecified if these bits are 0.
34

RETURN VALUES

36       Upon successful completion, ftok() returns a  key.   Otherwise,  ftok()
37       returns (key_t)−1 and sets errno to indicate the error.
38

ERRORS

40       The ftok() function will fail if:
41
42       EACCES          Search permission is denied for a component of the path
43                       prefix.
44
45
46       ELOOP           Too many symbolic links were encountered  in  resolving
47                       path.
48
49
50       ENAMETOOLONG    The length of the path argument exceeds {PATH_MAX}   or
51                       a pathname component is longer than {NAME_MAX}.
52
53
54       ENOENT          A component of path does not name an existing  file  or
55                       path is an empty string.
56
57
58       ENOTDIR         A component of the path prefix is not a directory.
59
60
61
62       The ftok() function may fail if:
63
64       ENAMETOOLONG    Pathname  resolution  of  a  symbolic  link produced an
65                       intermediate result whose length exceeds {PATH_MAX}  .
66
67

USAGE

69       For maximum portability, id should be a single-byte character.
70
71
72       Another way to compose keys is to include the project ID  in  the  most
73       significant byte and to use the remaining portion as a sequence number.
74       There are many other ways to form keys, but it is  necessary  for  each
75       system  to  define  standards for forming them. If some standard is not
76       adhered to, it will be possible for unrelated processes to unintention‐
77       ally  interfere  with  each  other's operation. It is still possible to
78       interfere intentionally. Therefore, it is strongly suggested  that  the
79       most significant byte of a key in some sense refer to a project so that
80       keys do not conflict across a given system.
81

NOTES

83       Since the ftok() function returns a value based on the id given and the
84       file  serial  number  of  the  file  named by path in a type that is no
85       longer large enough to hold all file serial numbers, it may return  the
86       same key for paths naming different files on large filesystems.
87

ATTRIBUTES

89       See attributes(5) for descriptions of the following attributes:
90
91
92
93
94       ┌─────────────────────────────┬─────────────────────────────┐
95       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
96       ├─────────────────────────────┼─────────────────────────────┤
97       │Interface Stability          │Standard                     │
98       ├─────────────────────────────┼─────────────────────────────┤
99       │MT-Level                     │MT-Safe                      │
100       └─────────────────────────────┴─────────────────────────────┘
101