1*358ede37Sschwarze.\" $OpenBSD: pthread_once.3,v 1.15 2015/09/14 13:08:01 schwarze Exp $ 282d2d131Sfgsch.\" 3a278733dSd.\" Copyright (c) 1996 John Birrell <jb@cimlogic.com.au>. 4a278733dSd.\" All rights reserved. 5a278733dSd.\" 6a278733dSd.\" Redistribution and use in source and binary forms, with or without 7a278733dSd.\" modification, are permitted provided that the following conditions 8a278733dSd.\" are met: 9a278733dSd.\" 1. Redistributions of source code must retain the above copyright 10a278733dSd.\" notice, this list of conditions and the following disclaimer. 11a278733dSd.\" 2. Redistributions in binary form must reproduce the above copyright 12a278733dSd.\" notice, this list of conditions and the following disclaimer in the 13a278733dSd.\" documentation and/or other materials provided with the distribution. 14a278733dSd.\" 3. All advertising materials mentioning features or use of this software 15a278733dSd.\" must display the following acknowledgement: 16a278733dSd.\" This product includes software developed by John Birrell. 17a278733dSd.\" 4. Neither the name of the author nor the names of any co-contributors 18a278733dSd.\" may be used to endorse or promote products derived from this software 19a278733dSd.\" without specific prior written permission. 20a278733dSd.\" 21a278733dSd.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND 22a278733dSd.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 23a278733dSd.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 24a278733dSd.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 25a278733dSd.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 26a278733dSd.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 27a278733dSd.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 28a278733dSd.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 29a278733dSd.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 30a278733dSd.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 31a278733dSd.\" SUCH DAMAGE. 32a278733dSd.\" 3374493c91Sd.\" $FreeBSD: pthread_once.3,v 1.5 1999/08/28 00:03:09 peter Exp $ 3474493c91Sd.\" 35*358ede37Sschwarze.Dd $Mdocdate: September 14 2015 $ 36a278733dSd.Dt PTHREAD_ONCE 3 37c043c0f7Sd.Os 38a278733dSd.Sh NAME 39a278733dSd.Nm pthread_once 40a278733dSd.Nd dynamic package initialization 41a278733dSd.Sh SYNOPSIS 4286f9d4cdStedu.In pthread.h 43*358ede37Sschwarze.Vt pthread_once_t once_control No = Dv PTHREAD_ONCE_INIT ; 44a278733dSd.Ft int 45a278733dSd.Fn pthread_once "pthread_once_t *once_control" "void (*init_routine)(void)" 46a278733dSd.Sh DESCRIPTION 47a278733dSdThe first call to 48a278733dSd.Fn pthread_once 49a278733dSdby any thread in a process, with a given 50a278733dSd.Fa once_control , 51a278733dSdwill call the 52a278733dSd.Fn init_routine 53ee997aeaSmpechwith no arguments. 54ee997aeaSmpechSubsequent calls to 55a278733dSd.Fn pthread_once 56a278733dSdwith the same 57a278733dSd.Fa once_control 58a278733dSdwill not call the 59a278733dSd.Fn init_routine . 60a278733dSdOn return from 61a278733dSd.Fn pthread_once , 62a278733dSdit is guaranteed that 63a278733dSd.Fn init_routine 64ee997aeaSmpechhas completed. 65ee997aeaSmpechThe 66a278733dSd.Fa once_control 67a278733dSdparameter is used to determine whether the associated initialization 68a278733dSdroutine has been called. 69a278733dSd.Pp 70a278733dSdThe function 71a278733dSd.Fn pthread_once 72ee997aeaSmpechis not a cancellation point. 73ee997aeaSmpechHowever, if 74a278733dSd.Fn init_routine 75a278733dSdis a cancellation point and is cancelled, the effect on 76*358ede37Sschwarze.Va once_control 7779ad192cSjmcis as if 78a278733dSd.Fn pthread_once 79a278733dSdwas never called. 80a278733dSd.Pp 81a278733dSdThe constant 8202ecd0d2Saaron.Dv PTHREAD_ONCE_INIT 8379ad192cSjmcis defined in the header file 84369bef3aSschwarze.In pthread.h . 85a278733dSd.Pp 86a278733dSdThe behavior of 87a278733dSd.Fn pthread_once 88a278733dSdis undefined if 89a278733dSd.Fa once_control 90a278733dSdhas automatic storage duration or is not initialized by 9102ecd0d2Saaron.Dv PTHREAD_ONCE_INIT . 92a278733dSd.Sh RETURN VALUES 93a278733dSdIf successful, the 94a278733dSd.Fn pthread_once 95ee997aeaSmpechfunction will return zero. 96ee997aeaSmpechOtherwise an error number will be returned to indicate the error. 97a278733dSd.Sh ERRORS 98a278733dSdNone. 99a278733dSd.Sh STANDARDS 100a278733dSd.Fn pthread_once 10182d2d131Sfgschconforms to 10282d2d131Sfgsch.St -p1003.1-96 . 103