Open Source
POSIX Threads for Win32



Announcement

PTHREADS-WIN32 RELEASE 2.9.1 (2012-05-27)

-----------------------------------------

Web Site: http://sourceware.org/pthreads-win32/

FTP Site: ftp://sourceware.org/pub/pthreads-win32



We are pleased to announce the availability of a new release of

Pthreads-win32, an Open Source Software implementation of the

Threads component of the POSIX 1003.1 2001 Standard for Microsoft's

Win32 environment. Some functions from other sections of POSIX

1003.1 2001 are also supported including semaphores and scheduling

functions.


This release replaces an extremely brief 2.9.0 release and adds

some last minute non-code changes were made to embed better

descriptive properties in the dlls to indicate target architecture

and build environments.


Some common non-portable functions are also implemented for

additional compatibility, as are a few functions specific

to pthreads-win32 for easier integration with Win32 applications.


Pthreads-win32 is free software, distributed under the GNU Lesser

General Public License (LGPL).



Acknowledgements

----------------

This library is based originally on a Win32 pthreads

implementation contributed by John Bossom.


The implementation of Condition Variables uses algorithms developed

by Alexander Terekhov and Louis Thomas.


The implementation of POSIX mutexes has been improved by Thomas Pfaff

and later by Alexander Terekhov.


The implementation of Spinlocks and Barriers was contributed

by Ross Johnson.


The implementation of read/write locks was contributed by

Aurelio Medina and improved by Alexander Terekhov.


Many others have contributed significant time and effort to solve crutial

problems in order to make the library workable, robust and reliable.


Thanks to Xavier Leroy for granting permission to use and modify his

LinuxThreads manual pages.


Thanks to The Open Group for making the Single Unix Specification

publicly available - many of the manual pages included in the package

were extracted from it.


There is also a separate CONTRIBUTORS file. This file and others are

on the web site:


http://sourceware.org/pthreads-win32


As much as possible, the ChangeLog file acknowledges contributions to the

code base in more detail.



Changes since the last release

------------------------------

These are now documented in the NEWS file.

See the ChangeLog file also.



Known Bugs

----------

These are now documented in the BUGS file.



Level of standards conformance

------------------------------


The following POSIX 1003.1 2001 options are defined and set to 200112L:


_POSIX_THREADS

_POSIX_THREAD_SAFE_FUNCTIONS

_POSIX_THREAD_ATTR_STACKSIZE

_POSIX_THREAD_PRIORITY_SCHEDULING

_POSIX_SEMAPHORES

_POSIX_READER_WRITER_LOCKS

_POSIX_SPIN_LOCKS

_POSIX_BARRIERS



The following POSIX 1003.1 2001 options are defined and set to -1:


_POSIX_THREAD_ATTR_STACKADDR

_POSIX_THREAD_PRIO_INHERIT

_POSIX_THREAD_PRIO_PROTECT

_POSIX_THREAD_PROCESS_SHARED



The following POSIX 1003.1 2001 limits are defined and set:


_POSIX_THREAD_THREADS_MAX

_POSIX_SEM_VALUE_MAX

_POSIX_SEM_NSEMS_MAX

_POSIX_THREAD_KEYS_MAX

_POSIX_THREAD_DESTRUCTOR_ITERATIONS

PTHREAD_STACK_MIN

PTHREAD_THREADS_MAX

SEM_VALUE_MAX

SEM_NSEMS_MAX

PTHREAD_KEYS_MAX

PTHREAD_DESTRUCTOR_ITERATIONS



The following functions are implemented:


---------------------------

PThreads

---------------------------

pthread_attr_init

pthread_attr_destroy

pthread_attr_getdetachstate

pthread_attr_getstackaddr

pthread_attr_getstacksize

pthread_attr_setdetachstate

pthread_attr_setstackaddr

pthread_attr_setstacksize


pthread_create

pthread_detach

pthread_equal

pthread_exit

pthread_join

pthread_once

pthread_self


pthread_cancel

pthread_cleanup_pop

pthread_cleanup_push

pthread_setcancelstate

pthread_setcanceltype

pthread_testcancel


---------------------------

Thread Specific Data

---------------------------

pthread_key_create

pthread_key_delete

pthread_setspecific

pthread_getspecific


---------------------------

Mutexes

---------------------------

pthread_mutexattr_init

pthread_mutexattr_destroy

pthread_mutexattr_getpshared

pthread_mutexattr_setpshared

pthread_mutexattr_gettype

pthread_mutexattr_settype (types: PTHREAD_MUTEX_DEFAULT

PTHREAD_MUTEX_NORMAL

PTHREAD_MUTEX_ERRORCHECK

PTHREAD_MUTEX_RECURSIVE )

pthread_mutexattr_getrobust

pthread_mutexattr_setrobust (values: PTHREAD_MUTEX_STALLED

PTHREAD_MUTEX_ROBUST)

pthread_mutex_init

pthread_mutex_destroy

pthread_mutex_lock

pthread_mutex_trylock

pthread_mutex_timedlock

pthread_mutex_unlock

pthread_mutex_consistent


---------------------------

Condition Variables

---------------------------

pthread_condattr_init

pthread_condattr_destroy

pthread_condattr_getpshared

pthread_condattr_setpshared


pthread_cond_init

pthread_cond_destroy

pthread_cond_wait

pthread_cond_timedwait

pthread_cond_signal

pthread_cond_broadcast


---------------------------

Read/Write Locks

---------------------------

pthread_rwlock_init

pthread_rwlock_destroy

pthread_rwlock_tryrdlock

pthread_rwlock_trywrlock

pthread_rwlock_rdlock

pthread_rwlock_timedrdlock

pthread_rwlock_rwlock

pthread_rwlock_timedwrlock

pthread_rwlock_unlock

pthread_rwlockattr_init

pthread_rwlockattr_destroy

pthread_rwlockattr_getpshared

pthread_rwlockattr_setpshared


---------------------------

Spin Locks

---------------------------

pthread_spin_init

pthread_spin_destroy

pthread_spin_lock

pthread_spin_unlock

pthread_spin_trylock


---------------------------

Barriers

---------------------------

pthread_barrier_init

pthread_barrier_destroy

pthread_barrier_wait

pthread_barrierattr_init

pthread_barrierattr_destroy

pthread_barrierattr_getpshared

pthread_barrierattr_setpshared


---------------------------

Semaphores

---------------------------

sem_init

sem_destroy

sem_post

sem_wait

sem_trywait

sem_timedwait

sem_getvalue (# free if +ve, # of waiters if -ve)

sem_open (returns an error ENOSYS)

sem_close (returns an error ENOSYS)

sem_unlink (returns an error ENOSYS)


---------------------------

RealTime Scheduling

---------------------------

pthread_attr_getschedparam

pthread_attr_setschedparam

pthread_attr_getinheritsched

pthread_attr_setinheritsched

pthread_attr_getschedpolicy (only supports SCHED_OTHER)

pthread_attr_setschedpolicy (only supports SCHED_OTHER)

pthread_getschedparam

pthread_setschedparam

pthread_getconcurrency

pthread_setconcurrency

pthread_attr_getscope

pthread_attr_setscope (only supports PTHREAD_SCOPE_SYSTEM)

sched_get_priority_max

sched_get_priority_min

sched_rr_get_interval (returns an error ENOTSUP)

sched_setscheduler (only supports SCHED_OTHER)

sched_getscheduler (only supports SCHED_OTHER)

sched_yield


---------------------------

Signals

---------------------------

pthread_sigmask

pthread_kill (only supports zero sig value,

for thread validity checking)


---------------------------

Non-portable routines (see the README.NONPORTABLE file for usage)

---------------------------

pthread_getw32threadhandle_np

pthread_timechange_handler_np

pthread_delay_np

pthread_getunique_np

pthread_mutexattr_getkind_np

pthread_mutexattr_setkind_np (types: PTHREAD_MUTEX_FAST_NP,

PTHREAD_MUTEX_ERRORCHECK_NP,

PTHREAD_MUTEX_RECURSIVE_NP,

PTHREAD_MUTEX_ADAPTIVE_NP,

PTHREAD_MUTEX_TIMED_NP)

pthread_num_processors_np

(The following four routines may be required when linking statically.

The process_* routines should not be needed for MSVC or GCC.)

pthread_win32_process_attach_np

pthread_win32_process_detach_np

(The following routines should only be needed to manage implicit

POSIX handles i.e. when Win native threads call POSIX thread routines

(other than pthread_create))

pthread_win32_thread_attach_np

pthread_win32_thread_detach_np


---------------------------

Static Initializers

---------------------------

PTHREAD_ONCE_INIT

PTHREAD_MUTEX_INITIALIZER

PTHREAD_RECURSIVE_MUTEX_INITIALIZER

PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP

PTHREAD_ERRORCHECK_MUTEX_INITIALIZER

PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP

PTHREAD_COND_INITIALIZER

PTHREAD_RWLOCK_INITIALIZER

PTHREAD_SPINLOCK_INITIALIZER



The library includes two non-API functions for creating cancellation

points in applications and libraries:

pthreadCancelableWait

pthreadCancelableTimedWait


The following functions are not implemented:


---------------------------

RealTime Scheduling

---------------------------

pthread_mutex_getprioceiling

pthread_mutex_setprioceiling

pthread_mutex_attr_getprioceiling

pthread_mutex_attr_getprotocol

pthread_mutex_attr_setprioceiling

pthread_mutex_attr_setprotocol


---------------------------

Fork Handlers

---------------------------

pthread_atfork


---------------------------

Stdio

---------------------------

flockfile

ftrylockfile

funlockfile

getc_unlocked

getchar_unlocked

putc_unlocked

putchar_unlocked


---------------------------

Thread-Safe C Runtime Library

---------------------------

readdir_r

getgrgid_r

getgrnam_r

getpwuid_r

getpwnam_r

---------------------------

Signals

---------------------------

sigtimedwait

sigwait

sigwaitinfo


---------------------------

General

---------------------------

sysconf


---------------------------

Thread-Safe C Runtime Library (macros)

---------------------------

strtok_r

asctime_r

ctime_r

gmtime_r

localtime_r

rand_r



Availability

------------


The prebuilt DLL, export libs (for both MSVC and Mingw32), and the header

files (pthread.h, semaphore.h, sched.h) are available along with the

complete source code.


The source code can be found at:


ftp://sources.redhat.com/pub/pthreads-win32


and as individual source code files at


ftp://sources.redhat.com/pub/pthreads-win32/source


The pre-built DLL, export libraries and include files can be found at:


ftp://sources.redhat.com/pub/pthreads-win32/dll-latest



Mailing List

------------

There is a mailing list for discussing pthreads on Win32. To join,

send email to:


pthreads-win32-subscribe@sourceware.cygnus.com


Application Development Environments

------------------------------------


See the README file for more information.

MSVC:

MSVC using SEH works. Distribute pthreadVSE.dll with your application.

MSVC using C++ EH works. Distribute pthreadVCE.dll with your application.

MSVC using C setjmp/longjmp works. Distribute pthreadVC.dll with your application.



Mingw32:

See the FAQ, Questions 6 and 10.


Mingw using C++ EH works. Distribute pthreadGCE.dll with your application.

Mingw using C setjmp/longjmp works. Distribute pthreadGC.dll with your application.



Cygwin: (http://sourceware.cygnus.com/cygwin/)

Developers using Cygwin do not need pthreads-win32 since it has POSIX threads

support. Refer to its documentation for details and extent.



UWIN:

UWIN is a complete Unix-like environment for Windows from AT&T. Pthreads-win32

doesn't currently support UWIN (and vice versa), but that may change in the

future.


Generally:

For convenience, the following pre-built files are available on the FTP site

(see Availability above):


pthread.h - for POSIX threads

semaphore.h - for POSIX semaphores

sched.h - for POSIX scheduling

pthreadVCE.dll - built with MSVC++ compiler using C++ EH

pthreadVCE.lib

pthreadVC.dll - built with MSVC compiler using C setjmp/longjmp

pthreadVC.lib

pthreadVSE.dll - built with MSVC compiler using SEH

pthreadVSE.lib

pthreadGCE.dll - built with Mingw32 G++ 2.95.2-1

pthreadGC.dll - built with Mingw32 GCC 2.95.2-1 using setjmp/longjmp

libpthreadGCE.a - derived from pthreadGCE.dll

libpthreadGC.a - derived from pthreadGC.dll

gcc.dll - needed if distributing applications that use

pthreadGCE.dll (but see the FAQ Q 10 for the latest

related information)


These are the only files you need in order to build POSIX threads

applications for Win32 using either MSVC or Mingw32.


See the FAQ file in the source tree for additional information.



Documentation

-------------


For the authoritative reference, see the online POSIX

standard reference at:


http://www.OpenGroup.org


For POSIX Thread API programming, several reference books are

available:


Programming with POSIX Threads

David R. Butenhof

Addison-Wesley (pub)


Pthreads Programming

By Bradford Nichols, Dick Buttlar & Jacqueline Proulx Farrell

O'Reilly (pub)


On the web: see the links at the bottom of the pthreads-win32 site:


http://sources.redhat.com/pthreads-win32/


Currently, there is no documentation included in the package apart

from the copious comments in the source code.




Enjoy!


Ross Johnson



Maintained by Ross Johnson