1PTHREADS-WIN32 RELEASE 2.9.0 (2012-05-25)
2-----------------------------------------
3Web Site: http://sourceware.org/pthreads-win32/
4FTP Site: ftp://sourceware.org/pub/pthreads-win32
5Maintainer: Ross Johnson <ross.johnson@loungebythelake.net>
6
7
8We are pleased to announce the availability of a new release of
9Pthreads-win32, an Open Source Software implementation of the
10Threads component of the POSIX 1003.1 2001 Standard for Microsoft's
11Win32 environment. Some functions from other sections of POSIX
121003.1 2001 are also supported including semaphores and scheduling
13functions.
14
15Some common non-portable functions are also implemented for
16additional compatibility, as are a few functions specific
17to pthreads-win32 for easier integration with Win32 applications.
18
19Pthreads-win32 is free software, distributed under the GNU Lesser
20General Public License (LGPL).
21
22
23Acknowledgements
24----------------
25This library is based originally on a Win32 pthreads
26implementation contributed by John Bossom.
27
28The implementation of Condition Variables uses algorithms developed
29by Alexander Terekhov and Louis Thomas.
30
31The implementation of POSIX mutexes has been improved by Thomas Pfaff
32and later by Alexander Terekhov.
33
34The implementation of Spinlocks and Barriers was contributed
35by Ross Johnson.
36
37The implementation of read/write locks was contributed by
38Aurelio Medina and improved by Alexander Terekhov.
39
40Many others have contributed significant time and effort to solve crutial
41problems in order to make the library workable, robust and reliable.
42
43Thanks to Xavier Leroy for granting permission to use and modify his
44LinuxThreads manual pages.
45
46Thanks to The Open Group for making the Single Unix Specification
47publicly available - many of the manual pages included in the package
48were extracted from it.
49
50There is also a separate CONTRIBUTORS file. This file and others are
51on the web site:
52
53	http://sourceware.org/pthreads-win32
54
55As much as possible, the ChangeLog file acknowledges contributions to the
56code base in more detail.
57
58
59Changes since the last release
60------------------------------
61These are now documented in the NEWS file.
62See the ChangeLog file also.
63
64
65Known Bugs
66----------
67These are now documented in the BUGS file.
68
69
70Level of standards conformance
71------------------------------
72
73The following POSIX 1003.1 2001 options are defined and set to 200112L:
74
75      _POSIX_THREADS
76      _POSIX_THREAD_SAFE_FUNCTIONS
77      _POSIX_THREAD_ATTR_STACKSIZE
78      _POSIX_THREAD_PRIORITY_SCHEDULING
79      _POSIX_SEMAPHORES
80      _POSIX_READER_WRITER_LOCKS
81      _POSIX_SPIN_LOCKS
82      _POSIX_BARRIERS
83
84
85The following POSIX 1003.1 2001 options are defined and set to -1:
86
87      _POSIX_THREAD_ATTR_STACKADDR
88      _POSIX_THREAD_PRIO_INHERIT
89      _POSIX_THREAD_PRIO_PROTECT
90      _POSIX_THREAD_PROCESS_SHARED
91
92
93The following POSIX 1003.1 2001 limits are defined and set:
94
95      _POSIX_THREAD_THREADS_MAX
96      _POSIX_SEM_VALUE_MAX
97      _POSIX_SEM_NSEMS_MAX
98      _POSIX_THREAD_KEYS_MAX
99      _POSIX_THREAD_DESTRUCTOR_ITERATIONS
100      PTHREAD_STACK_MIN
101      PTHREAD_THREADS_MAX
102      SEM_VALUE_MAX
103      SEM_NSEMS_MAX
104      PTHREAD_KEYS_MAX
105      PTHREAD_DESTRUCTOR_ITERATIONS
106
107
108The following functions are implemented:
109
110      ---------------------------
111      PThreads
112      ---------------------------
113      pthread_attr_init
114      pthread_attr_destroy
115      pthread_attr_getdetachstate
116      pthread_attr_getstackaddr
117      pthread_attr_getstacksize
118      pthread_attr_setdetachstate
119      pthread_attr_setstackaddr
120      pthread_attr_setstacksize
121
122      pthread_create
123      pthread_detach
124      pthread_equal
125      pthread_exit
126      pthread_join
127      pthread_once
128      pthread_self
129
130      pthread_cancel
131      pthread_cleanup_pop
132      pthread_cleanup_push
133      pthread_setcancelstate
134      pthread_setcanceltype
135      pthread_testcancel
136
137      ---------------------------
138      Thread Specific Data
139      ---------------------------
140      pthread_key_create
141      pthread_key_delete
142      pthread_setspecific
143      pthread_getspecific
144
145      ---------------------------
146      Mutexes
147      ---------------------------
148      pthread_mutexattr_init
149      pthread_mutexattr_destroy
150      pthread_mutexattr_getpshared
151      pthread_mutexattr_setpshared
152      pthread_mutexattr_gettype
153      pthread_mutexattr_settype (types: PTHREAD_MUTEX_DEFAULT
154					PTHREAD_MUTEX_NORMAL
155					PTHREAD_MUTEX_ERRORCHECK
156					PTHREAD_MUTEX_RECURSIVE  )
157      pthread_mutexattr_getrobust
158      pthread_mutexattr_setrobust (values: PTHREAD_MUTEX_STALLED
159                                           PTHREAD_MUTEX_ROBUST)
160      pthread_mutex_init
161      pthread_mutex_destroy
162      pthread_mutex_lock
163      pthread_mutex_trylock
164      pthread_mutex_timedlock
165      pthread_mutex_unlock
166      pthread_mutex_consistent
167
168      ---------------------------
169      Condition Variables
170      ---------------------------
171      pthread_condattr_init
172      pthread_condattr_destroy
173      pthread_condattr_getpshared
174      pthread_condattr_setpshared
175
176      pthread_cond_init
177      pthread_cond_destroy
178      pthread_cond_wait
179      pthread_cond_timedwait
180      pthread_cond_signal
181      pthread_cond_broadcast
182
183      ---------------------------
184      Read/Write Locks
185      ---------------------------
186      pthread_rwlock_init
187      pthread_rwlock_destroy
188      pthread_rwlock_tryrdlock
189      pthread_rwlock_trywrlock
190      pthread_rwlock_rdlock
191      pthread_rwlock_timedrdlock
192      pthread_rwlock_rwlock
193      pthread_rwlock_timedwrlock
194      pthread_rwlock_unlock
195      pthread_rwlockattr_init
196      pthread_rwlockattr_destroy
197      pthread_rwlockattr_getpshared
198      pthread_rwlockattr_setpshared
199
200      ---------------------------
201      Spin Locks
202      ---------------------------
203      pthread_spin_init
204      pthread_spin_destroy
205      pthread_spin_lock
206      pthread_spin_unlock
207      pthread_spin_trylock
208
209      ---------------------------
210      Barriers
211      ---------------------------
212      pthread_barrier_init
213      pthread_barrier_destroy
214      pthread_barrier_wait
215      pthread_barrierattr_init
216      pthread_barrierattr_destroy
217      pthread_barrierattr_getpshared
218      pthread_barrierattr_setpshared
219
220      ---------------------------
221      Semaphores
222      ---------------------------
223      sem_init
224      sem_destroy
225      sem_post
226      sem_wait
227      sem_trywait
228      sem_timedwait
229      sem_getvalue	     (# free if +ve, # of waiters if -ve)
230      sem_open		     (returns an error ENOSYS)
231      sem_close 	     (returns an error ENOSYS)
232      sem_unlink	     (returns an error ENOSYS)
233
234      ---------------------------
235      RealTime Scheduling
236      ---------------------------
237      pthread_attr_getschedparam
238      pthread_attr_setschedparam
239      pthread_attr_getinheritsched
240      pthread_attr_setinheritsched
241      pthread_attr_getschedpolicy (only supports SCHED_OTHER)
242      pthread_attr_setschedpolicy (only supports SCHED_OTHER)
243      pthread_getschedparam
244      pthread_setschedparam
245      pthread_getconcurrency
246      pthread_setconcurrency
247      pthread_attr_getscope
248      pthread_attr_setscope  (only supports PTHREAD_SCOPE_SYSTEM)
249      sched_get_priority_max
250      sched_get_priority_min
251      sched_rr_get_interval  (returns an error ENOTSUP)
252      sched_setscheduler     (only supports SCHED_OTHER)
253      sched_getscheduler     (only supports SCHED_OTHER)
254      sched_yield
255
256      ---------------------------
257      Signals
258      ---------------------------
259      pthread_sigmask
260      pthread_kill           (only supports zero sig value,
261                              for thread validity checking)
262
263      ---------------------------
264      Non-portable routines (see the README.NONPORTABLE file for usage)
265      ---------------------------
266      pthread_getw32threadhandle_np
267      pthread_timechange_handler_np
268      pthread_delay_np
269      pthread_getunique_np
270      pthread_mutexattr_getkind_np
271      pthread_mutexattr_setkind_np	(types: PTHREAD_MUTEX_FAST_NP,
272						PTHREAD_MUTEX_ERRORCHECK_NP,
273						PTHREAD_MUTEX_RECURSIVE_NP,
274						PTHREAD_MUTEX_ADAPTIVE_NP,
275						PTHREAD_MUTEX_TIMED_NP)
276      pthread_num_processors_np
277      (The following four routines may be required when linking statically.
278       The process_* routines should not be needed for MSVC or GCC.)
279      pthread_win32_process_attach_np
280      pthread_win32_process_detach_np
281      (The following routines should only be needed to manage implicit
282       POSIX handles i.e. when Win native threads call POSIX thread routines
283       (other than pthread_create))
284      pthread_win32_thread_attach_np
285      pthread_win32_thread_detach_np
286
287      ---------------------------
288      Static Initializers
289      ---------------------------
290      PTHREAD_ONCE_INIT
291      PTHREAD_MUTEX_INITIALIZER
292      PTHREAD_RECURSIVE_MUTEX_INITIALIZER
293      PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP
294      PTHREAD_ERRORCHECK_MUTEX_INITIALIZER
295      PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP
296      PTHREAD_COND_INITIALIZER
297      PTHREAD_RWLOCK_INITIALIZER
298      PTHREAD_SPINLOCK_INITIALIZER
299
300
301The library includes two non-API functions for creating cancellation
302points in applications and libraries:
303
304      pthreadCancelableWait
305      pthreadCancelableTimedWait
306
307
308The following functions are not implemented:
309
310      ---------------------------
311      RealTime Scheduling
312      ---------------------------
313      pthread_mutex_getprioceiling
314      pthread_mutex_setprioceiling
315      pthread_mutex_attr_getprioceiling
316      pthread_mutex_attr_getprotocol
317      pthread_mutex_attr_setprioceiling
318      pthread_mutex_attr_setprotocol
319
320      ---------------------------
321      Fork Handlers
322      ---------------------------
323      pthread_atfork
324
325      ---------------------------
326      Stdio
327      ---------------------------
328      flockfile
329      ftrylockfile
330      funlockfile
331      getc_unlocked
332      getchar_unlocked
333      putc_unlocked
334      putchar_unlocked
335
336      ---------------------------
337      Thread-Safe C Runtime Library
338      ---------------------------
339      readdir_r
340      getgrgid_r
341      getgrnam_r
342      getpwuid_r
343      getpwnam_r
344
345      ---------------------------
346      Signals
347      ---------------------------
348      sigtimedwait
349      sigwait
350      sigwaitinfo
351
352      ---------------------------
353      General
354      ---------------------------
355      sysconf
356
357      ---------------------------
358      Thread-Safe C Runtime Library (macros)
359      ---------------------------
360      strtok_r
361      asctime_r
362      ctime_r
363      gmtime_r
364      localtime_r
365      rand_r
366
367
368Availability
369------------
370
371The prebuilt DLL, export libs (for both MSVC and Mingw32), and the header
372files (pthread.h, semaphore.h, sched.h) are available along with the
373complete source code.
374
375The source code can be found at:
376
377	ftp://sources.redhat.com/pub/pthreads-win32
378
379and as individual source code files at
380
381	ftp://sources.redhat.com/pub/pthreads-win32/source
382
383The pre-built DLL, export libraries and include files can be found at:
384
385	ftp://sources.redhat.com/pub/pthreads-win32/dll-latest
386
387
388
389Mailing List
390------------
391
392There is a mailing list for discussing pthreads on Win32. To join,
393send email to:
394
395	pthreads-win32-subscribe@sourceware.cygnus.com
396
397
398Application Development Environments
399------------------------------------
400
401See the README file for more information.
402
403MSVC:
404MSVC using SEH works. Distribute pthreadVSE.dll with your application.
405MSVC using C++ EH works. Distribute pthreadVCE.dll with your application.
406MSVC using C setjmp/longjmp works. Distribute pthreadVC.dll with your application.
407
408
409Mingw32:
410See the FAQ, Questions 6 and 10.
411
412Mingw using C++ EH works. Distribute pthreadGCE.dll with your application.
413Mingw using C setjmp/longjmp works. Distribute pthreadGC.dll with your application.
414
415
416Cygwin: (http://sourceware.cygnus.com/cygwin/)
417Developers using Cygwin do not need pthreads-win32 since it has POSIX threads
418support. Refer to its documentation for details and extent.
419
420
421UWIN:
422UWIN is a complete Unix-like environment for Windows from AT&T. Pthreads-win32
423doesn't currently support UWIN (and vice versa), but that may change in the
424future.
425
426Generally:
427For convenience, the following pre-built files are available on the FTP site
428(see Availability above):
429
430	pthread.h	- for POSIX threads
431	semaphore.h	- for POSIX semaphores
432	sched.h 	- for POSIX scheduling
433	pthreadVCE.dll	- built with MSVC++ compiler using C++ EH
434	pthreadVCE.lib
435	pthreadVC.dll	- built with MSVC compiler using C setjmp/longjmp
436	pthreadVC.lib
437	pthreadVSE.dll	- built with MSVC compiler using SEH
438	pthreadVSE.lib
439	pthreadGCE.dll	- built with Mingw32 G++ 2.95.2-1
440	pthreadGC.dll	- built with Mingw32 GCC 2.95.2-1 using setjmp/longjmp
441	libpthreadGCE.a - derived from pthreadGCE.dll
442	libpthreadGC.a	- derived from pthreadGC.dll
443	gcc.dll 	- needed if distributing applications that use
444			  pthreadGCE.dll (but see the FAQ Q 10 for the latest
445			  related information)
446
447These are the only files you need in order to build POSIX threads
448applications for Win32 using either MSVC or Mingw32.
449
450See the FAQ file in the source tree for additional information.
451
452
453Documentation
454-------------
455
456For the authoritative reference, see the online POSIX
457standard reference at:
458
459       http://www.OpenGroup.org
460
461For POSIX Thread API programming, several reference books are
462available:
463
464       Programming with POSIX Threads
465       David R. Butenhof
466       Addison-Wesley (pub)
467
468       Pthreads Programming
469       By Bradford Nichols, Dick Buttlar & Jacqueline Proulx Farrell
470       O'Reilly (pub)
471
472On the web: see the links at the bottom of the pthreads-win32 site:
473
474       http://sources.redhat.com/pthreads-win32/
475
476       Currently, there is no documentation included in the package apart
477       from the copious comments in the source code.
478
479
480
481Enjoy!
482
483Ross Johnson
484