Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
PTHREAD_KEY_CREATE(3)	    Library Functions Manual	 PTHREAD_KEY_CREATE(3)

NAME
       pthread_key_create -- thread-specific data key creation

LIBRARY
       POSIX Threads Library (libpthread, -lpthread)

SYNOPSIS
       #include	<pthread.h>

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

DESCRIPTION
       The  pthread_key_create()  function  creates a thread-specific data key
       visible to  all	threads	 in  the  process.   Key  values  provided  by
       pthread_key_create()  are opaque	objects	used to	locate thread-specific
       data.  Although the same	key value may be used  by  different  threads,
       the  values bound to the	key by pthread_setspecific() are maintained on
       a per-thread basis and persist for the life of the calling thread.

       Upon key	creation, the value NULL is associated with the	new key	in all
       active threads.	Upon thread creation, the  value  NULL	is  associated
       with all	defined	keys in	the new	thread.

       An  optional destructor function	may be associated with each key	value.
       At thread exit, if a key	value has a non-NULL destructor	 pointer,  and
       the  thread  has	a non-NULL value associated with the key, the function
       pointed to is called with the current associated	value as its sole  ar-
       gument.	 The order of destructor calls is unspecified if more than one
       destructor exists for a thread when it exits.

       If, after all the destructors have been called for all non-NULL	values
       with  associated	destructors, there are still some non-NULL values with
       associated destructors, then the	process	is  repeated.	If,  after  at
       least  [PTHREAD_DESTRUCTOR_ITERATIONS]  iterations  of destructor calls
       for outstanding non-NULL	values,	there are still	some  non-NULL	values
       with  associated	destructors, the implementation	stops calling destruc-
       tors.

RETURN VALUES
       If successful, the pthread_key_create() function	will store  the	 newly
       created	key  value  at the location specified by key and returns zero.
       Otherwise an error number will be returned to indicate the error.

ERRORS
       The pthread_key_create()	function will fail if:

       [EAGAIN]		  The system lacked the	necessary resources to	create
			  another  thread-specific data	key, or	the system-im-
			  posed	limit on the total number of keys per  process
			  [PTHREAD_KEYS_MAX] would be exceeded.

       [ENOMEM]		  Insufficient memory exists to	create the key.

SEE ALSO
       pthread_getspecific(3), pthread_key_delete(3), pthread_setspecific(3)

STANDARDS
       The  pthread_key_create()  function  conforms  to  ISO/IEC  9945-1:1996
       ("POSIX.1").

FreeBSD	14.3			 April 4, 1996		 PTHREAD_KEY_CREATE(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=pthread_key_create&sektion=3&manpath=FreeBSD+14.3-RELEASE+and+Ports>

home | help