]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it) |
2 | .\" | |
93015253 | 3 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
4 | .\" Permission is granted to make and distribute verbatim copies of this |
5 | .\" manual provided the copyright notice and this permission notice are | |
6 | .\" preserved on all copies. | |
7 | .\" | |
8 | .\" Permission is granted to copy and distribute modified versions of this | |
9 | .\" manual under the conditions for verbatim copying, provided that the | |
10 | .\" entire resulting derived work is distributed under the terms of a | |
11 | .\" permission notice identical to this one. | |
c13182ef | 12 | .\" |
fea681da MK |
13 | .\" Since the Linux kernel and libraries are constantly changing, this |
14 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
15 | .\" responsibility for errors or omissions, or for damages resulting from | |
16 | .\" the use of the information contained herein. The author(s) may not | |
17 | .\" have taken the same level of care in the production of this manual, | |
18 | .\" which is licensed free of charge, as they might when working | |
19 | .\" professionally. | |
c13182ef | 20 | .\" |
fea681da MK |
21 | .\" Formatted or processed versions of this manual, if unaccompanied by |
22 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 23 | .\" %%%LICENSE_END |
fea681da | 24 | .\" |
c11b1abf | 25 | .\" Modified 2001-11-28, by Michael Kerrisk, <mtk.manpages@gmail.com> |
fea681da MK |
26 | .\" Changed data type of proj_id; minor fixes |
27 | .\" aeb: further fixes; added notes. | |
28 | .\" | |
460495ca | 29 | .TH FTOK 3 2015-08-08 "GNU" "Linux Programmer's Manual" |
fea681da MK |
30 | .SH NAME |
31 | ftok \- convert a pathname and a project identifier to a System V IPC key | |
32 | .SH SYNOPSIS | |
33 | .nf | |
2fadbfb5 MK |
34 | .B #include <sys/types.h> |
35 | .B #include <sys/ipc.h> | |
fea681da | 36 | .fi |
68e4db0a | 37 | .PP |
fea681da MK |
38 | .BI "key_t ftok(const char *" pathname ", int " proj_id ); |
39 | .SH DESCRIPTION | |
40 | The | |
e511ffb6 | 41 | .BR ftok () |
fea681da MK |
42 | function uses the identity of the file named by the given |
43 | .I pathname | |
44 | (which must refer to an existing, accessible file) | |
45 | and the least significant 8 bits of | |
46 | .I proj_id | |
c7094399 | 47 | (which must be nonzero) to generate a |
f19a0f03 | 48 | .I key_t |
fea681da MK |
49 | type System V IPC key, suitable for use with |
50 | .BR msgget (2), | |
51 | .BR semget (2), | |
52 | or | |
53 | .BR shmget (2). | |
dd3568a1 | 54 | .PP |
fea681da MK |
55 | The resulting value is the same for all pathnames that |
56 | name the same file, when the same value of | |
57 | .I proj_id | |
c13182ef MK |
58 | is used. |
59 | The value returned should be different when the | |
fea681da | 60 | (simultaneously existing) files or the project IDs differ. |
47297adb | 61 | .SH RETURN VALUE |
0ef84602 | 62 | On success, the generated |
f19a0f03 | 63 | .I key_t |
c13182ef MK |
64 | value is returned. |
65 | On failure \-1 is returned, with | |
fea681da MK |
66 | .I errno |
67 | indicating the error as for the | |
68 | .BR stat (2) | |
69 | system call. | |
bea300ad | 70 | .SH ATTRIBUTES |
27e8366f MK |
71 | For an explanation of the terms used in this section, see |
72 | .BR attributes (7). | |
73 | .TS | |
74 | allbox; | |
75 | lb lb lb | |
76 | l l l. | |
77 | Interface Attribute Value | |
78 | T{ | |
bea300ad | 79 | .BR ftok () |
27e8366f MK |
80 | T} Thread safety MT-Safe |
81 | .TE | |
47297adb | 82 | .SH CONFORMING TO |
01606565 | 83 | POSIX.1-2001, POSIX.1-2008. |
fea681da | 84 | .SH NOTES |
2c3a7aa1 | 85 | On some ancient systems, the prototype was: |
bdd915e2 MK |
86 | .PP |
87 | .in +4n | |
88 | .EX | |
fea681da | 89 | .BI "key_t ftok(char *" pathname ", char " proj_id ); |
bdd915e2 MK |
90 | .EE |
91 | .in | |
cab87712 | 92 | .PP |
88ba4651 | 93 | Today, |
fea681da MK |
94 | .I proj_id |
95 | is an | |
9ff08aad | 96 | .IR int , |
c13182ef MK |
97 | but still only 8 bits are used. |
98 | Typical usage has an ASCII character | |
fea681da | 99 | .IR proj_id , |
d9bfdb9c | 100 | that is why the behavior is said to be undefined when |
fea681da MK |
101 | .I proj_id |
102 | is zero. | |
dd3568a1 | 103 | .PP |
88ba4651 | 104 | Of course, no guarantee can be given that the resulting |
f19a0f03 | 105 | .I key_t |
c13182ef | 106 | is unique. |
88ba4651 | 107 | Typically, a best-effort attempt combines the given |
fea681da | 108 | .I proj_id |
76d8cd36 | 109 | byte, the lower 16 bits of the inode number, and the |
2706f299 | 110 | lower 8 bits of the device number into a 32-bit result. |
fea681da MK |
111 | Collisions may easily happen, for example between files on |
112 | .I /dev/hda1 | |
113 | and files on | |
114 | .IR /dev/sda1 . | |
47297adb | 115 | .SH SEE ALSO |
fea681da MK |
116 | .BR msgget (2), |
117 | .BR semget (2), | |
118 | .BR shmget (2), | |
119 | .BR stat (2), | |
2c5e151c | 120 | .BR svipc (7) |