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

FreeBSD Manual Pages


home | help
pthread_key_create(3T)					pthread_key_create(3T)

       pthread_key_create(), pthread_key_delete() - create or delete a thread-
       specific	data key

	      key	This is	either a pointer to the	location where the new
			key value will to be returned (create function)	or the
			thread-specific	data key to be deleted	(delete	 func-

			Function  to be	called to destroy a data value associ-
			ated with key when the thread terminates.

       creates a unique	thread-specific	data key.  The	key  may  be  used  by
       threads	within the process to maintain thread-specific data.  The same
       key is used by all threads, but each thread has its own thread-specific
       value  associated with key.  For	each thread, the value associated with
       key persists for	the life of the	thread.

       A process may create up to  thread-specific  data  keys.	  When	a  new
       thread-specific	data  key  is created, each thread will	initially have
       the value associated with the new key.  Each time a thread is  created,
       the  new	 thread	 will have the value for each thread-specific data key
       that has	been created in	the process.  A	thread may use to  change  the
       value  associated  with a thread-specific data key.  Note: is an	opaque
       data type.

       When a thread terminates, it may	have non-values	associated  with  some
       or  all of its thread-specific data keys.  Typically, these values will
       be pointers to dynamically allocated memory.  If	this memory is not re-
       leased  when  the thread	terminates, memory leaks in the	process	occur.
       An optional function may	be provided at key creation  time  to  destroy
       the thread-specific data	of a terminating thread.  When a thread	termi-
       nates, the thread-specific data values associated with the thread  will
       be  examined.   For  each key that has a	non-thread-specific data value
       and a destructor	function, the destructor function will be called  with
       the  thread-specific  data  value  as  its sole argument.  The order in
       which destructor	functions are called is	unspecified.

       Once all	the destructor functions have been called, the thread-specific
       data  values  for  the terminating thread are examined again.  If there
       are still non-values in which the associated keys have destructor func-
       tions, the process of calling destructor	functions is repeated.	If af-
       ter iterations of this loop there are still some	non-values with	 asso-
       ciated destructors, the system may stop calling the destructors or con-
       tinue calling the destructors until there  are  no  non-values.	 Note:
       This may	result in an infinite loop.

       If  a  destructor  function  is	not  desired for key, the value	may be
       passed in the destructor	parameter.

       The function deletes a thread-specific data key.	  The  key  must  have
       been  previously	 created by The	thread-specific	data values associated
       with key	are not	required to be when this function  is  called.	 Using
       key after it has	been deleted results in	undefined behavior.

       If a destructor function	is associated with key,	it will	not be invoked
       by the function.	 Once key has been deleted, any	function that was  as-
       sociated	with key is not	called when a thread exits.  It	is the respon-
       sibility	of the application to free any application storage for each of
       the threads using key.

       The function can	be called from a destructor function.

       If  successful, and return zero.	Otherwise, an error number is returned
       to indicate the error (the variable is not set).

       If any of the following occur, the function returns  the	 corresponding
       error number:

	      [EINVAL]	     The value specified by key	is invalid.

	      [EAGAIN]	     The necessary resources to	create another thread-
			     specific data key are not available, or the total
			     number of keys per	process	has exceeded

	      [ENOMEM]	     There  is	insufficient memory available in which
			     to	create key.

       For each	of the following conditions, if	the condition is detected, the
       function	returns	the corresponding error	number:

	      [EINVAL]	     The value specified by key	is invalid.

       and were	derived	from the IEEE POSIX P1003.1c standard.

       pthread_getspecific(3T),	pthread_setspecific(3T).

				Pthread	Library		pthread_key_create(3T)


Want to link to this manual page? Use this URL:

home | help