--------------------------------------------------------------------------------
AIX Version 4.3 Base Operating System and Extensions Technical Reference, Volume
                                       1
--------------------------------------------------------------------------------

pthread_once Subroutine

Purpose

Executes a routine exactly once in a process.

Library

Threads Library (libpthreads.a)

Syntax

#include 

int pthread_once (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

once_block 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.

Implementation Specifics

This subroutine is part of the Base Operating System (BOS) Runtime.

Related Information

The pthread_create subroutine, pthread.h file, PTHREAD_ONCE_INIT macro.

One Time Initializations in AIX Version 4.3 General Programming Concepts: Writing
and Debugging Programs.

Threads Library Quick Reference in AIX Version 4.3 General Programming Concepts:
Writing and Debugging Programs.
--------------------------------------------------------------------------------