FTOK(3P)                                            POSIX Programmer's Manual                                           FTOK(3P)



PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux implementation of this interface may differ (con-
       sult the corresponding Linux manual page for details of Linux behavior), or the  interface  may  not  be  implemented  on
       Linux.

NAME
       ftok - generate an IPC key

SYNOPSIS
       #include <sys/ipc.h>

       key_t ftok(const char *path, int id);


DESCRIPTION
       The ftok() function shall return a key based on path and id that is usable in subsequent calls to msgget(), semget(), and
       shmget(). The application shall ensure that the path argument is the pathname of an existing file  that  the  process  is
       able to stat().

       The  ftok()  function shall return the same key value for all paths that name the same file, when called with the same id
       value, and return different key values when called with different id values or  with  paths  that  name  different  files
       existing  on the same file system at the same time. It is unspecified whether ftok() shall return the same key value when
       called again after the file named by path is removed and recreated with the same name.

       Only the low-order 8-bits of id are significant. The behavior of ftok() is unspecified if these bits are 0.

RETURN VALUE
       Upon successful completion, ftok() shall return a key. Otherwise, ftok() shall return (key_t)-1 and set errno to indicate
       the error.

ERRORS
       The ftok() function shall fail if:

       EACCES Search permission is denied for a component of the path prefix.

       ELOOP  A loop exists in symbolic links encountered during resolution of the path argument.

       ENAMETOOLONG
              The length of the path argument exceeds {PATH_MAX} or a pathname component is longer than {NAME_MAX}.

       ENOENT A component of path does not name an existing file or path is an empty string.

       ENOTDIR
              A component of the path prefix is not a directory.


       The ftok() function may fail if:

       ELOOP  More than {SYMLOOP_MAX} symbolic links were encountered during resolution of the path argument.

       ENAMETOOLONG
              Pathname resolution of a symbolic link produced an intermediate result whose length exceeds {PATH_MAX}.


       The following sections are informative.

EXAMPLES
   Getting an IPC Key
       The  following  example gets a unique key that can be used by the IPC functions semget(), msgget(), and shmget(). The key
       returned by ftok() for this example is based on the ID value S and the pathname /tmp.


              #include <sys/ipc.h>
              ...
              key_t key;
              char *path = "/tmp";
              int id = 'S';


              key = ftok(path, id);

   Saving an IPC Key
       The following example gets a unique key based on the pathname /tmp and the ID value a. It also assigns the value  of  the
       resulting key to the semkey variable so that it will be available to a later call to semget(), msgget(), or shmget().


              #include <sys/ipc.h>
              ...
              key_t semkey;


              if ((semkey = ftok("/tmp", 'a')) == (key_t) -1) {
                  perror("IPC error: ftok"); exit(1);
              }

APPLICATION USAGE
       For maximum portability, id should be a single-byte character.

RATIONALE
       None.

FUTURE DIRECTIONS
       None.

SEE ALSO
       msgget(), semget(), shmget(), the Base Definitions volume of IEEE Std 1003.1-2001, <sys/ipc.h>

COPYRIGHT
       Portions  of  this  text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2003 Edition, Standard for
       Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6,  Copy-
       right (C) 2001-2003 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any
       discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open  Group
       Standard   is   the   referee   document.   The   original   Standard   can   be   obtained  online  at  http://www.open-
       group.org/unix/online.html .



IEEE/The Open Group                                           2003                                                      FTOK(3P)