man3/ftok.3

   1 .\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it)
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   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.
  12 .\"
  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.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .\" Modified 2001-11-28, by Michael Kerrisk, <mtk.manpages@gmail.com>
  26 .\"     Changed data type of proj_id; minor fixes
  27 .\"     aeb: further fixes; added notes.
  28 .\"
  29 .TH FTOK 3 2021-03-22 "GNU" "Linux Programmer's Manual"
  30 .SH NAME
  31 ftok \- convert a pathname and a project identifier to a System V IPC key
  32 .SH SYNOPSIS
  33 .nf
  34 .B #include <sys/ipc.h>
  35 .fi
  36 .PP
  37 .BI "key_t ftok(const char *" pathname ", int " proj_id );
  38 .SH DESCRIPTION
  39 The
  40 .BR ftok ()
  41 function uses the identity of the file named by the given
  42 .I pathname
  43 (which must refer to an existing, accessible file)
  44 and the least significant 8 bits of
  45 .I proj_id
  46 (which must be nonzero) to generate a
  47 .I key_t
  48 type System V IPC key, suitable for use with
  49 .BR msgget (2),
  50 .BR semget (2),
  51 or
  52 .BR shmget (2).
  53 .PP
  54 The resulting value is the same for all pathnames that
  55 name the same file, when the same value of
  56 .I proj_id
  57 is used.
  58 The value returned should be different when the
  59 (simultaneously existing) files or the project IDs differ.
  60 .SH RETURN VALUE
  61 On success, the generated
  62 .I key_t
  63 value is returned.
  64 On failure \-1 is returned, with
  65 .I errno
  66 indicating the error as for the
  67 .BR stat (2)
  68 system call.
  69 .SH ATTRIBUTES
  70 For an explanation of the terms used in this section, see
  71 .BR attributes (7).
  72 .ad l
  73 .nh
  74 .TS
  75 allbox;
  76 lbx lb lb
  77 l l l.
  78 Interface       Attribute       Value
  79 T{
  80 .BR ftok ()
  81 T}      Thread safety   MT-Safe
  82 .TE
  83 .hy
  84 .ad
  85 .sp 1
  86 .SH CONFORMING TO
  87 POSIX.1-2001, POSIX.1-2008.
  88 .SH NOTES
  89 On some ancient systems, the prototype was:
  90 .PP
  91 .in +4n
  92 .EX
  93 .BI "key_t ftok(char *" pathname ", char " proj_id );
  94 .EE
  95 .in
  96 .PP
  97 Today,
  98 .I proj_id
  99 is an
 100 .IR int ,
 101 but still only 8 bits are used.
 102 Typical usage has an ASCII character
 103 .IR proj_id ,
 104 that is why the behavior is said to be undefined when
 105 .I proj_id
 106 is zero.
 107 .PP
 108 Of course, no guarantee can be given that the resulting
 109 .I key_t
 110 is unique.
 111 Typically, a best-effort attempt combines the given
 112 .I proj_id
 113 byte, the lower 16 bits of the inode number, and the
 114 lower 8 bits of the device number into a 32-bit result.
 115 Collisions may easily happen, for example between files on
 116 .I /dev/hda1
 117 and files on
 118 .IR /dev/sda1 .
 119 .SH EXAMPLES
 120 See
 121 .BR semget (2).
 122 .SH SEE ALSO
 123 .BR msgget (2),
 124 .BR semget (2),
 125 .BR shmget (2),
 126 .BR stat (2),
 127 .BR sysvipc (7)