pthread_once Subroutine

Purpose

Executes a routine exactly once in a process.

Library

Threads Library (libpthreads.a)

Syntax

#include <pthread.h>

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

pthread_once_t once_control = PTHREAD_ONCE_INIT;

Description

The pthread_once subroutine executes the routine init_routine exactly once in a process. The first call to this subroutine by any thread in the process executes the given routine, without parameters. Any subsequent call will have no effect.

The init_routine routine is typically an initialization routine. Multiple initializations can be handled by multiple instances of pthread_once_t structures. This subroutine is useful when a unique initialization has to be done by one thread among many. It reduces synchronization requirements.

Note: The pthread.h header file must be the first included file of each source file using the threads library. Otherwise, the -D_THREAD_SAFE compilation flag should be used, or the cc_r compiler used. In this case, the flag is automatically set.

Parameters

Item	Description
once_control	Points to a synchronization control structure. This structure has to be initialized by the static initializer macro PTHREAD_ONCE_INIT.
init_routine	Points to the routine to be executed.

Return Values

Upon successful completion, pthread_once returns zero. Otherwise, an error number is returned to indicate the error.

Error Codes

No errors are defined. The pthread_once function will not return an error code of EINTR.