1FTOK(3P)                   POSIX Programmer's Manual                  FTOK(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       ftok - generate an IPC key
13

SYNOPSIS

15       #include <sys/ipc.h>
16
17       key_t ftok(const char *path, int id);
18
19

DESCRIPTION

21       The ftok() function shall return a key based on path  and  id  that  is
22       usable  in  subsequent  calls  to msgget(), semget(), and shmget(). The
23       application shall ensure that the path argument is the pathname  of  an
24       existing file that the process is able to stat().
25
26       The  ftok() function shall return the same key value for all paths that
27       name the same file, when called with the same id value, and return dif‐
28       ferent  key  values  when called with different id values or with paths
29       that name different files existing on the same file system at the  same
30       time.  It is unspecified whether ftok() shall return the same key value
31       when called again after the file named by path is removed and recreated
32       with the same name.
33
34       Only the low-order 8-bits of id are significant. The behavior of ftok()
35       is unspecified if these bits are 0.
36

RETURN VALUE

38       Upon successful completion,  ftok()  shall  return  a  key.  Otherwise,
39       ftok() shall return (key_t)-1 and set errno to indicate the error.
40

ERRORS

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

EXAMPLES

73   Getting an IPC Key
74       The following example gets a unique key that can be  used  by  the  IPC
75       functions  semget(), msgget(), and shmget(). The key returned by ftok()
76       for this example is based on the ID value S and the pathname /tmp.
77
78
79              #include <sys/ipc.h>
80              ...
81              key_t key;
82              char *path = "/tmp";
83              int id = 'S';
84
85
86              key = ftok(path, id);
87
88   Saving an IPC Key
89       The following example gets a unique key based on the pathname /tmp  and
90       the  ID  value a. It also assigns the value of the resulting key to the
91       semkey variable so that it  will  be  available  to  a  later  call  to
92       semget(), msgget(), or shmget().
93
94
95              #include <sys/ipc.h>
96              ...
97              key_t semkey;
98
99
100              if ((semkey = ftok("/tmp", 'a')) == (key_t) -1) {
101                  perror("IPC error: ftok"); exit(1);
102              }
103

APPLICATION USAGE

105       For maximum portability, id should be a single-byte character.
106

RATIONALE

108       None.
109

FUTURE DIRECTIONS

111       None.
112

SEE ALSO

114       msgget(),   semget(),   shmget(),   the   Base  Definitions  volume  of
115       IEEE Std 1003.1-2001, <sys/ipc.h>
116
118       Portions of this text are reprinted and reproduced in  electronic  form
119       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
120       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
121       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
122       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
123       event of any discrepancy between this version and the original IEEE and
124       The Open Group Standard, the original IEEE and The Open Group  Standard
125       is  the  referee document. The original Standard can be obtained online
126       at http://www.opengroup.org/unix/online.html .
127
128
129
130IEEE/The Open Group                  2003                             FTOK(3P)
Impressum