usr/src/man/man3c/pthread_key_create.3c

   1 '\" te
   2 .\" Copyright (c) 2008, Sun Microsystems, Inc.  All Rights Reserved.
   3 .\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved.
   4 .\" Copyright 1991, 1992, 1994, The X/Open Company Ltd.
   5 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
   6 .\" http://www.opengroup.org/bookstore/.
   7 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions 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.
   8 .\"  This notice shall appear on any product containing this material.
   9 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
  10 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
  11 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
  12 .TH PTHREAD_KEY_CREATE 3C "Nov 2, 2007"
  13 .SH NAME
  14 pthread_key_create, pthread_key_create_once_np \- create thread-specific data
  15 key
  16 .SH SYNOPSIS
  17 .LP
  18 .nf
  19 cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ]
  20 #include <pthread.h>
  21
  22 \fBint\fR \fBpthread_key_create\fR(\fBpthread_key_t *\fR\fIkey\fR,
  23      \fBvoid\fR (*\fIdestructor\fR)(\fBvoid*\fR));
  24 .fi
  25
  26 .LP
  27 .nf
  28 \fBint\fR \fBpthread_key_create_once_np\fR(\fBpthread_key_t *\fR\fIkey\fR,
  29      \fBvoid\fR (*\fIdestructor\fR)(\fBvoid*\fR));
  30 .fi
  31
  32 .SH DESCRIPTION
  33 .sp
  34 .LP
  35 The \fBpthread_key_create()\fR function creates a thread-specific data key
  36 visible to all threads in the process. Key values provided by
  37 \fBpthread_key_create()\fR are opaque objects used to locate thread-specific
  38 data. Although the same key value may be used by different threads, the values
  39 bound to the key by \fBpthread_setspecific()\fR are maintained on a per-thread
  40 basis and persist for the life of the calling thread.
  41 .sp
  42 .LP
  43 Upon key creation, the value  \fINULL\fR is associated with the new key in all
  44 active threads. Upon thread creation, the value  \fINULL\fR is associated with
  45 all defined keys in the new thread.
  46 .sp
  47 .LP
  48 An optional destructor function may be associated with each key value. At
  49 thread exit, if a key value has a non-\fINULL\fR  destructor pointer, and the
  50 thread has a non-\fINULL\fR value associated with that key, the function
  51 pointed to is called with the current associated value as its sole argument.
  52 Destructors can be called in any order.
  53 .sp
  54 .LP
  55 If, after all the destructors have been  called for all keys with
  56 non-\fINULL\fR values,  there are still some keys with non-\fINULL\fR values,
  57 the process will be repeated. If, after at least
  58 \fBPTHREAD_DESTRUCTOR_ITERATIONS\fR iterations of destructor calls for
  59 outstanding non-\fINULL\fR values, there are still some keys with
  60 non-\fINULL\fR values, the process is continued, even though this might result
  61 in an infinite loop.
  62 .sp
  63 .LP
  64 An exiting thread runs with all signals blocked. All thread termination
  65 functions, including thread-specific data destructor functions, are called with
  66 all signals blocked.
  67 .sp
  68 .LP
  69 The \fBpthread_key_create_once_np()\fR function is identical to the
  70 \fBpthread_key_create()\fR function except that the key referred to by
  71 *\fIkey\fR must be statically initialized with the value
  72 \fBPTHREAD_ONCE_KEY_NP\fR before calling \fBpthread_key_create_once_np()\fR,
  73 and the key is created exactly once. This function call is equivalent to using
  74 \fBpthread_once\fR(3C) to call a onetime initialization function that calls
  75 \fBpthread_key_create()\fR to create the data key.
  76 .SH RETURN VALUES
  77 .sp
  78 .LP
  79 If successful, the \fBpthread_key_create()\fR and
  80 \fBpthread_key_create_once_np()\fR functions store the newly created key value
  81 at *\fIkey\fR and return \fB0\fR. Otherwise, an error number is returned to
  82 indicate the error.
  83 .SH ERRORS
  84 .sp
  85 .LP
  86 The  \fBpthread_key_create()\fR and \fBpthread_key_create_once_np()\fR
  87 functions will fail if:
  88 .sp
  89 .ne 2
  90 .na
  91 \fB\fBEAGAIN\fR\fR
  92 .ad
  93 .RS 10n
  94 The system lacked the necessary resources to create another thread-specific
  95 data key, or the system-imposed limit on the total number of keys per process
  96 \fBPTHREAD_KEYS_MAX\fR has been exceeded.
  97 .RE
  98
  99 .sp
 100 .ne 2
 101 .na
 102 \fB\fBENOMEM\fR\fR
 103 .ad
 104 .RS 10n
 105 Insufficient memory exists to create the key.
 106 .RE
 107
 108 .sp
 109 .LP
 110 The \fBpthread_key_create()\fR and \fBpthread_key_create_once_np()\fR functions
 111 will not return an error value of \fBEINTR\fR.
 112 .SH EXAMPLES
 113 .LP
 114 \fBExample 1 \fRCall thread-specific data in the function from more than one
 115 thread without special initialization.
 116 .sp
 117 .LP
 118 In the following example, the thread-specific data in the function can be
 119 called from more than one thread without special initialization. For each
 120 argument passed to the executable, a thread is created and privately bound to
 121 the string-value of that argument.
 122
 123 .sp
 124 .in +2
 125 .nf
 126 /* cc -mt thisfile.c */
 127
 128 #include <stdio.h>
 129 #include <stdlib.h>
 130 #include <string.h>
 131 #include <pthread.h>
 132
 133 static void *thread_function(void *);
 134 static void show_tsd(void);
 135 static void cleanup(void*);
 136
 137 #define MAX_THREADS 20
 138
 139 static pthread_key_t tsd_key = PTHREAD_ONCE_KEY_NP;
 140
 141 int
 142 main(int argc, char *argv[])
 143 {
 144      pthread_t tid[MAX_THREADS];
 145      int num_threads;
 146      int i;
 147
 148      if ((num_threads = argc - 1) > MAX_THREADS)
 149           num_threads = MAX_THREADS;
 150      for (i = 0; i < num_threads; i++)
 151           pthread_create(&tid[i], NULL, thread_function, argv[i+1]);
 152      for (i = 0; i < num_threads; i++)
 153           pthread_join(tid[i], NULL);
 154      return (0);
 155 }
 156
 157 static void *
 158 thread_function(void *arg)
 159 {
 160      char *data;
 161
 162      pthread_key_create_once_np(&tsd_key, cleanup);
 163      data = malloc(strlen(arg) + 1);
 164      strcpy(data, arg);
 165      pthread_setspecific(tsd_key, data);
 166      show_tsd();
 167      return (NULL);
 168 }
 169
 170 static void
 171 show_tsd()
 172 {
 173      void *tsd = pthread_getspecific(tsd_key);
 174
 175      printf("tsd for %d = %s\en", pthread_self(), (char *)tsd);
 176 }
 177
 178 /* application-specific clean-up function */
 179 static void
 180 cleanup(void *tsd)
 181 {
 182      printf("freeing tsd for %d = %s\en", pthread_self(), (char *)tsd);
 183      free(tsd);
 184 }
 185 .fi
 186 .in -2
 187
 188 .SH ATTRIBUTES
 189 .sp
 190 .LP
 191 See \fBattributes\fR(5) for descriptions of the following attributes:
 192 .sp
 193
 194 .sp
 195 .TS
 196 box;
 197 c | c
 198 l | l .
 199 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 200 _
 201 Interface Stability     Committed.
 202 _
 203 MT-Level        MT-Safe
 204 _
 205 Standard        See below.
 206 .TE
 207
 208 .sp
 209 .LP
 210 For \fBpthread_key_create()\fR, see \fBstandards\fR(5).
 211 .SH SEE ALSO
 212 .sp
 213 .LP
 214 \fBpthread_once\fR(3C), \fBpthread_getspecific\fR(3C),
 215 \fBpthread_setspecific\fR(3C), \fBpthread_key_delete\fR(3C),
 216 \fBattributes\fR(5), \fBstandards\fR(5)