man3/ftok.3

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