ftok(3C)

NAME

     ftok - generate an IPC key

SYNOPSIS

     #include <sys/ipc.h>

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

DESCRIPTION

     The ftok() function returns a key based on path and id  that
     is  usable  in  subsequent calls to msgget(2), semget(2) and
     shmget(2). The path argument must  be  the  pathname  of  an
     existing file that the process is able to  stat(2).

     The ftok() function will return the same key value  for  all
     paths  that name the same file, when called with the same id
     value, and will return different key values when called with
     different id values.

     If the file named by path is removed while still referred to
     by a key, a call to ftok() with the same path and id returns
     an error. If the same file is  recreated,  then  a  call  to
     ftok()  with the same path and id is likely to return a dif-
     ferent key.

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

RETURN VALUES

     Upon successful completion, ftok() returns  a  key.   Other-
     wise,  ftok()  returns  (key_t)-1 and sets errno to indicate
     the error.

ERRORS

     The ftok() function will fail if:

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

     ELOOP Too many symbolic links were encountered in  resolving
           path.

     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:

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

USAGE

     For maximum portability, id should be a single-byte  charac-
     ter.

     Another way to compose keys is to include the project ID  in
     the  most  significant byte and to use the remaining portion
     as a sequence number. There are  many  other  ways  to  form
     keys,  but  it  is necessary for each system to define stan-
     dards for forming them. If some standard is not adhered  to,
     it  will be possible for unrelated processes to unintention-
     ally interfere with each other's operation. It is still pos-
     sible  to interfere intentionally. Therefore, it is strongly
     suggested that the most significant byte of a  key  in  some
     sense refer to a project so that keys do not conflict across
     a given system.

NOTES

     Since the ftok() function returns a value based  on  the  id
     given  and  the file serial number of the file named by path
     in a type that is no longer large enough to  hold  all  file
     serial  numbers, it may return the same key for paths naming
     different files on large filesystems.

ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | MT-Level                    | MT-Safe                     |
    |_____________________________|_____________________________|

SEE ALSO

     msgget(2), semget(2), shmget(2), stat(2), attributes(5)