1. Introduction

All source that uses threads must include the header

#include <pthread.h>

Name Space

Each threads type is of the form:

pthread[_object]_t

Each threads function (apart from pread(),pwrite() and sigwait()) has the form

pthread[_object]_operation

where object is a type (not required if object is a thread), and operation is a type-specific operation.

All threads functions (except for pread(), pthread_exit(), pthread_getspecific(), pthread_self() and pwrite()) return zero (0) for success and non-zero on failure. The non-zero failure value is an error number to indicate the cause of the error (see errno.h).

.

Threads Types

There are ten (10) threads types.

Type	Description
pthread_attr_t	Used to identify a thread attributes object.
pthread_cond_t	Used for condition variables.
pthread_condattr_t	Used to identify a condition attribute object.
pthread_key_t	Used for thread-specific data (TSD) keys.
pthread_mutex_t	Used for mutexes (mutual excusion lock)
pthread_mutexattr_t	Used to identify a mutex attribute object.
pthread_once_t	Used for once-only initialisation.
pthread_rwlock_t	Used for read-write locks.
pthread_rwlockattr_t	Used for read-write lock attributes.
pthread_t	Used to identify a thread

.

2. UNIX System Threads API

pthread_atfork

Synopsis	int pthread_atfork ( void (*prepare) (void), void (*parent)(void), void (*child) (void));
Description	Register functions to be called during fork() execution
Errors	ENOMEM
Notes	prepare functions are called in reverse order of registration. parent and child functions are called in order of registration

.

Threads Attributes

All threads attributes are set in a thread attributes object by a function of the form:

int pthread_attr_setname( pthread_attr_t *attr, Type t);

All threads attributes are retrieved from a threads attributes object by a function of the form:

int pthread_attr_getname( pthread_attr_t *attr, Type t);

Where name and Type are from the table below:

Type and Name	Description and Value(s)
size_t stacksize	The thread's stack size. >= PTHREAD_STACK_MIN
void *stackaddr	The thread's stack address. For example, void *stack
size_t guardsize	The thread's stack guard size. The default size is PAGESIZE bytes.
int detachstate	The thread's detach state: PTHREAD_CREATE_DETACHED,PTHREAD_CREATE_JOINABLE
int contentionscope	The thread's scope. PTHREAD_SCOPE_SYSTEM, PTHREAD_SCOPE_PROCESS
int inheritsched	The thread's scheduling inheritence PTHREAD_INHERIT_SCHED,PTHREAD_EXPLICIT_SCHED
int schedpolicy	The thread's scheduling policy. SCHED_FIFO, SCHED_RR, SCHED_OTHER
struct sched_param schedparam	The thread's scheduling parameters. See POSIX.1 Section 13

pthread_attr_init

Synopsis	int pthread_attr_init (pthread_attr_t *attr);
Description	Initialize a thread attributes object.
Errors	ENOMEM

pthread_attr_destroy

Synopsis	int pthread_attr_destroy(pthread_attr_t *attr);
Description	Destroy a thread attributes object
Errors	None

The other attribute related functions are listed below:

int pthread_attr_getdetachstate(const pthread_attr_t *attr, int *detachstate);

int pthread_attr_getguardsize(const pthread_attr_t *attr, size_t *guardsize);

int pthread_attr_getinheritsched(const pthread_attr_t *attr, int *inheritsched);

int pthread_attr_getschedparam(const pthread_attr_t *attr, struct sched_param *param);

int pthread_attr_getschedpolicy(const pthread_attr_t *attr, int *policy);

int pthread_attr_getscope(const pthread_attr_t *attr, int *contentionscope);

int pthread_attr_getstackaddr(const pthread_attr_t *attr, void **stackaddr);

int pthread_attr_getstacksize(const pthread_attr_t *attr, size_t *stacksize);

int pthread_attr_setdetachstate(pthread_attr_t *attr, int detachstate);

int pthread_attr_setguardsize(pthread_attr_t *attr, size_t guardsize);

int pthread_attr_setinheritsched(pthread_attr_t *attr, int inheritsched);

int pthread_attr_setschedparam(pthread_attr_t *attr, const struct sched_param *param);

int pthread_attr_setschedpolicy(pthread_attr_t *attr, int policy);

int pthread_attr_setscope(pthread_attr_t *attr, int contentionscope);

int pthread_attr_setstackaddr(pthread_attr_t *attr, void *stackaddr);

int pthread_attr_setstacksize(pthread_attr_t *attr, size_t stacksize);

Thread Management

pthread_create

Synopsis	int pthread_create(pthread_t *thread, const pthread_attr_t *attr, void *(*entry)(void*), void *arg);
Description	Create a new thread of execution
Errors	EAGAIN, EINVAL
Notes	Maximum number of PTHREADS_THREADS_MAX per process

pthread_detach

Synopsis	int pthread_detach(pthread_t thread);
Description	Set the detachstate of the specified thread to PTHREAD_CREATE_DETACHED
Errors	EINVAL,ESRCH

pthread_safe

Synopsis	pthread_t pthread_self(void);
Description	Return the thread ID of the calling thread
Errors	None

pthread_equal

Synopsis	int pthread_equal(pthread_t thread1, pthread_t thread2);
Description	Compare two thread Ids for equality
Errors	None

pthread_exit

Synopsis	void pthread_exit(void *status);
Description	Terminate the calling thread
Errors	None

pthread_join

Synopsis	int pthread_join(pthread_t thread, void **status);
Description	Synchronize with the termination of a thread
Errors	EINVAL,ESRCH,EDEADLK
Notes	This function is a cancellation point

pthread_getschedparam

Synopsis	#include <sched.h> int pthread_getschedparam(pthread_t thread, int *policy, struct sched_param *param);
Description	Get the scheduling policy and parameters of the specified thread
Errors	ENOSYS,ESRCH
Notes	Dependent on support of _XOPEN_REALTIME_THREADS

pthread_setschedparam

Synopsis	#include <sched.h> int pthread_setschedparam(pthread_t thread, int *policy, const struct sched_param *param);
Description	Set the scheduling policy and parameters of the specified thread
Errors	ENOSYS,EINVAL,ENOTSUP,EPERM,ESRCH
Notes	Dependent on support of _XOPEN_REALTIME_THREADS

Mutex Attributes

All mutex attributes are set in a mutex attribute object by a function of the form:

int pthread_mutexattr_setname(pthread_attr_t *attr, Type t);

All mutex attributes are retrieved from a mutex attribute object by a function of the form:

int pthread_mutexattr_getname(const pthread_attr_t *attr, Type *t);

where name and Type are defined as in the table below:

Type and Name	Description and Value(s)
int protocol	Define the scheduling classes for mutex locks PTHREAD_PRIO_NONE,PTHREAD_PRIO_PROTECT, PTHREAD_PRIO_INHERIT
int pshared	Defines whether a mutex is shared with other processes. PTHREAD_PROCESS_SHARED, PTHREAD_PROCESS_PRIVATE
int prioceiling	Used for mutex attribute priority ceiling values. See POSIX.1 section 13
int type	Application defined mutex locking PTHREAD_MUTEX_NORMAL,PTHREAD_MUTEX_RECURSIVE, PTHREAD_MUTEX_ERRORCHECK,PTHREAD_MUTEX_DEFAULT

pthread_mutexattr_init

Synopsis	int pthread_mutexattr_init(pthread_mutexattr_t *attr);
Description	Initialize a mutex attribute object
Errors	ENOMEM

pthread_mutexattr_destroy

Synopsis	int pthread_mutexattr_destroy(pthread_mutexattr_t *attr);
Description	Destroy a mutex attribute object
Errors	EINVAL

The mutex attribute manipulation routines supported are as follows:

int pthread_mutexattr_getprioceiling(const pthread_mutexattr_t *attr, int *prioceling);

int pthread_mutexattr_getprotocol(const pthread_mutexattr_t *attr, int *protocol);

int pthread_mutexattr_getpshared(const pthread_mutexattr_t *attr, int *pshared);

int pthread_mutexattr_gettype(pthread_mutexattr_t *attr, int *type);

int pthread_mutexattr_setprioceiling(pthread_mutexattr_t *attr, int prioceiling);

int pthread_mutexattr_setprotocol(pthread_mutexattr_t *attr, int protocol);

int pthread_mutexattr_setpshared(pthread_mutexattr_t *attr, int pshared);

int pthread_mutexattr_settype(pthread_mutexattr_t *attr, int type);

Mutex Usage

pthread_mutex_init

Synopsis	int pthread_mutex_init(pthread_mutex_t *mutex, const pthread_mutexattr_t *attr);
Description	Initialize a mutex
Errors	EAGAIN,ENOMEM,EPERM,EBUSY,EINVAL

pthread_mutex_destroy

Synopsis	int pthread_mutex_destroy(pthread_mutex_t *mutex);
Description	Destroy a mutex
Errors	EBUSY,EINVAL

pthread_mutex_getprioceiling

Synopsis	int pthread_mutex_getprioceiling(const pthread_mutex_t *mutex, int *prioceiling);
Description	Get the prioceiling value of the specified mutex
Errors	ENOSYS, EINVAL,EPERM
Notes	This is dependent on _XOPEN_REALTIME_THREADS

pthread_mutex_setprioceiling

Synopsis	int pthread_mutex_setprioceiling(pthread_mutex_t *mutex, int prioceiling, int *old_ceiling);
Description	Set the prioceiling value and return the old prioceiling value in the specified mutex
Errors	ENOSYS,EINVAL,EPERM
Notes	This is dependent on _XOPEN_REALTIME_THREADS

pthread_mutex_lock

Synopsis	int pthread_mutex_lock(pthread_mutex_t *mutex);
Description	Acquire the indicated mutex
Errors	EINVAL,EDEADLK

pthread_mutex_trylock

Synopsis	int pthread_mutex_trylock(pthread_mutex_t *mutex);
Description	Attempt to acquire the indicated mutex
Errors	EINVAL,EBUSY

pthread_mutex_unlock

Synopsis	int pthread_mutex_unlock(pthread_mutex_t *mutex);
Description	Release the previously acquired mutex
Errors	EINVAL,EPERM

Once-only execution

Initialize a once control variable:

pthread_once_t once = PTHREAD_ONCE_INIT;

pthread_once

Synopsis	int pthread_once(pthread_once_t *once_control, void (*init_routine)(void));
Description	Execute init_routine once
Errors	None

Condition Variable Attributes

All condition variable attributes are set in a condition variable attribute object by a function of the form:

int pthread_condattr_setname ( pthread_condattr_t *attr_t, Type t);

All condition variable attributes are received from a condition variable attribute object by a function of the form:

int pthread_condattr_getname ( const pthread_condattr_t *attr, Type *t );

Where name and Type are from the table below:

Type and name	Description and Value(s)
int pshared	Defines whether a condition variable is shared with other processes. PTHREAD_PROCESS_SHARED,PTHREAD_PROCESS_PRIVATE

The functions are:

int pthread_condattr_getpshared(const pthread_condattr_t *attr, int *pshared);

int pthread_condattr_setpshared(pthread_condattr_t *attr, int pshared);

pthread_condattr_init

Synopsis	int pthread_condattr_init(pthread_condattr_t *attr);
Description	Initialize a condition variable attribute object
Errors	ENOMEM

pthread_condattr_destroy

Synopsis	int pthread_condattr_destroy(pthread_condattr_t *attr);
Description	Destroy a condition variable attribute object
Errors	EINVAL

Condition Variable Usage

pthread_cond_init

Synopsis	int pthread_cond_init(pthread_cond_t *cond, const pthread_condattr_t *attr);
Description	Initialize a condition variable
Errors	EAGAIN,ENOMEM,EBUSY,EINVAL

pthread_cond_destroy

Synopsis	int pthread_cond_destroy(pthread_cond_t *cond);
Description	Destroy a condition variable
Errors	EBUSY,EINVAL

pthread_cond_signal

Synopsis	int pthread_cond_signal(pthread_cond_t *cond);
Description	Unblock at least one thread currently blocked in the specified condition variable
Errors	EINVAL

pthread_cond_broadcast

Synopsis	int pthread_cond_broadcast(pthread_cond_t *cond);
Description	Unblock all threads currently blocked on the specified condition variable
Errors	EINVAL

pthread_cond_wait

Synopsis	int pthread_cond_wait(pthread_cond_t *cond);
Description	Block on the specified condition variable
Errors	EINVAL
Notes	This function is a cancellation point

pthread_cond_timedwait

Synopsis	int pthread_cond_timedwait(pthread_cond_t *cond, pthread_mutex_t *mutex, const struct timespec *abstime);
Description	Block on the specified condition variable not longer than the specified absolute time
Errors	ETIMEDOUT,EINVAL
Notes	This function is a cancellation point

Thread Specific Data

pthread_key_create

Synopsis	int pthread_key_create(pthread_key_t *key, void (*destructor)(void*));
Description	Create a thread-specific data key
Errors	EAGAIN,ENOMEM
Notes	There is a system limit of PTHREAD_KEYS_MAX per process. There is a system limit of PTHREAD_DESTRUCTOR_ITERATIONS calls to destructor per thread exit

.

pthread_key_delete

Synopsis	int pthread_key_delete(pthread_key_t key);
Description	Destroy a thread-specific data key
Errors	EINVAL

pthread_getspecific

Synopsis	void *pthread_getspecific(pthread_key_t key);
Description	Return the value bound to the given key for the calling thread
Errors	ENOMEM,EINVAL

pthread_setspecific

Synopsis	int pthread_setspecific(pthread_key_t key, const void *value);
Description	Set the value for the given key in the calling thread
Errors	ENOMEM,EINVAL

Signal Management

pthread_sigmask

Synopsis	#include <signal.h> int pthread_sigmask(int how, const sigset_t *newmask, sigset_t *oldmask);
Description	Examine or change calling threads signal mask
Errors	EINVAL
Notes	The value of how can be SIG_BLOCK,SIG_UNBLOCK,SIG_SETMASK

pthread_kill

Synopsis	#include <signal.h> pthread_kill( pthread_t thread, int signo );
Description	Deliver signal to indicated thread
Errors	ESRCH,EINVAL

sigwait

Synopsis	int sigwait( const sigset_t *set, int *sig );
Description	Synchronously accept a signal
Errors	EINVAL,EINTR
Notes	This function is a cancellation point

Cancellation

pthread_setcancelstate

Synopsis	int pthread_setcancelstate(int state, int *oldstate);
Description	Set the cancellation state for the calling thread
Errors	EINVAL
Notes	Values for state are PTHREAD_CANCEL_ENABLE,PTHREAD_CANCEL_DISABLE

pthread_setcanceltype

Synopsis	int pthread_setcanceltype(int type, int *oldtype);
Description	Set the cancellation type for the calling thread
Errors	EINVAL
Notes	Values for type are PTHREAD_CANCEL_ENABLE,PTHREAD_CANCEL_ASYNCHRONOUS

pthread_cancel

Synopsis	int pthread_cancel(pthread_t thread);
Description	Cancel the specified thread
Errors	ESRCH
Notes	Threads that have been cancelled terminate with a status of PTHREAD_CANCELLED

pthread_testcancel

Synopsis	void pthread_testcancel(void);
Description	Introduce a cancellation point
Errors	None
Notes	This function is a cancellation point

pthread_cleanup_push

Synopsis	void pthread_cleanup_push(void (*routine)(void*), void *arg);
Description	Push an item onto the cancellation stack
Errors	None

pthread_cleanup_pop

Synopsis	void pthread_cleanup_pop(int execute);
Description	Pop the top item from the cancellation stack and optionally execute it
Errors	None
Notes	push and pop operations must appear at the same lexical level. execute takes the values 0 or 1.

Concurrency

pthread_getconcurrency

Synopsis	int pthread_getconcurrency(void);
Description	Get level of concurrency
Errors	None

pthread_setconcurrency

Synopsis	int pthread_setconcurrency(int level);
Description	Set level of concurrency
Errors	EINVAL,EAGAIN

Read-Write Locks

pthread_rwlock_init

Synopsis	int pthread_rwlock_init(pthread_rwlock_t *rwlock, const pthread_rwlockattr_t *attr);
Description	Initialize a read-write lock object
Errors	EAGAIN,ENOMEM,EPERM,EBUSY,EINVAL

pthread_rwlock_destory

Synopsis	int pthread_rwlock_destroy(pthread_rwlock_t *rwlock);
Description	Destroy a read-write lock object
Errors	EBUSY,EINVAL

pthread_rwlock_rdlock

Synopsis	int pthread_rwlock_rdlock(pthread_rwlock_t *rwlock);
Description	Lock a read-write lock object for reading
Errors	EINVAL,EDEADLCK,EAGAIN

pthread_rwlock_tryrdlock

Synopsis	int pthread_rwlock_tryrdlock(pthread_rwlock_t *rwlock);
Description	Lock a read-write lock for reading, unless there is an existing write lock or blocked writers
Errors	EBUSY,EINVAL,EDEADLCK,,EAGAIN

pthread_rwlock_wrlock

Synopsis	int pthread_rwlock_wrlock(pthread_rwlock_t *rwlock);
Description	Lock a read-write lock object for writing, block if necessary until the lock becomes available
Errors	EINVAL,EDEADLCK

pthread_rwlock_trywrlock

Synopsis	int pthread_rwlock_trywrlock(pthread_rwlock_t *rwlock);
Description	Lock a read-write lock for writing, unless there are any existing read or write locks
Errors	EBUSY,EINVAL,EDEADLCK

pthread_rwlock_unlock

Synopsis	int pthread_rwlock_unlock(pthread_rwlock_t *rwlock);
Description	Unlock a read-write lock object
Errors	EINVAL,EPERM

pthread_rwlockattr_init

Synopsis	int pthread_rwlockattr_init(pthread_rwlockattr_t *attr);
Description	Initialize a read-write lock attributes object
Errors	ENOMEM

pthread_rwlockattr_destroy

Synopsis	int pthread_rwlockattr_destroy(pthread_rwlockattr_t *attr);
Description	Destroy a read-write lock attributes object
Errors	EINVAL

pthread_rwlockattr_getpshared

Synopsis	int pthread_rwlockattr_getpshared(const pthread_rwlockattr_t *attr, int *pshared);
Description	Get the value of the process-shared attribute of a read-write lock attributes object
Errrors	EINVAL

pthread_rwlockattr_setpshared

Synopsis	int pthread_rwlockattr_setpshared(pthread_rwlockattr_t *attr, int pshared);
Description	Set the value of the process-shared attribute of a read-write lock attributes object
Errrors	EINVAL

Atomic Input/Output

pread

Synopsis	ssize_t pread(int fildes, void * buf, size_t nbyte, off_t offset);
Description	Atomic read of data from file into buffer
Errors	See read()

pwrite

Synopsis	ssize_t pwrite(int fildes, const void * buf, size_t nbyte, off_t offset);
Description	Atomic write of data from buffer into file
Errors	See write()

Realtime Threads Feature Group

The following threads functions are only supported on UNIX systems if the Realtime Threads Feature group is supported (denoted by the symbol _XOPEN_REALTIME_THREADS in <unistd.h>).

pthread_attr_getinheritsched ()	pthread_attr_getschedpolicy()
pthread_attr_getscope()	pthread_attr_setinheritsched()
pthread_attr_setschedpolicy()	pthread_attr_setscope()
pthread_getschedparam()	pthread_mutex_getprioceiling()
pthread_mutex_setprioceiling()	pthread_mutexattr_getprioceiling()
pthread_mutexattr_getprotocol()	pthread_mutexattr_setprioceiling()
pthread_mutexattr_setprotocol()	pthread_setschedparam()

Thread-safety

The following functions are not guaranteed to be thread-safe on all UNIX systems:

asctime()	basename()	catgets()	ctime()
dbm_clearerr()	dbm_close()	dbm_delete()	dbm_error()
dbm_fetch()	dbm_firstkey()	dbm_nextkey()	dbm_open()
dbm_store()	dirname()	drand48()	ecvt()
encrypt()	endgrent()	endpwent()	endutxent()
fcvt()	gamma()	gcvt()	getc_unlocked()
getchar_unlocked()	getdate()	getenv()	getgrent()
getgrgid()	getgrnam()	getlogin()	getopt()
getpwnam()	getpwent()	getpwuid()	getutxent()
getutxid()	getutxline()	getw()	gmtime()
l64a()	lgamma()	lrand48()	localtime()
mrand48()	nl_langinfo()	ptsname()	putc_unlocked()
putchar_unlocked()	putenv()	pututxline()	rand()
readdir()	setgrent()	setkey()	setpwent()
setutxent()	strerror()	strtok()	ttyname()

The functions ctermid() and tmpnam() need not be thread-safe if passed a NULL argument.

The functions in the Legacy Feature Group need not be thread-safe.

New Threads Related Functions

The following functions offer alternate functionality for implementing thread-safe code, some of these

functions are thread-safe versions of common POSIX.1 functions, some are non thread-safe fast functions to be used with the locking facilities also defined in this section.

asctime_r

Synopsis	#include <time.h> char *asctime_r (const struct tm *tm, char *buf);
Description	Thread safe version of asctime()

ctime_r

Synopsis	#include <time.h> char *ctime_r(const time_t *clock, char *buf);
Description	Thread safe version of ctime()

flockfile

Synopsis	#include <stdio.h> void flockfile(FILE * file);
Description	Lock a stdio (FILE *) object

ftrylockfile

Synopsis	#include <stdio.h> int ftrylockfile(FILE * file);
Description	Attempt to lock a stdio (FILE *) object if available, do not block

funlockfile

Synopsis	#include <stdio.h> void funlockfile(FILE * file);
Description	Unlock a stdio (FILE *) object

getc_unlocked

Synopsis	#include <stdio.h> int getc_unlocked(FILE * stream);
Description	Fast version of getc() to be used in conjunction with flockfile(), ftrylockfile() and funlockfile()

getchar_unlocked

Synopsis	#include <stdio.h> int getchar_unlocked(void);
Description	Fast version of getchar() to be used in conjunction with flockfile(), ftrylockfile() and funlockfile()

getgrgid_r

Synopsis	#include <grp.h> int getgrgid_r(gid_t gid, struct group *grp, char *buffer, size_t bufsize, struct group **result);
Description	Thread safe version of getgrgid()

getgrnam_r

Synopsis	int getgrnam_r(const char * name, struct group * grp, char * buffer,size_t bufsize, struct group ** result);
Description	Thread safe version of getgrnam()

getpwnam_r

Synopsis	int getpwnam_r(const char * nam, struct passwd * pwd, char * buffer, size_t bufsize, struct passwd ** result);
Description	Thread safe version of getpwnam()

getpwuid_r

Synopsis	int getpwuid_r(uid_t uid, struct passwd * pwd, char * buffer, size_t bufsize, struct passwd ** result);
Description	Thread safe version of getpwuid()

gmtime_r

Synopsis	#include <time.h> struct tm *gmtime_r(const time_t *clock, struct tm *result);
Description	Thread safe version of gmtime()

localtime_r

Synopsis	#include <time.h> struct tm *localtime_r(const time_t *clock, struct tm *result);
Description	Thread safe version of localtime()

putc_unlocked

Synopsis	#include <stdio.h> int putc_unlocked(int c, FILE * stream);
Description	Fast version of putc() to be used in conjunction with flockfile(), ftrylockfile() and funlockfile()

putchar_unlocked

Synopsis	#include <stdio.h> int putchar_unlocked(int c);
Description	Fast version of putchar() to be used in conjunction with flockfile(), ftrylockfile() and funlockfile()

rand_r

Synopsis	#include <stdlib.h> int rand_r(unsigned int *seed);
Description	Thread safe version of rand()

readdir_r

Synopsis	int readdir_r(DIR * dirp, struct direct * entry, struct dirent ** result);
Description	Thread safe version of readdir()

strtok_r

Synopsis	char *strtok_r(char * s, const char * sep, char ** lasts);
Description	Thread safe version of strtok()

Read other technical papers.

Read or download the complete Single UNIX Specification from http://www.UNIX-systems.org/go/unix.

Copyright © 1997-1998 The Open Group

UNIX is a registered trademark of The Open Group.