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

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
PTHREAD(3)	       FreeBSD Library Functions Manual		    PTHREAD(3)

NAME
     pthread --	POSIX thread functions

SYNOPSIS
     #include <pthread.h>

DESCRIPTION
     POSIX threads are a set of	functions that support applications with
     requirements for multiple flows of	control, called	threads, within	a
     process.  Multithreading is used to improve the performance of a program.

     The POSIX thread functions	are summarized in this section in the follow-
     ing groups:

	   +o   Thread Routines

	   +o   Attribute Object	Routines

	   +o   Mutex Routines

	   +o   Condition Variable Routines

	   +o   Read/Write Lock Routines

	   +o   Per-Thread Context Routines

	   +o   Cleanup Routines

THREAD ROUTINES
     int pthread_create(pthread_t *thread, const pthread_attr_t	*attr, void
			*(*start_routine)(void *), void	*arg)
			Creates	a new thread of	execution.

     int pthread_cancel(pthread_t thread)
			Cancels	execution of a thread.

     int pthread_detach(pthread_t thread)
			Marks a	thread for deletion.

     int pthread_equal(pthread_t t1, pthread_t t2)
			Compares two thread IDs.

     void pthread_exit(void *value_ptr)
			Terminates the calling thread.

     int pthread_join(pthread_t	thread,	void **value_ptr)
			Causes the calling thread to wait for the termination
			of the specified thread.

     int pthread_kill(pthread_t	thread,	int sig)
			Delivers a signal to a specified thread.

     int pthread_once(pthread_once_t *once_control, void
			(*init_routine)(void))
			Calls an initialization	routine	once.

     pthread_t pthread_self(void)
			Returns	the thread ID of the calling thread.

     int pthread_setcancelstate(int state, int *oldstate)
			Sets the current thread's cancelability	state.

     int pthread_setcanceltype(int type, int *oldtype)
			Sets the current thread's cancelability	type.

     void pthread_testcancel(void)
			Creates	a cancellation point in	the calling thread.

     void pthread_yield(void)
			Allows the scheduler to	run another thread instead of
			the current one.

ATTRIBUTE OBJECT ROUTINES
     int pthread_attr_destroy(pthread_attr_t *attr)
			Destroy	a thread attributes object.

     int pthread_attr_getinheritsched(const pthread_attr_t *attr, int
			*inheritsched)
			Get the	inherit	scheduling attribute from a thread
			attributes object.

     int pthread_attr_getschedparam(const pthread_attr_t *attr,	struct
			sched_param *param)
			Get the	scheduling parameter attribute from a thread
			attributes object.

     int pthread_attr_getschedpolicy(const pthread_attr_t *attr, int *policy)
			Get the	scheduling policy attribute from a thread
			attributes object.

     int pthread_attr_getscope(const pthread_attr_t *attr, int
			*contentionscope)
			Get the	contention scope attribute from	a thread
			attributes object.

     int pthread_attr_getstacksize(const pthread_attr_t	*attr, size_t
			*stacksize)
			Get the	stack size attribute from a thread attributes
			object.

     int pthread_attr_getstackaddr(const pthread_attr_t	*attr, void
			**stackaddr)
			Get the	stack address attribute	from a thread
			attributes object.

     int pthread_attr_getdetachstate(const pthread_attr_t *attr, int
			*detachstate)
			Get the	detach state attribute from a thread
			attributes object.

     int pthread_attr_init(pthread_attr_t *attr)
			Initialize a thread attributes object with default
			values.

     int pthread_attr_setinheritsched(pthread_attr_t *attr, int	inheritsched)
			Set the	inherit	scheduling attribute in	a thread
			attributes object.

     int pthread_attr_setschedparam(pthread_attr_t *attr, const	struct
			sched_param *param)
			Set the	scheduling parameter attribute in a thread
			attributes object.

     int pthread_attr_setschedpolicy(pthread_attr_t *attr, int policy)
			Set the	scheduling policy attribute in a thread
			attributes object.

     int pthread_attr_setscope(pthread_attr_t *attr, int contentionscope)
			Set the	contention scope attribute in a	thread
			attributes object.

     int pthread_attr_setstacksize(pthread_attr_t *attr, size_t	stacksize)
			Set the	stack size attribute in	a thread attributes
			object.

     int pthread_attr_setstackaddr(pthread_attr_t *attr, void *stackaddr)
			Set the	stack address attribute	in a thread attributes
			object.

     int pthread_attr_setdetachstate(pthread_attr_t *attr, int detachstate)
			Set the	detach state in	a thread attributes object.

MUTEX ROUTINES
     int pthread_mutexattr_destroy(pthread_mutexattr_t *attr)
			Destroy	a mutex	attributes object.

     int pthread_mutexattr_getprioceiling(pthread_mutexattr_t *attr, int
			*ceiling)
			Obtain priority	ceiling	attribute of mutex attribute
			object.

     int pthread_mutexattr_getprotocol(pthread_mutexattr_t *attr, int
			*protocol)
			Obtain protocol	attribute of mutex attribute object.

     int pthread_mutexattr_gettype(pthread_mutexattr_t *attr, int *type)
			Obtain the mutex type attribute	in the specified mutex
			attributes object.

     int pthread_mutexattr_init(pthread_mutexattr_t *attr)
			Initialize a mutex attributes object with default val-
			ues.

     int pthread_mutexattr_setprioceiling(pthread_mutexattr_t *attr, int
			ceiling)
			Set priority ceiling attribute of mutex	attribute
			object.

     int pthread_mutexattr_setprotocol(pthread_mutexattr_t *attr, int
			protocol)
			Set protocol attribute of mutex	attribute object.

     int pthread_mutexattr_settype(pthread_mutexattr_t *attr, int type)
			Set the	mutex type attribute that is used when a mutex
			is created.

     int pthread_mutex_destroy(pthread_mutex_t *mutex)
			Destroy	a mutex.

     int pthread_mutex_init(pthread_mutex_t *mutex, const pthread_mutexattr_t
			*attr)
			Initialize a mutex with	specified attributes.

     int pthread_mutex_lock(pthread_mutex_t *mutex)
			Lock a mutex and block until it	becomes	available.

     int pthread_mutex_trylock(pthread_mutex_t *mutex)
			Try to lock a mutex, but don't block if	the mutex is
			locked by another thread, including the	current
			thread.

     int pthread_mutex_unlock(pthread_mutex_t *mutex)
			Unlock a mutex.

CONDITION VARIABLE ROUTINES
     int pthread_condattr_destroy(pthread_condattr_t *attr)
			Destroy	a condition variable attributes	object.

     int pthread_condattr_init(pthread_condattr_t *attr)
			Initialize a condition variable	attributes object with
			default	values.

     int pthread_cond_broadcast(pthread_cond_t *cond)
			Unblock	all threads currently blocked on the specified
			condition variable.

     int pthread_cond_destroy(pthread_cond_t *cond)
			Destroy	a condition variable.

     int pthread_cond_init(pthread_cond_t *cond, const pthread_condattr_t
			*attr)
			Initialize a condition variable	with specified
			attributes.

     int pthread_cond_signal(pthread_cond_t *cond)
			Unblock	at least one of	the threads blocked on the
			specified condition variable.

     int pthread_cond_timedwait(pthread_cond_t *cond, pthread_mutex_t *mutex,
			const struct timespec *abstime)
			Wait no	longer than the	specified time for a condition
			and lock the specified mutex.

     int pthread_cond_wait(pthread_cond_t *, pthread_mutex_t *mutex)
			Wait for a condition and lock the specified mutex.

READ/WRITE LOCK	ROUTINES
     int pthread_rwlock_destroy(pthread_rwlock_t *lock)
			Destroy	a read/write lock object.

     int pthread_rwlock_init(pthread_rwlock_t *lock, const
			pthread_rwlockattr_t *attr)
			Initialize a read/write	lock object.

     int pthread_rwlock_rdlock(pthread_rwlock_t	*lock)
			Lock a read/write lock for reading, blocking until the
			lock can be acquired.

     int pthread_rwlock_tryrdlock(pthread_rwlock_t *lock)
			Attempt	to lock	a read/write lock for reading, without
			blocking if the	lock is	unavailable.

     int pthread_rwlock_trywrlock(pthread_rwlock_t *lock)
			Attempt	to lock	a read/write lock for writing, without
			blocking if the	lock is	unavailable.

     int pthread_rwlock_unlock(pthread_rwlock_t	*lock)
			Unlock a read/write lock.

     int pthread_rwlock_wrlock(pthread_rwlock_t	*lock)
			Lock a read/write lock for writing, blocking until the
			lock can be acquired.

     int pthread_rwlockattr_destroy(pthread_rwlockattr_t *attr)
			Destroy	a read/write lock attribute object.

     int pthread_rwlockattr_getpshared(const pthread_rwlockattr_t *attr, int
			*pshared)
			Retrieve the process shared setting for	the read/write
			lock attribute object.

     int pthread_rwlockattr_init(pthread_rwlockattr_t *attr)
			Initialize a read/write	lock attribute object.

     int pthread_rwlockattr_setpshared(pthread_rwlockattr_t *attr, int
			pshared)
			Set the	process	shared setting for the read/write lock
			attribute object.

PER-THREAD CONTEXT ROUTINES
     int pthread_key_create(pthread_key_t *key,	void (*routine)(void *))
			Create a thread-specific data key.

     int pthread_key_delete(pthread_key_t key)
			Delete a thread-specific data key.

     void * pthread_getspecific(pthread_key_t key)
			Get the	thread-specific	value for the specified	key.

     int pthread_setspecific(pthread_key_t key,	const void *value_ptr)
			Set the	thread-specific	value for the specified	key.

CLEANUP	ROUTINES
     void pthread_cleanup_pop(int execute)
			Remove the routine at the top of the calling thread's
			cancellation cleanup stack and optionally invoke it.

     void pthread_cleanup_push(void (*routine)(void *),	void *routine_arg)
			Push the specified cancellation	cleanup	handler	onto
			the calling thread's cancellation stack.

INSTALLATION
     The current FreeBSD POSIX thread implementation is	built in the library
     libc_r which contains both	thread-safe libc functions and the thread
     functions.	 This library replaces libc for	threaded applications.

     By	default, libc_r	is built as part of a 'make world'.  To	disable	the
     build of libc_r you must supply the '-DNOLIBC_R' option to	make(1).

     A FreeBSD specific	option has been	added to gcc to	make linking threaded
     processes simple.	gcc -pthread links a threaded process against libc_r
     instead of	libc.

SEE ALSO
     pthread_cleanup_pop(3), pthread_cleanup_push(3),
     pthread_condattr_destroy(3), pthread_condattr_init(3),
     pthread_cond_broadcast(3),	pthread_cond_destroy(3), pthread_cond_init(3),
     pthread_cond_signal(3), pthread_cond_timedwait(3),	pthread_cond_wait(3),
     pthread_create(3),	pthread_detach(3), pthread_equal(3), pthread_exit(3),
     pthread_getspecific(3), pthread_join(3), pthread_key_delete(3),
     pthread_kill(3), pthread_mutexattr_destroy(3),
     pthread_mutexattr_getprioceiling(3), pthread_mutexattr_getprotocol(3),
     pthread_mutexattr_gettype(3), pthread_mutexattr_init(3),
     pthread_mutexattr_setprioceiling(3), pthread_mutexattr_setprotocol(3),
     pthread_mutexattr_settype(3), pthread_mutex_destroy(3),
     pthread_mutex_init(3), pthread_mutex_lock(3), pthread_mutex_trylock(3),
     pthread_mutex_unlock(3), pthread_once(3), pthread_rwlockattr_destroy(3),
     pthread_rwlockattr_getpshared(3), pthread_rwlockattr_init(3),
     pthread_rwlockattr_setpshared(3), pthread_rwlock_destroy(3),
     pthread_rwlock_init(3), pthread_rwlock_rdlock(3),
     pthread_rwlock_unlock(3), pthread_rwlock_wrlock(3), pthread_self(3),
     pthread_setcancelstate(3),	pthread_setcanceltype(3),
     pthread_setspecific(3), pthread_testcancel(3)

STANDARDS
     The functions in libc_r with the pthread_ prefix and not _np suffix or
     pthread_rwlock prefix conform to ISO/IEC 9945-1:1996 (``POSIX.1'').

     The functions in libc_r with the pthread_ prefix and _np suffix are non-
     portable extensions to POSIX threads.

     The functions in libc_r with the pthread_rwlock prefix are	extensions
     created by	The Open Group as part of the Version 2	of the Single UNIX
     Specification (``SUSv2'').

FreeBSD	9.2		      September	10, 1998		   FreeBSD 9.2

NAME | SYNOPSIS | DESCRIPTION | THREAD ROUTINES | ATTRIBUTE OBJECT ROUTINES | MUTEX ROUTINES | CONDITION VARIABLE ROUTINES | READ/WRITE LOCK ROUTINES | PER-THREAD CONTEXT ROUTINES | CLEANUP ROUTINES | INSTALLATION | SEE ALSO | STANDARDS

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=pthread&sektion=3&manpath=FreeBSD+5.2.1-RELEASE>

home | help