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 "February 17, 2023" 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. 33Each instance of a properly initialized 34.Ft once_flag 35can be passed to the 36.Ft call_once 37function; however, only a single caller will successfully execute the 38specified function, 39.Fa func . 40This ensures that the argument 41.Fa func 42is called only once. 43Note, the argument 44.Fa once 45is the only thing used as a point of synchronization. 46If multiple callers use the same pointer for 47.Fa once , 48but use different values for 49.Fa func , 50then only one of the functions will be successfully called. 51.Pp 52The argument 53.Fn once 54should always be initialized to the symbol 55.Sy ONCE_FLAG_INIT 56before calling 57.Fn call_once . 58Failure to do so will result in undefined behavior. 59.Pp 60Like 61.Xr pthread_once 3C , 62the 63.Fn call_once 64function is not itself a cancellation point; however, if the thread 65calling 66.Fn func 67encounters a cancellation point and is cancelled, then the value pointed 68to by 69.Fa once 70will be as though 71.Fn call_once 72had not been called, as 73.Fn func 74had not completed successfully. 75.Sh RETURN VALUES 76The 77.Fn call_once 78function does not return any values. 79Upon its completion, it is guaranteed that 80.Fa func 81will have been called at most once across the liftime of the 82.Fa once 83argument . 84.Sh INTERFACE STABILITY 85.Sy Standard 86.Sh MT-LEVEL 87.Sy MT-Safe 88.Sh SEE ALSO 89.Xr pthread_once 3C , 90.Xr threads.h 3HEAD , 91.Xr attributes 7 , 92.Xr threads 7 93