| Samsung Internal API reference 2.0

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

Data Structures | Macros | Typedefs | Enumerations | Functions
Thread support library API

## Data Structures
struct | __pthread_once_t
struct | __pthread_attr_t
struct | __pthread_mutex_t
struct | __pthread_cond_t
struct | __pthread_condattr_t

## Macros
#define | PTHREAD_STACK_MIN (PAGE_SIZE)
#define | PTHREAD_GUARD_MIN (PAGE_SIZE)
#define | PTHREAD_GUARD_MAX (PAGE_SIZE << 2)
#define | MUTEX_STATE_UNLOCKED 0
#define | MUTEX_STATE_LOCKED 1
#define | PTHREAD_MUTEX_INITIALIZER { { MUTEX_STATE_UNLOCKED }, PTHREAD_MUTEX_DEFAULT, 0, 0 }
#define | PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP { { MUTEX_STATE_UNLOCKED }, PTHREAD_MUTEX_ERRORCHECK, 0, 0 }
#define | PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP { { MUTEX_STATE_UNLOCKED }, PTHREAD_MUTEX_RECURSIVE, 0, 0 }
#define | PTHREAD_ONCE_INIT { ATOMIC_INITIALIZER }
#define | PTHREAD_COND_INITIALIZER { ATOMIC_INITIALIZER }
| Object for static initialization of pthread_cond_t variables.
#define | pthread_sigmask(how, set, oldset) sigprocmask(how, set, oldset)
| Set signal mask for specified thread. More...

## Typedefs
typedef struct pthread_impl | pthread_impl_t
typedef uintptr_t | pthread_t
typedef uint32_t | pthread_mutexattr_t
typedef struct __pthread_mutex_t | pthread_mutex_t
typedef unsigned | pthread_key_t
typedef struct __pthread_attr_t | pthread_attr_t
typedef struct __pthread_once_t | pthread_once_t
typedef struct __pthread_cond_t | pthread_cond_t
typedef struct __pthread_cond_t | pthread_condattr_t

## Enumerations
enum | { PTHREAD_MUTEX_NORMAL = 0, PTHREAD_MUTEX_RECURSIVE, PTHREAD_MUTEX_ERRORCHECK, PTHREAD_MUTEX_DEFAULT = PTHREAD_MUTEX_NORMAL, PTHREAD_MUTEX_DESTROYED = -1, PTHREAD_MUTEX_ERRORCHECK_NP = PTHREAD_MUTEX_ERRORCHECK, PTHREAD_MUTEX_RECURSIVE_NP = PTHREAD_MUTEX_RECURSIVE }
| types and states for mutex More...
enum | { PTHREAD_CREATE_JOINABLE, PTHREAD_CREATE_DETACHED }
| detach state attribute settings More...

## Functions
int | pthread_attr_init (pthread_attr_t *attr)
| The pthread_attr_init() function initialize attribute struct. More...
int | pthread_attr_destroy (pthread_attr_t *attr)
| The pthread_attr_destroy() function destroy attribute struct. More...
int | pthread_attr_getstacksize (const pthread_attr_t *attr, size_t *stacksize)
| The pthread_attr_getstacksize() function gets size of stack. More...
int | pthread_attr_getguardsize (const pthread_attr_t *attr, size_t *guardsize)
| The pthread_attr_getguardsize() function gets size of guard. More...
int | pthread_attr_setstacksize (pthread_attr_t *attr, size_t stacksize)
| The pthread_attr_setstacksize() function sets size of stack. More...
int | pthread_attr_setguardsize (pthread_attr_t *attr, size_t guardsize)
| The pthread_attr_setguardsize() function sets size of guard. More...
int | pthread_attr_getstackaddr (const pthread_attr_t *attr, void **stackaddr)
| The pthread_attr_getstackaddr() function gets stack address. More...
int | pthread_attr_setstackaddr (pthread_attr_t *attr, void *stackaddr)
| The pthread_attr_setstackaddr() function gets stack address. More...
int | pthread_attr_getstack (const pthread_attr_t *attr, void **stackaddr, size_t *stacksize)
| The pthread_attr_getstack() function gets stack address and size. More...
int | pthread_attr_setstack (pthread_attr_t *attr, void *stackaddr, size_t stacksize)
| The pthread_attr_setstack() function sets stack address and size. More...
int | pthread_create (pthread_t *thread, const pthread_attr_t *attr, void *(*start_routine)(void *), void *arg)
| The pthread_create() function starts a new thread in the calling process. The new thread starts execution by invoking `start_routine()` `arg` is passed as the sole argument of `start_routine()`. More...
_noreturn_ void | pthread_exit (void *retval)
| Terminate calling thread. More...
int | pthread_join (pthread_t thread, void **retval)
| Wait for the thread specified by `thread` to terminate. If that thread has already terminated, then returns immediately. The thread specified by `thread` must be joinable. More...
int | pthread_once (pthread_once_t *once_control, void(*init_routine)(void))
| If any thread in a process with a `once_control` parameter makes a call to pthread_once(), the first call will summon the `init_routine()`, but subsequent calls will not. The `once_control` parameter determines whether the associated initialization routine has been called. The `init_routine()` is complete upon return of pthread_once(). More...
void * | pthread_getspecific (pthread_key_t key)
| Return the value currently bound to the specified `key` on behalf of the calling thread. More...
int | pthread_setspecific (pthread_key_t key, const void *value)
| Associate a thread-specific `value` with a `key` obtained via a previous call to pthread_key_create(). More...
int | pthread_key_create (pthread_key_t *key, void(*destructor)(void *))
| Create data key for data manipulation functions (pthread_getspecific(), pthread_setspecific()). Multiple threads can call data manipulation functions with the same key. In this case all threads will have separate data. More...
int | pthread_key_delete (pthread_key_t key)
| Delete data key and destructor associated with `key`. After key deletion there is no destructor will be called on thread exits. More...
int | pthread_mutexattr_init (pthread_mutexattr_t *attr)
| Initialize mutex attributes object and initialize attributes with default values. More...
int | pthread_mutexattr_destroy (pthread_mutexattr_t *attr)
| Destroy attributes object and make all attribute values are uninitialized. More...
int | pthread_mutexattr_gettype (const pthread_mutexattr_t *attr, int *type)
| Get mutex type attribute associated with `attr` parameter. More...
int | pthread_mutexattr_settype (pthread_mutexattr_t *attr, int type)
| Set mutex type attribute associated with `attr` parameter. More...
int | pthread_mutex_lock (pthread_mutex_t *mutex)
| Lock mutex or wait while another thread is unlock currently locked mutex. More...
int | pthread_mutex_trylock (pthread_mutex_t *mutex)
| Lock mutex or fail if mutex is already locked. More...
int | pthread_mutex_unlock (pthread_mutex_t *mutex)
| Release lock on currently locked mutex. More...
int | pthread_mutex_destroy (pthread_mutex_t *mutex)
| Destroy mutex object and make all associated data are uninitialized. More...
int | pthread_mutex_init (pthread_mutex_t *mutex, const pthread_mutexattr_t *attr)
| Initialize mutex object `mutex` with attributes given by `attr` parameter. If `attr` parameter is NULL then default attributes will be used. More...
int | pthread_cond_destroy (pthread_cond_t *cond)
| Destroy conditional variable object and make it unitialized. More...
int | pthread_condattr_init (pthread_condattr_t *attr)
| Initialize conditional variable attributes with default values. More...
int | pthread_condattr_destroy (pthread_condattr_t *attr)
| Destroy conditional variable attributes. More...
int | pthread_cond_init (pthread_cond_t *cond, const pthread_condattr_t *attr)
| Initialize conditional variable object `cond` with attributes given by `attr` parameter. More...
int | pthread_cond_signal (pthread_cond_t *cond)
| Unblock at least one of the threads that are blocked on the specified condition variable `cond` (if any threads are blocked on `cond`). More...
int | pthread_cond_broadcast (pthread_cond_t *cond)
| Wake up all threads locked by conditional variable `cond`. More...
int | pthread_cond_wait (pthread_cond_t *cond, pthread_mutex_t *mutex)
| Block on condition variable `cond`, while another thread will unblock this variable by pthread_cond_broadcast() / pthread_cond_signal() call. More...
int | pthread_cond_timedwait (pthread_cond_t *cond, pthread_mutex_t *mutex, const struct timespec *timeout)
| Block on condition variable `cond`, while another thread will unblock this variable by pthread_cond_broadcast() / pthread_cond_signal() call. If timeout reached before condition set then wait will be interrupted and error is returned. More...
pthread_t | pthread_self (void)
| Obtain ID of the calling thread. More...
int | pthread_kill (pthread_t thread, int sig)
| Send signal to specified thread. More...
int | pthread_equal (pthread_t t1, pthread_t t2)
| Compare thread IDs. More...
int | pthread_detach (pthread_t thread)
| Detach a thread. More...
int | pthread_attr_setdetachstate (pthread_attr_t *attr, int detachstate)
| Set the detach state attribute. More...
int | pthread_attr_getdetachstate (const pthread_attr_t *attr, int *detachstate)
| Get the detach state attribute. More...
int | pthread_getattr_np (pthread_t thread, pthread_attr_t *attr)
| Get attributes of created thread. More...

## Detailed Description

## Data Structure Documentation

struct __pthread_once_t

Struct to avoid direct assignment of its single field, which is meant to be threated atomically.

Data Fields
atomic_t | already_executed |

struct __pthread_attr_t

Pthread attibute object type (not implemented yet).

Data Fields
unsigned int | flags |
unsigned int | guardsize |
void * | stackaddr |
unsigned int | stacksize |

struct __pthread_mutex_t

Pthread mutex object type.

Data Fields
unsigned | attr |
pthread_t | caller_thread |
unsigned | count |
atomic_t | state |

struct __pthread_cond_t

Struct to avoid direct assignment of its single field, which is meant to be threated atomically.

Data Fields
atomic_t | status |

struct __pthread_condattr_t

Condition variable attributes type. Not implemented

## Macro Definition Documentation

#define MUTEX_STATE_LOCKED 1

`#include <pthread.h>`

Lock state for mutex.

#define MUTEX_STATE_UNLOCKED 0

`#include <pthread.h>`

Unlock state for mutex.

#define PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP { { MUTEX_STATE_UNLOCKED }, PTHREAD_MUTEX_ERRORCHECK, 0, 0 }

`#include <pthread.h>`

pthread_mutex_t object for static mutex initialization with errorcheck.

#define PTHREAD_GUARD_MAX (PAGE_SIZE << 2)

`#include <pthread.h>`

Maximum stack guard size.

#define PTHREAD_GUARD_MIN (PAGE_SIZE)

`#include <pthread.h>`

Minimum stack guard size.

#define PTHREAD_MUTEX_INITIALIZER { { MUTEX_STATE_UNLOCKED }, PTHREAD_MUTEX_DEFAULT, 0, 0 }

`#include <pthread.h>`

pthread_mutex_t object for static mutex initialization.

#define PTHREAD_ONCE_INIT { ATOMIC_INITIALIZER }

`#include <pthread.h>`

Object for static initialization of pthread_once_t variables.

#define PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP { { MUTEX_STATE_UNLOCKED }, PTHREAD_MUTEX_RECURSIVE, 0, 0 }

`#include <pthread.h>`

pthread_mutex_t object for static recursive mutex initialization.

#define pthread_sigmask | ( |  | how,
|  |  | set,
|  |  | oldset
| ) |  | sigprocmask(how, set, oldset)

`#include <pthread.h>`

Set signal mask for specified thread.

Parameters

  [in] | how | defines how to set mask, must be one of: SIG_BLOCK, SIG_UNBLOCK, SIG_SETMASK
  [in] | set | if not NULL, signals mask to act on, otherwise ignored
  [in] | oldset | if not NULL then here stored previous value of the signal mask

Return values

  0 | On success.
  EINVAL | The value specified by `how` is invalid
  EFAULT | The `set` or `oldset` argument points outside the process's allocated address space

Example:

sigset_t set, oldset;
memset(&set, 0xff, sizeof(set));
int err = pthread_sigmask(SIG_BLOCK, &set, &oldset);
if (!err) {
do_some_work(...);
}

#define PTHREAD_STACK_MIN (PAGE_SIZE)

`#include <pthread.h>`

Minimum stack size.

## Typedef Documentation

pthread_attr_t

`#include <pthread.h>`

Type for pthread attibutes.

pthread_cond_t

`#include <pthread.h>`

Type for pthread conditional variable.

pthread_condattr_t

`#include <pthread.h>`

Type for attibutes of pthread conditional variable.

pthread_impl_t

`#include <pthread.h>`

Internal pthread info representation.

pthread_key_t

`#include <pthread.h>`

Type for unique per-thread keys.

pthread_mutex_t

`#include <pthread.h>`

Pthread mutex type.

pthread_mutexattr_t

`#include <pthread.h>`

Mutex attibute variable.

pthread_once_t

`#include <pthread.h>`

Type for pthreads, created once.

pthread_t

`#include <pthread.h>`

Unique thread identification variable.

## Enumeration Type Documentation

anonymous enum

`#include <pthread.h>`

types and states for mutex

Enumerator
PTHREAD_MUTEX_NORMAL | Regular mutex.
PTHREAD_MUTEX_RECURSIVE | Mutex with the concept of a lock count.
PTHREAD_MUTEX_ERRORCHECK | Mutex with error checking.
PTHREAD_MUTEX_DEFAULT | Regular mutex.
PTHREAD_MUTEX_DESTROYED | Mutex state after pthread_mutex_destroy().
PTHREAD_MUTEX_ERRORCHECK_NP | Same as PTHREAD_MUTEX_ERRORCHECK.
PTHREAD_MUTEX_RECURSIVE_NP | Same as PTHREAD_MUTEX_RECURSIVE.

anonymous enum

`#include <pthread.h>`

detach state attribute settings

Enumerator
PTHREAD_CREATE_JOINABLE | Set thread to be joinable
PTHREAD_CREATE_DETACHED | Set thread to be detached

## Function Documentation

int pthread_attr_destroy | ( | pthread_attr_t * | attr | ) |

`#include <pthread.h>`

The pthread_attr_destroy() function destroy attribute struct.

Parameters

  [in] | attr | is attribute struct.

Return values

  0 | On success.
  EINVAL | Invalid attr address

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

`#include <pthread.h>`

Get the detach state attribute.

Parameters

  [in] | attr | Thread attributes object
  [out] | detachstate | Buffer to return detach state

Return values

  0 | On success

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

`#include <pthread.h>`

The pthread_attr_getguardsize() function gets size of guard.

Parameters

  [in] | attr | is attribute struct.
  [out] | guardsize | is buffer to return size of guard.

Return values

  0 | On success.

int pthread_attr_getstack | ( | const pthread_attr_t * | attr,
|  | void ** | stackaddr,
|  | size_t * | stacksize
| ) |  |

`#include <pthread.h>`

The pthread_attr_getstack() function gets stack address and size.

Parameters

  [in] | attr | is attribute struct.
  [out] | stackaddr | is buffer to save stack address.
  [out] | stacksize | is buffer to save stack size.

Return values

  0 | On success.

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

`#include <pthread.h>`

The pthread_attr_getstackaddr() function gets stack address.

Parameters

  [in] | attr | is attribute struct.
  [out] | stackaddr | is buffer to save stack address.

Return values

  0 | On success.

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

`#include <pthread.h>`

The pthread_attr_getstacksize() function gets size of stack.

Parameters

  [in] | attr | is attribute struct.
  [out] | stacksize | is buffer to return size of stack.

Return values

  0 | On success.

int pthread_attr_init | ( | pthread_attr_t * | attr | ) |

`#include <pthread.h>`

The pthread_attr_init() function initialize attribute struct.

Parameters

  [in] | attr | is attribute struct.

Return values

  0 | On success.
  EINVAL | Invalid attr address

int pthread_attr_setdetachstate | ( | pthread_attr_t * | attr,
|  | int | detachstate
| ) |  |

`#include <pthread.h>`

Set the detach state attribute.

Parameters

  [in] | attr | Thread attributes object
  [in] | detachstate | Detach state to set in attr

Return values

  EINVAL | Invalid value of detachstate
  0 | On success

int pthread_attr_setguardsize | ( | pthread_attr_t * | attr,
|  | size_t | guardsize
| ) |  |

`#include <pthread.h>`

The pthread_attr_setguardsize() function sets size of guard.

Parameters

  [in] | attr | is attribute struct.
  [in] | guardsize | is wished size of guard.

Return values

  0 | On success.
  EINVAL | size is less than DEFAULT_GUARD_SIZE.

int pthread_attr_setstack | ( | pthread_attr_t * | attr,
|  | void * | stackaddr,
|  | size_t | stacksize
| ) |  |

`#include <pthread.h>`

The pthread_attr_setstack() function sets stack address and size.

Parameters

  [in] | attr | is attribute struct.
  [in] | stackaddr | is buffer to save stack address.
  [in] | stacksize | is buffer to save stack size.

Return values

  0 | On success.

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

`#include <pthread.h>`

The pthread_attr_setstackaddr() function gets stack address.

Parameters

  [in] | attr | is attribute struct.
  [in] | stackaddr | is desired stack address.

Return values

  0 | On success.

int pthread_attr_setstacksize | ( | pthread_attr_t * | attr,
|  | size_t | stacksize
| ) |  |

`#include <pthread.h>`

The pthread_attr_setstacksize() function sets size of stack.

Parameters

  [in] | attr | is attribute struct.
  [in] | stacksize | is wished size of stack.

Return values

  0 | On success.
  EINVAL | size is less than PTHREAD_STACK_MIN.

int pthread_cond_broadcast | ( | pthread_cond_t * | cond | ) |

`#include <pthread.h>`

Wake up all threads locked by conditional variable `cond`.

Parameters

  [out] | cond | A pointer to the pthread_cond_t object for which user wants to unblock the threads.

Return values

  0 | If successful.
  EINVAL | The value `cond` does not refer to an initialized condition variable.

Example:

pthread_mutex_t rsrc_lock;
pthread_cond_t rsrc_add;
unsigned int resources;
void get_resources(int amount)
{
pthread_mutex_lock(&rsrc_lock);
while (resources < amount)
pthread_cond_wait(&rsrc_add, &rsrc_lock);
resources -= amount;
pthread_mutex_unlock(&rsrc_lock);
}
void add_resources(int amount)
{
pthread_mutex_lock(&rsrc_lock);
resources += amount;
pthread_cond_broadcast(&rsrc_add);
pthread_mutex_unlock(&rsrc_lock);
}

int pthread_cond_destroy | ( | pthread_cond_t * | cond | ) |

`#include <pthread.h>`

Destroy conditional variable object and make it unitialized.

Parameters

  [out] | cond | A pointer to the pthread_cond_t object that to destroy.

Return values

  0 | On success.
  EBUSY | The implementation has detected an attempt to destroy the object referenced by cond while it is referenced (for example, while being used in a pthread_cond_wait()) by another thread.
  EINVAL | The value specified by `cond` is invalid.

Example:

struct list {
pthread_mutex_t lm;
...
}
struct elt {
key k;
int busy;
pthread_cond_t notbusy;
...
}
delete_elt(struct list *lp, struct elt *ep)
{
pthread_mutex_lock(&lp->lm);
assert(ep->busy);
... remove ep from list ...
ep->busy = 0;
pthread_cond_broadcast(&ep->notbusy);
pthread_mutex_unlock(&lp->lm);
pthread_cond_destroy(&rp->notbusy);
free(ep);
}

int pthread_cond_init | ( | pthread_cond_t * | cond,
|  | const pthread_condattr_t * | attr
| ) |  |

`#include <pthread.h>`

Initialize conditional variable object `cond` with attributes given by `attr` parameter.

Parameters

  [out] | cond | A pointer to the pthread_cond_t object to initialize.
  [in] | attr | NULL, or a pointer to a pthread_condattr_t object that specifies the attributes that you want to use for the `cond`.

Return values

  0 | On success it returns 0.
  EAGAIN | The system lacked the necessary resources (other than memory) to initialise another condition variable.
  ENOMEM | Insufficient memory exists to initialise the condition variable.
  EBUSY | The implementation has detected an attempt to re-initialise the object referenced by `cond`, a previously initialised, but not yet destroyed, condition variable.
  EINVAL | The value specified by `attr` is invalid.

Example:

// initialize a condition variable to its default value
ret = pthread_cond_init(&cv, NULL);

int pthread_cond_signal | ( | pthread_cond_t * | cond | ) |

`#include <pthread.h>`

Unblock at least one of the threads that are blocked on the specified condition variable `cond` (if any threads are blocked on `cond`).

Parameters

  [out] | cond | A pointer to the pthread_cond_t object for which user wants to unblock the threads.

Return values

  0 | If successful.
  EINVAL | The value `cond` does not refer to an initialized condition variable.

Example:

pthread_mutex_t count_lock;
pthread_cond_t count_nonzero;
unsigned count;
void decrement_count()
{
pthread_mutex_lock(&count_lock);
while (count == 0)
pthread_cond_wait(&count_nonzero, &count_lock);
count = count - 1;
pthread_mutex_unlock(&count_lock);
}
void increment_count()
{
pthread_mutex_lock(&count_lock);
if (count == 0)
pthread_cond_signal(&count_nonzero);
count = count + 1;
pthread_mutex_unlock(&count_lock);
}

int pthread_cond_timedwait | ( | pthread_cond_t * | cond,
|  | pthread_mutex_t * | mutex,
|  | const struct timespec * | timeout
| ) |  |

`#include <pthread.h>`

Block on condition variable `cond`, while another thread will unblock this variable by pthread_cond_broadcast() / pthread_cond_signal() call. If timeout reached before condition set then wait will be interrupted and error is returned.

Parameters

  [out] | cond | A pointer to the pthread_cond_t object that user wants the threads to block on.
  [out] | mutex | The mutex that to unlock.
  [out] | timeout | Timeout to wait for condition

Return values

  0 | On success.
  EINVAL | The value specified by `cond` or `mutex` or `timeout` is invalid.
  EINVAL | Different mutexes were supplied for concurrent pthread_cond_wait() operations on the same condition variable.
  EPERM | The mutex was not owned by the current thread at the time of the call.
  ETIMEDOUT | The timeout occured while awaiting for condition

Example:

pthread_mutex_t myMutex;
pthread_cond_t cond;
pthread_attr_t attr;
const struct timespec to = {1, 0};
int cont;
void *anotherFunc(void*)
{
printf("anotherFunc\n");
pthread_mutex_lock(&myMutex);
printf("waiting...\n");
pthread_cond_timedwait(&cond, &myMutex, &to);
cont += 10;
printf("slot\n");
pthread_mutex_unlock(&myMutex);
printf("mutex unlocked anotherFunc\n");
printf("Done anotherFunc\n");
pthread_exit(NULL);
}

int pthread_cond_wait | ( | pthread_cond_t * | cond,
|  | pthread_mutex_t * | mutex
| ) |  |

`#include <pthread.h>`

Block on condition variable `cond`, while another thread will unblock this variable by pthread_cond_broadcast() / pthread_cond_signal() call.

Parameters

  [out] | cond | A pointer to the pthread_cond_t object that user wants the threads to block on.
  [out] | mutex | The mutex that to unlock.

Return values

  0 | On success.
  EINVAL | The value specified by `cond` or `mutex` is invalid.
  EINVAL | Different mutexes were supplied for concurrent pthread_cond_wait() operations on the same condition variable.
  EPERM | The mutex was not owned by the current thread at the time of the call.

Example:

pthread_mutex_t myMutex;
pthread_cond_t cond;
pthread_attr_t attr;
int cont;
void *anotherFunc(void*)
{
printf("anotherFunc\n");
pthread_mutex_lock(&myMutex);
printf("waiting...\n");
pthread_cond_wait(&cond, &myMutex);
cont += 10;
printf("slot\n");
pthread_mutex_unlock(&myMutex);
printf("mutex unlocked anotherFunc\n");
printf("Done anotherFunc\n");
pthread_exit(NULL);
}

int pthread_condattr_destroy | ( | pthread_condattr_t * | attr | ) |

`#include <pthread.h>`

Destroy conditional variable attributes.

Parameters

  [in] | attr | pointer to a pthread_condattr_t object that specifies the attributes that you want to use for the `cond`.

Return values

  0 | On success it returns 0.

int pthread_condattr_init | ( | pthread_condattr_t * | attr | ) |

`#include <pthread.h>`

Initialize conditional variable attributes with default values.

Parameters

  [out] | attr | pointer to a pthread_condattr_t object that specifies the attributes that you want to use for the `cond`.

Return values

  0 | On success it returns 0.

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

`#include <pthread.h>`

The pthread_create() function starts a new thread in the calling process. The new thread starts execution by invoking `start_routine()` `arg` is passed as the sole argument of `start_routine()`.

Parameters

  [out] | thread | NULL, or a pointer to a pthread_t object where the function can store the thread ID of the new thread.
  [in] | attr | NULL, a pointer to a pthread_attr_t structure that specifies the attributes of the new thread.
  [in] | start_routine | The routine where the thread begins, with `arg` as its only argument.
  [in] | arg | single parameter of `start_routine()` function.

Return values

  0 | On success.
  EAGAIN | The system lacked the necessary resources to create another thread, or the system-imposed limit on the total number of threads in a process would be exceeded.
  EPERM | The caller does not have appropriate permission to set the required scheduling parameters or scheduling policy.
  EINVAL | The attributes specified by `attr` are invalid.

Example:

void *foo(void *i) {
int a = *((int *) i);
free(i);
}
int main()
{
pthread_t thread;
int *arg = malloc(sizeof(*arg));
*arg = 10;
pthread_create(&thread, 0, foo, arg);
return 0;
}

int pthread_detach | ( | pthread_t | thread | ) |

`#include <pthread.h>`

Detach a thread.

Parameters

  [in] | thread | Thread to detach

Return values

  0 | On success
  EINVAL | if thread is not a joinable thread
  ESRCH | if no thread with the ID thread could be found

int pthread_equal | ( | pthread_t | t1,
|  | pthread_t | t2
| ) |  |

`#include <pthread.h>`

Compare thread IDs.

Parameters

  [in] | t1 | Thread 1 id
  [in] | t2 | Thread 2 id

Return values

  Nonzero | if two thread IDs are equal
  0 | if two thread IDs are not equal

Example:

int res = pthread_equal(t1, t2);
if (res) {
do_some_work(...);
}

_noreturn_ void pthread_exit | ( | void * | retval | ) |

`#include <pthread.h>`

Terminate calling thread.

Parameters

  [in] | retval | value which will be available by `pthread_join`.

int pthread_getattr_np | ( | pthread_t | thread,
|  | pthread_attr_t * | attr
| ) |  |

`#include <pthread.h>`

Get attributes of created thread.

Parameters

  [in] | thread | thread to get attributtes from
  [out] | attr | Buffer to return thread attributes

Return values

  0 | On success

void* pthread_getspecific | ( | pthread_key_t | key | ) |

`#include <pthread.h>`

Return the value currently bound to the specified `key` on behalf of the calling thread.

Parameters

  [in] | key | The key associated with the data that user wants to get.

Returns
  Pointer to the data value, or NULL.

Example:

pthread_key_t buffer_key;
void buffer_key_destruct( void *value )
{
free( value );
pthread_setspecific( buffer_key, NULL );
}
char *lookup( void )
{
char *string;
string = (char *)pthread_getspecific( buffer_key );
if( string == NULL ) {
string = (char *) malloc( 32 );
sprintf( string, "This is thread %d\n", pthread_self() );
pthread_setspecific( buffer_key, (void *)string );
}
return( string );
}
void *function( void *arg )
{
while( 1 ) {
puts( lookup() );
}
return( 0 );
}
int main( void )
{
pthread_key_create( &buffer_key,
&buffer_key_destruct );
pthread_create( NULL, NULL, &function, NULL );
// Let the threads run for 60 seconds
sleep( 60 );
return EXIT_SUCCESS;
}

int pthread_join | ( | pthread_t | thread,
|  | void ** | retval
| ) |  |

`#include <pthread.h>`

Wait for the thread specified by `thread` to terminate. If that thread has already terminated, then returns immediately. The thread specified by `thread` must be joinable.

Parameters

  [in] | thread | Target thread which termination is waited.
  [out] | retval | NULL, or a double pointer to a location where the function can store the value passed to pthread_exit() by the target thread.

Return values

  0 | If successful.
  EINVAL | The implementation has detected that the value specified by `thread` does not refer to a joinable thread.
  ESRCH | No thread could be found corresponding to that specified by the given thread ID.
  EDEADLK | A deadlock was detected or the value of `thread` specifies the calling thread.

Example:

void* thread_function(void)
{
char *a = malloc(10);
strcpy(a,"hello world");
pthread_exit((void*)a);
}
int main()
{
pthread_t thread_id;
char *b;
pthread_create (&thread_id, NULL,&thread_function, NULL);
pthread_join(thread_id,(void**)&b);
printf("b is %s",b);
}

int pthread_key_create | ( | pthread_key_t * | key,
|  | void(*)(void *) | destructor
| ) |  |

`#include <pthread.h>`

Create data key for data manipulation functions (pthread_getspecific(), pthread_setspecific()). Multiple threads can call data manipulation functions with the same key. In this case all threads will have separate data.

Parameters

  [out] | key | A pointer to a pthread_key_t object where the function can store the new key.
  [in] | destructor | (optional) pointer to function to be called when you destroy the key.

Return values

  0 | On success.
  EINVAL | The key value is invalid.

Example:

pthread_key_t buffer_key;
void buffer_key_destruct( void *value )
{
free( value );
pthread_setspecific( buffer_key, NULL );
}
char *lookup( void )
{
char *string;
string = (char *)pthread_getspecific( buffer_key );
if( string == NULL ) {
string = (char *) malloc( 32 );
sprintf( string, "This is thread %d\n", pthread_self() );
pthread_setspecific( buffer_key, (void *)string );
}
return( string );
}
void *function( void *arg )
{
while( 1 ) {
puts( lookup() );
}
return( 0 );
}
int main( void )
{
pthread_key_create( &buffer_key,
&buffer_key_destruct );
pthread_create( NULL, NULL, &function, NULL );
// Let the threads run for 60 seconds
sleep( 60 );
return EXIT_SUCCESS;
}

int pthread_key_delete | ( | pthread_key_t | key | ) |

`#include <pthread.h>`

Delete data key and destructor associated with `key`. After key deletion there is no destructor will be called on thread exits.

Parameters

  [in] | key | The key, created by calling pthread_key_create() to delete.

Return values

  0 | On success.
  EAGAIN | The system lacked the necessary resources to create another thread-specific data key, or the system-imposed limit on the total number of keys per process { PTHREAD_KEYS_MAX } has been exceeded.
  ENOMEM | Insufficient memory exists to create the key.

Example:

pthread_key_t buffer_key;
void buffer_key_destruct( void *value )
{
free( value );
pthread_setspecific( buffer_key, NULL );
}
char *lookup( void )
{
char *string;
string = (char *)pthread_getspecific( buffer_key );
if( string == NULL ) {
string = (char *) malloc( 32 );
sprintf( string, "This is thread %d\n", pthread_self() );
pthread_setspecific( buffer_key, (void *)string );
}
return( string );
}
void *function( void *arg )
{
while( 1 ) {
puts( lookup() );
}
return( 0 );
}
int main( void )
{
pthread_key_create( &buffer_key,
&buffer_key_destruct );
pthread_key_delete(buffer_key);
return EXIT_SUCCESS;
}

int pthread_kill | ( | pthread_t | thread,
|  | int | sig
| ) |  |

`#include <pthread.h>`

Send signal to specified thread.

Parameters

  [in] | thread | thread to send signal
  [in] | sig | signal id to send

Return values

  0 | On success.
  EINVAL | The value specified by `sig` not a valid signal identifier
  EPERM | The signal id specified by `sig` is not allowed to send from unprivileged task
  ESRCH | Specified thread not found

Example:

int err = pthread_kill(thread, sig);
if (!err) {
do_some_work(...);
}

int pthread_mutex_destroy | ( | pthread_mutex_t * | mutex | ) |

`#include <pthread.h>`

Destroy mutex object and make all associated data are uninitialized.

Parameters

  [out] | mutex | A pointer to the pthread_mutex_t object to destroy.

Return values

  0 | On success.
  EBUSY | The implementation has detected an attempt to destroy the object referenced by `mutex` while it is locked or referenced (for example, while being used in a pthread_cond_wait()) by another thread.
  EINVAL | The value specified by `mutex` is invalid.

Example:

pthread_mutex_t demoMutex;
pthread_mutex_trylock(&demoMutex);
pthread_t writeToFile = pthread_self ();
unsigned short iterate;
for (iterate = 0; iterate < 10000; iterate++) {
fprintf (fp, " %d ", iterate, 4);
fprintf (fp, " %lu ", writeToFile, sizeof (pthread_t));
fprintf (fp, "\n", writeToFile, 1);
}
pthread_mutex_unlock (&demoMutex);
pthread_mutex_destroy (&demoMutex);
pthread_exit (NULL);

int pthread_mutex_init | ( | pthread_mutex_t * | mutex,
|  | const pthread_mutexattr_t * | attr
| ) |  |

`#include <pthread.h>`

Initialize mutex object `mutex` with attributes given by `attr` parameter. If `attr` parameter is NULL then default attributes will be used.

Parameters

  [out] | mutex | A pointer to the pthread_mutex_t object to initialize.
  [in] | attr | NULL, or a pointer to a pthread_mutexattr_t object that specifies the attributes that you want to use for the mutex.

Return values

  0 | On success.
  EAGAIN | The system lacked the necessary resources (other than memory) to initialise another mutex.
  ENOMEM | Insufficient memory exists to initialise the mutex.
  EPERM | The caller does not have the privilege to perform the operation
  EBUSY | The implementation has detected an attempt to re-initialise the object referenced by `mutex`, a previously initialised, but not yet destroyed, mutex.
  EINVAL | The value specified by `attr` is invalid.

Example:

pthread_mutex_t demoMutex;
pthread_mutex_init(&Mutex, &Attr);
pthread_mutex_trylock(&demoMutex);
pthread_t writeToFile = pthread_self ();
unsigned short iterate;
for (iterate = 0; iterate < 10000; iterate++) {
fprintf (fp, " %d ", iterate, 4);
fprintf (fp, " %lu ", writeToFile, sizeof (pthread_t));
fprintf (fp, "\n", writeToFile, 1);
}
pthread_mutex_unlock (&demoMutex);
pthread_exit (NULL);

int pthread_mutex_lock | ( | pthread_mutex_t * | mutex | ) |

`#include <pthread.h>`

Lock mutex or wait while another thread is unlock currently locked mutex.

Parameters

  [out] | mutex | A pointer to the pthread_mutex_t object to lock.

Return values

  0 | On success.
  EINVAL | The value specified by `mutex` does not refer to an initialized mutex object.
  EAGAIN | The mutex could not be acquired because the maximum number of recursive locks for mutex has been exceeded.
  EDEADLK | The current thread already owns the mutex.

Example:

pthread_mutex_t count_mutex;
long long count;
void increment_count()
{
pthread_mutex_lock(&count_mutex);
count = count + 1;
pthread_mutex_unlock(&count_mutex);
}

int pthread_mutex_trylock | ( | pthread_mutex_t * | mutex | ) |

`#include <pthread.h>`

Lock mutex or fail if mutex is already locked.

Parameters

  [out] | mutex | A pointer to the pthread_mutex_t object to lock.

Return values

  0 | On success.
  EBUSY | The mutex could not be acquired because it was already locked.
  EINVAL | The value specified by `mutex` does not refer to an initialized mutex object.
  EAGAIN | The mutex could not be acquired because the maximum number of recursive locks for mutex has been exceeded.

Example:

pthread_mutex_t demoMutex;
pthread_mutex_trylock(&demoMutex);
pthread_t writeToFile = pthread_self ();
unsigned short iterate;
for (iterate = 0; iterate < 10000; iterate++) {
fprintf (fp, " %d ", iterate, 4);
fprintf (fp, " %lu ", writeToFile, sizeof (pthread_t));
fprintf (fp, "\n", writeToFile, 1);
}
pthread_mutex_unlock (&demoMutex);
pthread_exit (NULL);

int pthread_mutex_unlock | ( | pthread_mutex_t * | mutex | ) |

`#include <pthread.h>`

Release lock on currently locked mutex.

Parameters

  [out] | mutex | A pointer to the pthread_mutex_t object to unlock.

Return values

  0 | On success.
  EPERM | The current thread does not own the mutex.

Example:

pthread_mutex_t demoMutex;
pthread_mutex_trylock(&demoMutex);
pthread_t writeToFile = pthread_self ();
unsigned short iterate;
for (iterate = 0; iterate < 10000; iterate++) {
fprintf (fp, " %d ", iterate, 4);
fprintf (fp, " %lu ", writeToFile, sizeof (pthread_t));
fprintf (fp, "\n", writeToFile, 1);
}
pthread_mutex_unlock (&demoMutex);
pthread_exit (NULL);

int pthread_mutexattr_destroy | ( | pthread_mutexattr_t * | attr | ) |

`#include <pthread.h>`

Destroy attributes object and make all attribute values are uninitialized.

Parameters

  [in] | attr | A pointer to the pthread_mutexattr_t object that user wants to get the attribute from.

Return values

  0 | On success.
  EINVAL | The value specified by `attr` is invalid.

Example:

pthread_mutex_t mutex;
int main(int argc, char **argv)
{
int rc = 0;
pthread_mutexattr_t mta;
printf("Create a default mutex attribute\n");
rc = pthread_mutexattr_init(&mta);
printf("Create the mutex using a mutex attributes object\n");
rc = pthread_mutex_init(&mutex, &mta);
printf("Destroy mutex attribute\n");
rc = pthread_mutexattr_destroy(&mta);
printf("Destroy mutex\n");
rc = pthread_mutex_destroy(&mutex);
return 0;
}

int pthread_mutexattr_gettype | ( | const pthread_mutexattr_t * | attr,
|  | int * | type
| ) |  |

`#include <pthread.h>`

Get mutex type attribute associated with `attr` parameter.

Parameters

  [in] | attr | A pointer to the pthread_mutexattr_t object to get the attribute from.
  [out] | type | A pointer to location where the function can store the type.

Return values

  0 | On success.
  EINVAL | The value specified by `attr` is invalid.

Example:

pthread_mutex_t Mutex;
int type;
pthread_mutexattr_t Attr;
pthread_mutexattr_init(&Attr);
pthread_mutexattr_settype(&Attr, PTHREAD_MUTEX_RECURSIVE);
pthread_mutexattr_gettype(&Attr, &type);
pthread_mutex_init(&Mutex, &Attr);

int pthread_mutexattr_init | ( | pthread_mutexattr_t * | attr | ) |

`#include <pthread.h>`

Initialize mutex attributes object and initialize attributes with default values.

Parameters

  [in] | attr | A pointer to the pthread_mutexattr_t object to initialize.

Return values

  0 | On success.
  ENOMEM | Insufficient memory exists to initialize the mutex attributes object.

Example:

pthread_mutex_t mutex;
int main(int argc, char **argv)
{
int rc = 0;
pthread_mutexattr_t mta;
printf("Create a default mutex attribute\n");
rc = pthread_mutexattr_init(&mta);
printf("Create the mutex using a mutex attributes object\n");
rc = pthread_mutex_init(&mutex, &mta);
printf("Destroy mutex attribute\n");
rc = pthread_mutexattr_destroy(&mta);
printf("Destroy mutex\n");
rc = pthread_mutex_destroy(&mutex);
return 0;
}

int pthread_mutexattr_settype | ( | pthread_mutexattr_t * | attr,
|  | int | type
| ) |  |

`#include <pthread.h>`

Set mutex type attribute associated with `attr` parameter.

Parameters

  [out] | attr | A pointer to the pthread_mutexattr_t object to set the attribute in.
  [in] | type | Parameter type can be one of the following values: PTHREAD_MUTEX_NORMAL - does not detect deadlocks. PTHREAD_MUTEX_ERRORCHECK - lock function tries to lock already locked function will fail with error. PTHREAD_MUTEX_RECURSIVE - allow lock already locked mutex by the same thread. PTHREAD_MUTEX_DEFAULT - equal to PTHREAD_MUTEX_NORMAL.

Return values

  0 | On success.
  EINVAL | The value `type` is invalid.
  EINVAL | The value specified by `attr` is invalid.

Example:

pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER;
pthread_mutexattr_t mta;
pthread_mutexattr_init(&mta);
pthread_mutexattr_settype(&mta, PTHREAD_MUTEX_RECURSIVE);
pthread_mutex_init(&mutex, &mta);

int pthread_once | ( | pthread_once_t * | once_control,
|  | void(*)(void) | init_routine
| ) |  |

`#include <pthread.h>`

If any thread in a process with a `once_control` parameter makes a call to pthread_once(), the first call will summon the `init_routine()`, but subsequent calls will not. The `once_control` parameter determines whether the associated initialization routine has been called. The `init_routine()` is complete upon return of pthread_once().

Parameters

  [out] | once_control | A pointer to a pthread_once_t object that the function uses to determine whether or not to run the initialization code.
  [in] | init_routine | The function that new thread will run.

Return values

  0 | Upon successful completion.
  EINVAL | The implementation has detected that the value specified by `thread` does not refer to a joinable thread.
  ESRCH | No thread could be found corresponding to that specified by the given thread ID.
  EDEADLK | A deadlock was detected or the value of `thread` specifies the calling thread.

Example:

pthread_once_t once_control = PTHREAD_ONCE_INIT;
void library_init( void )
{
// initialize the library
}
void library_entry_point1( void )
{
pthread_once( &once_control, library_init );
// do stuff for library_entry_point1...
}
void library_entry_point2( void )
{
pthread_once( &once_control, library_init );
// do stuff for library_entry_point1...
}

pthread_t pthread_self | ( | void |  | ) |

`#include <pthread.h>`

Obtain ID of the calling thread.

Returns
  the ID of the calling thread.

Example:

pthread_t id = pthread_self();
if (id == wanted_id) {
...
}

int pthread_setspecific | ( | pthread_key_t | key,
|  | const void * | value
| ) |  |

`#include <pthread.h>`

Associate a thread-specific `value` with a `key` obtained via a previous call to pthread_key_create().

Parameters

  [out] | key | The key associated with the data to set.
  [in] | value | Pointer to buffer where to store value.

Return values

  0 | If successful.
  ENOMEM | Insufficient memory to store threads specific data value.
  EINVAL | Invalid thread specific data key.

Example:

pthread_key_t buffer_key;
void buffer_key_destruct( void *value )
{
free( value );
pthread_setspecific( buffer_key, NULL );
}
char *lookup( void )
{
char *string;
string = (char *)pthread_getspecific( buffer_key );
if( string == NULL ) {
string = (char *) malloc( 32 );
sprintf( string, "This is thread %d\n", pthread_self() );
pthread_setspecific( buffer_key, (void *)string );
}
return( string );
}
void *function( void *arg )
{
while( 1 ) {
puts( lookup() );
}
return( 0 );
}
int main( void )
{
pthread_key_create( &buffer_key,
&buffer_key_destruct );
pthread_create( NULL, NULL, &function, NULL );
// Let the threads run for 60 seconds
sleep( 60 );
return EXIT_SUCCESS;
}