original/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 2013-10-07 "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/types.h>
  35 .B #include <sys/ipc.h>
  36 .fi
  37 .sp
  38 .BI "key_t ftok(const char *" pathname ", int " proj_id );
  39 .SH DESCRIPTION
  40 The
  41 .BR ftok ()
  42 function uses the identity of the file named by the given
  43 .I pathname
  44 (which must refer to an existing, accessible file)
  45 and the least significant 8 bits of
  46 .I proj_id
  47 (which must be nonzero) to generate a
  48 .I key_t
  49 type System V IPC key, suitable for use with
  50 .BR msgget (2),
  51 .BR semget (2),
  52 or
  53 .BR shmget (2).
  54 .LP
  55 The resulting value is the same for all pathnames that
  56 name the same file, when the same value of
  57 .I proj_id
  58 is used.
  59 The value returned should be different when the
  60 (simultaneously existing) files or the project IDs differ.
  61 .SH RETURN VALUE
  62 On success, the generated
  63 .I key_t
  64 value is returned.
  65 On failure \-1 is returned, with
  66 .I errno
  67 indicating the error as for the
  68 .BR stat (2)
  69 system call.
  70 .SH ATTRIBUTES
  71 .SS Multithreading (see pthreads(7))
  72 The
  73 .BR ftok ()
  74 function is thread-safe.
  75 .SH CONFORMING TO
  76 POSIX.1-2001.
  77 .SH NOTES
  78 Under libc4 and libc5 (and under SunOS 4.x) the prototype was:
  79 .sp
  80 .RS
  81 .BI "key_t ftok(char *" pathname ", char " proj_id );
  82 .RE
  83 .PP
  84 Today
  85 .I proj_id
  86 is an
  87 .IR int ,
  88 but still only 8 bits are used.
  89 Typical usage has an ASCII character
  90 .IR proj_id ,
  91 that is why the behavior is said to be undefined when
  92 .I proj_id
  93 is zero.
  94 .LP
  95 Of course no guarantee can be given that the resulting
  96 .I key_t
  97 is unique.
  98 Typically, a best effort attempt combines the given
  99 .I proj_id
 100 byte, the lower 16 bits of the inode number, and the
 101 lower 8 bits of the device number into a 32-bit result.
 102 Collisions may easily happen, for example between files on
 103 .I /dev/hda1
 104 and files on
 105 .IR /dev/sda1 .
 106 .SH SEE ALSO
 107 .BR msgget (2),
 108 .BR semget (2),
 109 .BR shmget (2),
 110 .BR stat (2),
 111 .BR svipc (7)
 112 .SH COLOPHON
 113 This page is part of release 3.68 of the Linux
 114 .I man-pages
 115 project.
 116 A description of the project,
 117 information about reporting bugs,
 118 and the latest version of this page,
 119 can be found at
 120 \%http://www.kernel.org/doc/man\-pages/.