ftok(3) - f38

1ftok(3)                    Library Functions Manual                    ftok(3)
2
3
4

NAME

6       ftok  -  convert  a pathname and a project identifier to a System V IPC
7       key
8

LIBRARY

10       Standard C library (libc, -lc)
11

SYNOPSIS

13       #include <sys/ipc.h>
14
15       key_t ftok(const char *pathname, int proj_id);
16

DESCRIPTION

18       The ftok() function uses the identity of the file named  by  the  given
19       pathname  (which  must  refer  to an existing, accessible file) and the
20       least significant 8 bits of proj_id (which must be nonzero) to generate
21       a  key_t  type  System  V  IPC  key,  suitable  for use with msgget(2),
22       semget(2), or shmget(2).
23
24       The resulting value is the same for all pathnames that  name  the  same
25       file,  when  the  same  value  of  proj_id is used.  The value returned
26       should be different when the (simultaneously  existing)  files  or  the
27       project IDs differ.
28

RETURN VALUE

30       On  success,  the  generated key_t value is returned.  On failure -1 is
31       returned, with errno indicating the error as  for  the  stat(2)  system
32       call.
33

ATTRIBUTES

35       For  an  explanation  of  the  terms  used  in  this  section,  see at‐
36       tributes(7).
37
38       ┌────────────────────────────────────────────┬───────────────┬─────────┐
39       │Interface                                   │ Attribute     │ Value   │
40       ├────────────────────────────────────────────┼───────────────┼─────────┤
41       │ftok()                                      │ Thread safety │ MT-Safe │
42       └────────────────────────────────────────────┴───────────────┴─────────┘
43

STANDARDS

45       POSIX.1-2008.
46

HISTORY

48       POSIX.1-2001.
49

NOTES

51       On some ancient systems, the prototype was:
52
53           key_t ftok(char *pathname, char proj_id);
54
55       Today, proj_id is an int, but still only 8 bits are used.  Typical  us‐
56       age has an ASCII character proj_id, that is why the behavior is said to
57       be undefined when proj_id is zero.
58
59       Of course, no guarantee can  be  given  that  the  resulting  key_t  is
60       unique.   Typically,  a  best-effort attempt combines the given proj_id
61       byte, the lower 16 bits of the inode number, and the lower  8  bits  of
62       the  device number into a 32-bit result.  Collisions may easily happen,
63       for example between files on /dev/hda1 and files on /dev/sda1.
64

EXAMPLES

66       See semget(2).
67