pthread_once(3) 					     Library Functions Manual						   pthread_once(3)

NAME

       pthread_once - Calls a routine to be executed by a single thread, once.

LIBRARY

       DECthreads POSIX 1003.1c Library (libpthread.so)

SYNOPSIS

       #include <pthread.h>

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

STANDARDS

       Interfaces documented on this reference page conform to industry standards as follows:

       IEEE Std 1003.1c-1995, POSIX System Application Program Interface

PARAMETERS

       Address	of  a  record  that controls the one-time execution code.  Each one-time execution routine must have its own unique pthread_once_t
       record.	Address of a procedure to be executed once.  This routine is called only once, regardless of the number of times it and its  asso-
       ciated once_control block are passed to pthread_once(3).

DESCRIPTION

       The  first  call  to  this  routine by any thread in a process with a given once_control will call the specified routine with no arguments.
       Subsequent calls to pthread_once(3) with the same once_control will not call the routine.  On return from pthread_once(3), it is guaranteed
       that the routine has completed.

       For  example, a mutex or a per-thread context key must be created exactly once.	Calling pthread_once(3) ensures that the initialization is
       serialized across multiple threads.  Other threads that reach the same point in the code would be delayed until the first  thread  is  fin-
       ished.

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

       To initialize the once_control record, your program can zero out the entire structure, or you can use the PTHREAD_ONCE_INIT macro, which is
       defined in the pthread.h header file, to statically initialize that structure.  If using PTHREAD_ONCE_INIT, declare the once_control record
       as follows:

       pthread_once_t  once_control = PTHREAD_ONCE_INIT;

       Note that it is often easier to simply lock a statically initialized mutex, check a control flag, and perform necessary initialization (in-
       line) rather than using pthread_once(3).  For example, code an initialization routine that begins with the following basic logic:
	 init()
	 {
	  static pthread_mutex_t    mutex = PTHREAD_MUTEX_INITIALIZER;
	  static int		    flag = FALSE;

	  pthread_mutex_lock(&mutex);
	  if(!flag)
	    {
	     flag = TRUE;
	     /* initialize code */
	    }
	  pthread_mutex_unlock(&mutex);
	 }

RETURN VALUES

       If  an  error  condition occurs, this routine returns an integer indicating the type of error.  Possible return values are as follows: Suc-
       cessful completion.  Invalid argument.

ERRORS

       None

RELATED INFORMATION

       Manuals: Guide to DECthreads and Programmer's Guide

       delim off

																   pthread_once(3)