Files
file	pthread.h

Functions
int	pthread_create (pthread_t thread, const pthread_attr_t attr, void (start_routine)(void ), void arg)
	Create a thread. More...

void	pthread_exit (void *retval)
	Exit a thread. More...

int	pthread_join (pthread_t thread, void **retval)
	Wait for a thread. More...

int	pthread_detach (pthread_t thread)
	Detach a thread. More...

int	pthread_mutex_init (pthread_mutex_t mutex, const pthread_mutexattr_t mutexattr)
	Create a mutex. More...

int	pthread_mutex_lock (pthread_mutex_t *mutex)
	Lock a mutex. More...

int	pthread_mutex_unlock (pthread_mutex_t *mutex)
	Unlock a mutex. More...

int	pthread_mutex_destroy (pthread_mutex_t *mutex)
	Destroy a mutex. More...

Detailed Description

This page shows a simplified interface for POSIX threads (pthreads). Threads are a more lightweight method to use the concurrency potential of modern multi-core processors, compared to the process concept of Linux.

Disclaimer: Some parts of the interface are simplified. This page does not replace a thorough study of the manpages for the respective functions!

The pthread_*() function family does not set the errno variable to indicate the error cause, but instead returns an error value (or 0 on success). Thus, the return value of pthread_*() functions can be usually assigned to errno (except otherwise stated) and in case of an error perror() can be used to print a meaningful error message. Be aware, that the errno is not a global but a thread-local variable, hence each thread has its own errno.

If you intend to use this library, make sure to run your gcc with the appropriate flags.

-pthread -std=c11 -Werror -Wall -pedantic -D_XOPEN_SOURCE=700 -O3

Minimal pthread example:

static int counter = 0;
  
// Function the threads execute
void *thread_func(void *arg) {
    pthread_mutex_t *mutex = (pthread_mutex_t *) arg;
  
    // do stuff concurrently
    for (unsigned int i = 0; i < 1000; i++) {
        pthread_mutex_lock(mutex);
        counter++;
        pthread_mutex_unlock(mutex);
    }
  
    pthread_exit(NULL);
}
  
int main(int argc, char *argv[]) {
    // create mutex
    pthread_mutex_t mutex;
    errno = pthread_mutex_init(&mutex, NULL);
    if (errno != 0) {
        perror("pthread_mutex_init");
        exit(EXIT_FAILURE);
    }
  
    // create and start threads
    pthread_t threads[4];
    for (unsigned int i = 0; i < 4; i++) {
        errno = pthread_create(&(threads[i]), NULL, thread_func,
                               (void *) &mutex);
        if (errno != 0) {
            perror("pthread_create");
            exit(EXIT_FAILURE);
        }
    }
  
    // wait until threads terminate
    for (unsigned int i = 0; i < 4; i++) {
        errno = pthread_join(threads[i], NULL);
        if (errno != 0) {
            perror("pthread_join");
            exit(EXIT_FAILURE);
        }
    }
  
    pthread_mutex_destroy(&mutex);
  
    printf("counter: %i\n", counter);
}

Function Documentation

int pthread_create	(	pthread_t *	thread,
		const pthread_attr_t *	attr,
		void ()(void *)	start_routine,
		void *	arg
	)

The pthread_create() function creates and starts a new thread within the calling process. The new thread will initially execute the function specified in start_routine, which receives a void * pointer as parameter and returns a void * pointer. The argument handed over to the new thread is specified in arg.

The pthread_create() function uses the pointer in thread to store the thread id in the underlying pthread_t variable, which can be used to identify a thread in further pthread_* function calls.

The attributes for the new thread are specified in attr. For default attributes NULL can be used.

A thread that has been created with pthread_create() must be joined with pthread_join() or marked as detached using pthread_detach() in order to free the resources associated with the thread. This is similar to fork() and waitpid() for processes.

Parameters

thread	pointer to the thread id
attr	thread attributes (`NULL` for default attributes)
start_routine	function the thread initially executes
arg	argument for `start_routine`

Return values

0	on success
!=0	on error

void pthread_exit ( void * retval )

The pthread_exit() function terminates the calling thread with the return value in retval.

This function never returns.

Parameters

retval return value visible to a pthread_join() caller

int pthread_join	(	pthread_t	thread,
		void **	retval
	)

The pthread_join() function waits for the thread in thread to terminate. If the thread has already been terminated, the pthread_join() function returns immediately. The return value of the terminated thread can be retrieved by retval.

Be aware that threads marked as detached (pthread_detach()) can not be joined anymore!

Example code

void *retval;
  
errno = pthread_join(thread, &retval);
if (errno != 0) {
    perror("pthread_join");
    exit(EXIT_FAILURE);
}
  
printf("Exit code of thread: %p\n", retval);

Parameters

thread	thread to wait for
retval	buffer for a pointer to the return value

Return values

0	on success
!=0	on error

int pthread_detach ( pthread_t thread )

The pthread_detach() function marks the thread in thread detached. This automatically frees all resources, when the threads exits. Once a thread is marked as detached it can not be joined using pthread_join() anymore!

Parameters

thread thread to detach

Return values

0	on success
!=0	on error

int pthread_mutex_init	(	pthread_mutex_t *	mutex,
		const pthread_mutexattr_t *	mutexattr
	)

The pthread_mutex_init() function initializes a pthread mutex. It receives a pointer to a pthread_mutex_t type and a pointer to the attributes in mutexattr. For default attributes NULL can be used for mutexattr. If a mutex should be destroyed the pthread_mutex_destroy() function can be used.

pthread_mutex_t mutex;
errno = pthread_mutex_init(&mutex, NULL);
if (errno != 0) {
    perror("pthread_mutex_init");
    exit(EXIT_FAILURE);
}

Parameters

mutex	mutex to be initialized
mutexattr	attributes for `mutex` (`NULL` for default)

Return values

0	on success
!=	on error

int pthread_mutex_lock ( pthread_mutex_t * mutex )

The pthread_mutex_lock() function blocks the current thread, until it successfully acquired the mutex in mutex. When this function returns, the thread can safely assume to be the only thread inside of the critical section guarded by mutex.

Parameters

mutex mutex to lock

int pthread_mutex_unlock ( pthread_mutex_t * mutex )

The pthread_mutex_unlock() function releases the mutex in mutex.

Parameters

mutex mutex to unlock

int pthread_mutex_destroy ( pthread_mutex_t * mutex )

The pthread_mutex_destroy() function destroys the mutex in mutex. After this function returns, pthread_mutex_lock() and pthread_mutex_unlock() must not be called with this mutex as argument anymore.

Parameters

mutex mutex to destroy

Linux libc-doc

Files

Functions

Detailed Description

Function Documentation