PTHREAD_ONCE(3) | Library Functions Manual | PTHREAD_ONCE(3)

# NAME

`pthread_once` — dynamic package initialization

# SYNOPSIS

POSIX Threads Library (libpthread, -lpthread)
`#include <pthread.h>`

pthread_once_t once_control = `PTHREAD_ONCE_INIT`;

int
`pthread_once`(pthread_once_t *once_control, void (*init_routine)(void));

# DESCRIPTION

The first call to `pthread_once`() by any thread in a process, with a given once_control, will call the `init_routine`() with no arguments. Subsequent calls to `pthread_once`() with the same once_control will not call the `init_routine`(). On return from `pthread_once`(), it is guaranteed that `init_routine`() has completed. The once_control parameter is used to determine whether the associated initialization routine has been called.

The function `pthread_once`() is not a cancellation point. However, if `init_routine`() is a cancellation point and is cancelled, the effect on once_control is as if `pthread_once`() was never called.

The constant `PTHREAD_ONCE_INIT` is defined in the header file `<pthread.h>`.

The behavior of `pthread_once`() is undefined if once_control has automatic storage duration or is not initialized by `PTHREAD_ONCE_INIT`.

# RETURN VALUES

If successful, the `pthread_once`() function will return zero. Otherwise an error number will be returned to indicate the error.

# ERRORS

None.

# STANDARDS

`pthread_once`() conforms to ISO/IEC 9945-1:1996 (“POSIX.1”).

June 7, 2025 | Debian