NAME

    pthread_once - Calls an initialization routine executed by
                   one thread, a single time

 SYNOPSIS

     #include <pthread.h>

     int pthread_once( pthread_once_t        *once_block,
                       pthread_initroutine_t init_routine );

 PARAMETERS

     once_block                Address of a record that defines the
                               one-time initialization code.  Each
                               one-time initialization routine must
                               have its own unique pthread_once_t data
                               structure.

     init_routine              Address of a procedure that performs the
                               initialization. This routine is called
                               only once, regardless of the number of
                               times it and its associated once_block
                               are passed to pthread_once().

 DESCRIPTION

 The pthread_once() routine calls an initialization routine executed by
 one thread, a single time. This routine allows you to create your own
 initialization code that is guaranteed to be run only once, even if
 called simultaneously by multiple threads or multiple times in the same
 thread.

 For example, a mutex or a thread-specfic data key must be created
 exactly once. Calling pthread_once() prevents the code that creates a
 mutex or thread-specific data from being called by multiple threads.
 Without this routine, the execution must be serialized so that only one
 thread performs the initialization. Other threads that reach the same
 point in the code are delayed until the first thread is finished.

    ---------------------------- NOTE -------------------------------
    If you specify an init_routine that directly or indirectly results
    in a recursive call to pthread_once() and that specifies the same
    init_routine argument, the recursive call can result in a deadlock.
    ------------------------------------------------------------------

 This routine initializes the control record if it has not been initial-
 ized and then determines if the client one-time initialization routine
 has executed once. If it has not executed, this routine calls the ini-
 tialization routine specified in init_routine. If the client one-time
 initialization code has executed once, this routine returns.

 The pthread_once_t data structure is a record that allows client ini-
 tialization operations to guarantee mutual exclusion of access to the
 initialization routine, and that each initialization routine is executed
 exactly once.

 The client code must declare a variable of type pthread_once_t to use
 the client initialization operations. This variable must be initialized
 using the pthread_once_init macro, as follows:

     static pthread_once_t myOnceBlock = pthread_once_init;

 RETURN VALUES

 If the function fails, errno may be set to one of the following values:

    Return   Error     Description
    __________________________________________
     0                 Successful completion.

    -1      [EINVAL]   Invalid parameter.