man3/ftok.3

   1 .\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it)
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .\" Modified 2001-11-28, by Michael Kerrisk, <mtk.manpages@gmail.com>
   6 .\"     Changed data type of proj_id; minor fixes
   7 .\"     aeb: further fixes; added notes.
   8 .\"
   9 .TH FTOK 3 2021-03-22 "Linux man-pages (unreleased)" "Linux Programmer's Manual"
  10 .SH NAME
  11 ftok \- convert a pathname and a project identifier to a System V IPC key
  12 .SH LIBRARY
  13 Standard C library
  14 .RI ( libc ", " \-lc )
  15 .SH SYNOPSIS
  16 .nf
  17 .B #include <sys/ipc.h>
  18 .fi
  19 .PP
  20 .BI "key_t ftok(const char *" pathname ", int " proj_id );
  21 .SH DESCRIPTION
  22 The
  23 .BR ftok ()
  24 function uses the identity of the file named by the given
  25 .I pathname
  26 (which must refer to an existing, accessible file)
  27 and the least significant 8 bits of
  28 .I proj_id
  29 (which must be nonzero) to generate a
  30 .I key_t
  31 type System V IPC key, suitable for use with
  32 .BR msgget (2),
  33 .BR semget (2),
  34 or
  35 .BR shmget (2).
  36 .PP
  37 The resulting value is the same for all pathnames that
  38 name the same file, when the same value of
  39 .I proj_id
  40 is used.
  41 The value returned should be different when the
  42 (simultaneously existing) files or the project IDs differ.
  43 .SH RETURN VALUE
  44 On success, the generated
  45 .I key_t
  46 value is returned.
  47 On failure \-1 is returned, with
  48 .I errno
  49 indicating the error as for the
  50 .BR stat (2)
  51 system call.
  52 .SH ATTRIBUTES
  53 For an explanation of the terms used in this section, see
  54 .BR attributes (7).
  55 .ad l
  56 .nh
  57 .TS
  58 allbox;
  59 lbx lb lb
  60 l l l.
  61 Interface       Attribute       Value
  62 T{
  63 .BR ftok ()
  64 T}      Thread safety   MT-Safe
  65 .TE
  66 .hy
  67 .ad
  68 .sp 1
  69 .SH STANDARDS
  70 POSIX.1-2001, POSIX.1-2008.
  71 .SH NOTES
  72 On some ancient systems, the prototype was:
  73 .PP
  74 .in +4n
  75 .EX
  76 .BI "key_t ftok(char *" pathname ", char " proj_id );
  77 .EE
  78 .in
  79 .PP
  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 .PP
  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)