1.\" 2.\" This file and its contents are supplied under the terms of the 3.\" Common Development and Distribution License ("CDDL"), version 1.0. 4.\" You may only use this file in accordance with the terms of version 5.\" 1.0 of the CDDL. 6.\" 7.\" A full copy of the text of the CDDL should have accompanied this 8.\" source. A copy of the CDDL is also available via the Internet at 9.\" http://www.illumos.org/license/CDDL. 10.\" 11.\" 12.\" Copyright 2016 Joyent, Inc. 13.\" 14.Dd "Jan 11, 2015" 15.Dt CALL_ONCE 3C 16.Os 17.Sh NAME 18.Nm call_once 19.Nd ensure function is only called once 20.Sh SYNOPSIS 21.In treads.h 22.Vt "once_flag once = ONCE_FLAG_INIT;" 23.Ft void 24.Fo call_once 25.Fa "once_flag *once" 26.Fa "void (*func)(void)" 27.Fc 28.Sh DESCRIPTION 29The 30.Fn call_once 31function is used to ensure that an operation occurs only once, even 32across multiple threads. Each instance of a properly initialized 33.Ft once_flag 34can be pased to the 35.Ft call_once 36function; however, only a single caller will successfully execute the 37specified function, 38.Fa func . 39This ensures that the argument 40.Fa func 41is called only once. Note, the argument 42.Fa once 43is the only thing used as a point of synchronization. If multiple 44callers use the same pointer for 45.Fa once , 46but use different values for 47.Fa func , 48then only one of the functions will be successfully called. 49.Pp 50The argument 51.Fn once 52should always be initialized to the symbol 53.Sy ONCE_FLAG_INIT 54before calling 55.Fn call_once . 56Failure to do so will result in undefined behavior. 57.Pp 58Like 59.Xr pthread_once 3C , 60the 61.Fn call_once 62function is not itself a cancellation point; however, if the thread 63calling 64.Fn func 65encounters a cancellation point and is cancelled, then the value pointed 66to by 67.Fa once 68will be as though 69.Fn call_once 70had not been called, as 71.Fn func 72had not completed successfully. 73.Sh RETURN VALUES 74The 75.Fn call_once 76function does not return any values. Upon its completion, it is guaranteed that 77.Fa func 78will have been called at most once across the liftime of the 79.Fa once 80argument . 81.Sh INTERFACE STABILITY 82.Sy Standard 83.Sh MT-LEVEL 84.Sy MT-Safe 85.Sh SEE ALSO 86.Xr pthread_once 3C , 87.Xr threads.h 3HEAD , 88.Xr attributes 5 , 89.Xr threads 5 90