huschi.net

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 (consult 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 dif-
       ferent  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,  Copyright  (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.opengroup.org/unix/online.html .

IEEE/The Open Group                  2003                             FTOK(3P)