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 .P
  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 .P
  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 .SH STANDARDS
  68 POSIX.1-2008.
  69 .SH HISTORY
  70 POSIX.1-2001.
  71 .SH NOTES
  72 On some ancient systems, the prototype was:
  73 .P
  74 .in +4n
  75 .EX
  76 .BI "key_t ftok(char *" pathname ", char " proj_id );
  77 .EE
  78 .in
  79 .P
  80 Today,
  81 .I proj_id
  82 is an
  83 .IR int ,
  84 but still only 8 bits are used.
  85 Typical usage has an ASCII character
  86 .IR proj_id ,
  87 that is why the behavior is said to be undefined when
  88 .I proj_id
  89 is zero.
  90 .P
  91 Of course, no guarantee can be given that the resulting
  92 .I key_t
  93 is unique.
  94 Typically, a best-effort attempt combines the given
  95 .I proj_id
  96 byte, the lower 16 bits of the inode number, and the
  97 lower 8 bits of the device number into a 32-bit result.
  98 Collisions may easily happen, for example between files on
  99 .I /dev/hda1
 100 and files on
 101 .IR /dev/sda1 .
 102 .SH EXAMPLES
 103 See
 104 .BR semget (2).
 105 .SH SEE ALSO
 106 .BR msgget (2),
 107 .BR semget (2),
 108 .BR shmget (2),
 109 .BR stat (2),
 110 .BR sysvipc (7)