NAME    [Toc]    [Back]

       tis_key_create  -  Generates a unique thread-specific data
       key

SYNOPSIS    [Toc]    [Back]

       #include <tis.h>

       int tis_key_create(
               pthread_key_t *key,
               void (*destructor)(void *) );

LIBRARY    [Toc]    [Back]

       Standard C Library (libc.so, libc.a)

STANDARDS    [Toc]    [Back]

       None

PARAMETERS    [Toc]    [Back]

       Address of a variable that receives the  key  value.  This
       value  is used in calls to tis_getspecific(3) and tis_setspecific(3) to get and set the value associated with  this
       key.   Address  of a routine that is called to destroy the
       context value when a thread  terminates  with  a  non-NULL
       value  for  the  key. Note that this argument is used only
       when threads are present.

DESCRIPTION    [Toc]    [Back]

       This routine generates a unique thread-specific data  key.
       The key argument points to an opaque object used to locate
       data.

       This routine generates and returns a new  key  value.  The
       key  reserves  a cell. Each call to this routine creates a
       new cell that is unique within an application  invocation.
       Keys  must  be  generated from initialization code that is
       guaranteed to be called only  once  within  each  process.
       (See the tis_once(3) description for more information.)

       Your program can associate an optional destructor function
       with each key. At thread exit, if a  key  has  a  non-NULL
       destructor function pointer, and the thread has a non-NULL
       value associated with that key, the function pointed to is
       called with the current associated value as its sole argument.
  The order in which data destructors are  called  at
       thread termination is undefined.

       When  threads are present, keys and any corresponding data
       are thread specific; they enable the context to  be  maintained
  on a per-thread basis.  For more information about
       the use of tis_key_create(3) in  a  threaded  environment,
       refer to the pthread_key_create(3) description.

       DECthreads  imposes  a  maximum  number of thread-specific
       data   keys,    equal    to    the    symbolic    constant
       PTHREAD_KEYS_MAX.

RETURN VALUES    [Toc]    [Back]

       If  an  error  condition  occurs,  this routine returns an
       integer value  indicating  the  type  of  error.  Possible
       return  values are as follows: Successful completion.  The
       system lacked the necessary resources  to  create  another
       thread-specific data key, or the limit on the total number
       of keys per process (PTHREAD_KEYS_MAX) has been  exceeded.
       Insufficient  memory  exists  to  create the key.  Invalid
       argument.

ERRORS    [Toc]    [Back]

       None

SEE ALSO    [Toc]    [Back]

       Functions:     tis_getspecific(3),      tis_key_delete(3),
       tis_once(3), tis_setspecific(3)

       Manuals: Guide to DECthreads and Programmer's Guide



                                                tis_key_create(3)