1.\" Copyright (c) 1996 John Birrell <jb@cimlogic.com.au>. 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by John Birrell. 15.\" 4. Neither the name of the author nor the names of any co-contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.Dd April 4, 1996 32.Dt PTHREAD_ONCE 3 33.Os BSD 4 34.Sh NAME 35.Nm pthread_once 36.Nd dynamic package initialization 37.Sh SYNOPSIS 38.Fd #include <pthread.h> 39.Pp 40pthread_once 41.Fa once_control 42= PTHREAD_ONCE_INIT; 43.Ft int 44.Fn pthread_once "pthread_once_t *once_control" "void *(*init_routine)(void)" 45.Sh DESCRIPTION 46The first call to 47.Fn pthread_once 48by any thread in a process, with a given 49.Fa once_control , 50will call the 51.Fn init_routine 52with no arguments. Subsequent calls to 53.Fn pthread_once 54with the same 55.Fa once_control 56will not call the 57.Fn init_routine . 58On return from 59.Fn pthread_once , 60it is guaranteed that 61.Fn init_routine 62has completed. The 63.Fa once_control 64parameter is used to determine whether the associated initialization 65routine has been called. 66.Pp 67The function 68.Fn pthread_once 69is not a cancellation point. However, if 70.Fn init_routine 71is a cancellation point and is cancelled, the effect on 72.Fa once_control is as if 73.Fn pthread_once 74was never called. 75.Pp 76The constant 77.Fa PTHREAD_ONCE_INIT 78is defined by header 79.Aq Pa pthread.h . 80.Pp 81The behavior of 82.Fn pthread_once 83is undefined if 84.Fa once_control 85has automatic storage duration or is not initialized by 86.Fa PTHREAD_ONCE_INIT . 87.Pp 88.Sh RETURN VALUES 89If successful, the 90.Fn pthread_once 91function will return zero. Otherwise an error number will be returned to 92indicate the error. 93.Sh ERRORS 94None. 95.Pp 96.Sh STANDARDS 97.Fn pthread_once 98is expected to conform to IEEE 99.Pq Dq Tn POSIX 100Std 1003.1c when it is published. 101