Debian Codegraph @

upstream/debian-unstable/man3/ftok.3

raw
1 '\" t
2 .\" Copyright 1993, Giorgio Ciucci <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH ftok 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 ftok \- convert a pathname and a project identifier to a System V IPC key
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <sys/ipc.h>
16 .fi
17 .P
18 .BI "key_t ftok(const char *" path ", int " proj_id );
19 .SH DESCRIPTION
20 The
21 .BR ftok ()
22 function uses the identity of the file named by the given
23 .I path
24 (which must refer to an existing, accessible file)
25 and the least significant 8 bits of
26 .I proj_id
27 (which must be nonzero) to generate a
28 .I key_t
29 type System V IPC key, suitable for use with
30 .BR msgget (2),
31 .BR semget (2),
32 or
33 .BR shmget (2).
34 .P
35 The resulting value is the same for all pathnames that
36 name the same file, when the same value of
37 .I proj_id
38 is used.
39 The value returned should be different when the
40 (simultaneously existing) files or the project IDs differ.
41 .SH RETURN VALUE
42 On success, the generated
43 .I key_t
44 value is returned.
45 On failure \-1 is returned, with
46 .I errno
47 indicating the error as for the
48 .BR stat (2)
49 system call.
50 .SH ATTRIBUTES
51 For an explanation of the terms used in this section, see
52 .BR attributes (7).
53 .TS
54 allbox;
55 lbx lb lb
56 l l l.
57 Interface Attribute Value
58 T{
59 .na
60 .nh
61 .BR ftok ()
62 T} Thread safety MT-Safe
63 .TE
64 .SH STANDARDS
65 POSIX.1-2008.
66 .SH HISTORY
67 POSIX.1-2001.
68 .SH NOTES
69 On some ancient systems, the prototype was:
70 .P
71 .in +4n
72 .EX
73 .BI "key_t ftok(char *" path ", char " proj_id );
74 .EE
75 .in
76 .P
77 Today,
78 .I proj_id
79 is an
80 .IR int ,
81 but still only 8 bits are used.
82 Typical usage has an ASCII character
83 .IR proj_id ,
84 that is why the behavior is said to be undefined when
85 .I proj_id
86 is zero.
87 .P
88 Of course, no guarantee can be given that the resulting
89 .I key_t
90 is unique.
91 Typically, a best-effort attempt combines the given
92 .I proj_id
93 byte, the lower 16 bits of the inode number, and the
94 lower 8 bits of the device number into a 32-bit result.
95 Collisions may easily happen, for example between files on
96 .I /dev/hda1
97 and files on
98 .IR /dev/sda1 .
99 .SH EXAMPLES
100 See
101 .BR semget (2).
102 .SH SEE ALSO
103 .BR msgget (2),
104 .BR semget (2),
105 .BR shmget (2),
106 .BR stat (2),
107 .BR sysvipc (7)