1fc2512cfSRobert Mustacchi.\" 2fc2512cfSRobert Mustacchi.\" This file and its contents are supplied under the terms of the 3fc2512cfSRobert Mustacchi.\" Common Development and Distribution License ("CDDL"), version 1.0. 4fc2512cfSRobert Mustacchi.\" You may only use this file in accordance with the terms of version 5fc2512cfSRobert Mustacchi.\" 1.0 of the CDDL. 6fc2512cfSRobert Mustacchi.\" 7fc2512cfSRobert Mustacchi.\" A full copy of the text of the CDDL should have accompanied this 8fc2512cfSRobert Mustacchi.\" source. A copy of the CDDL is also available via the Internet at 9fc2512cfSRobert Mustacchi.\" http://www.illumos.org/license/CDDL. 10fc2512cfSRobert Mustacchi.\" 11fc2512cfSRobert Mustacchi.\" 12fc2512cfSRobert Mustacchi.\" Copyright 2016 Joyent, Inc. 13fc2512cfSRobert Mustacchi.\" 14*4a8d6d7cSPeter Tribble.Dd "February 17, 2023" 15fc2512cfSRobert Mustacchi.Dt CALL_ONCE 3C 16fc2512cfSRobert Mustacchi.Os 17fc2512cfSRobert Mustacchi.Sh NAME 18fc2512cfSRobert Mustacchi.Nm call_once 19fc2512cfSRobert Mustacchi.Nd ensure function is only called once 20fc2512cfSRobert Mustacchi.Sh SYNOPSIS 21fc2512cfSRobert Mustacchi.In treads.h 22fc2512cfSRobert Mustacchi.Vt "once_flag once = ONCE_FLAG_INIT;" 23fc2512cfSRobert Mustacchi.Ft void 24fc2512cfSRobert Mustacchi.Fo call_once 25fc2512cfSRobert Mustacchi.Fa "once_flag *once" 26fc2512cfSRobert Mustacchi.Fa "void (*func)(void)" 27fc2512cfSRobert Mustacchi.Fc 28fc2512cfSRobert Mustacchi.Sh DESCRIPTION 29fc2512cfSRobert MustacchiThe 30fc2512cfSRobert Mustacchi.Fn call_once 31fc2512cfSRobert Mustacchifunction is used to ensure that an operation occurs only once, even 3272d3dbb9SYuri Pankovacross multiple threads. 3372d3dbb9SYuri PankovEach instance of a properly initialized 34fc2512cfSRobert Mustacchi.Ft once_flag 35*4a8d6d7cSPeter Tribblecan be passed to the 36fc2512cfSRobert Mustacchi.Ft call_once 37fc2512cfSRobert Mustacchifunction; however, only a single caller will successfully execute the 38fc2512cfSRobert Mustacchispecified function, 39fc2512cfSRobert Mustacchi.Fa func . 40fc2512cfSRobert MustacchiThis ensures that the argument 41fc2512cfSRobert Mustacchi.Fa func 4272d3dbb9SYuri Pankovis called only once. 4372d3dbb9SYuri PankovNote, the argument 44fc2512cfSRobert Mustacchi.Fa once 4572d3dbb9SYuri Pankovis the only thing used as a point of synchronization. 4672d3dbb9SYuri PankovIf multiple callers use the same pointer for 47fc2512cfSRobert Mustacchi.Fa once , 48fc2512cfSRobert Mustacchibut use different values for 49fc2512cfSRobert Mustacchi.Fa func , 50fc2512cfSRobert Mustacchithen only one of the functions will be successfully called. 51fc2512cfSRobert Mustacchi.Pp 52fc2512cfSRobert MustacchiThe argument 53fc2512cfSRobert Mustacchi.Fn once 54fc2512cfSRobert Mustacchishould always be initialized to the symbol 55fc2512cfSRobert Mustacchi.Sy ONCE_FLAG_INIT 56fc2512cfSRobert Mustacchibefore calling 57fc2512cfSRobert Mustacchi.Fn call_once . 58fc2512cfSRobert MustacchiFailure to do so will result in undefined behavior. 59fc2512cfSRobert Mustacchi.Pp 60fc2512cfSRobert MustacchiLike 61fc2512cfSRobert Mustacchi.Xr pthread_once 3C , 62fc2512cfSRobert Mustacchithe 63fc2512cfSRobert Mustacchi.Fn call_once 64fc2512cfSRobert Mustacchifunction is not itself a cancellation point; however, if the thread 65fc2512cfSRobert Mustacchicalling 66fc2512cfSRobert Mustacchi.Fn func 67fc2512cfSRobert Mustacchiencounters a cancellation point and is cancelled, then the value pointed 68fc2512cfSRobert Mustacchito by 69fc2512cfSRobert Mustacchi.Fa once 70fc2512cfSRobert Mustacchiwill be as though 71fc2512cfSRobert Mustacchi.Fn call_once 72fc2512cfSRobert Mustacchihad not been called, as 73fc2512cfSRobert Mustacchi.Fn func 74fc2512cfSRobert Mustacchihad not completed successfully. 75fc2512cfSRobert Mustacchi.Sh RETURN VALUES 76fc2512cfSRobert MustacchiThe 77fc2512cfSRobert Mustacchi.Fn call_once 7872d3dbb9SYuri Pankovfunction does not return any values. 7972d3dbb9SYuri PankovUpon its completion, it is guaranteed that 80fc2512cfSRobert Mustacchi.Fa func 81fc2512cfSRobert Mustacchiwill have been called at most once across the liftime of the 82fc2512cfSRobert Mustacchi.Fa once 83fc2512cfSRobert Mustacchiargument . 84fc2512cfSRobert Mustacchi.Sh INTERFACE STABILITY 85fc2512cfSRobert Mustacchi.Sy Standard 86fc2512cfSRobert Mustacchi.Sh MT-LEVEL 87fc2512cfSRobert Mustacchi.Sy MT-Safe 88fc2512cfSRobert Mustacchi.Sh SEE ALSO 89fc2512cfSRobert Mustacchi.Xr pthread_once 3C , 90fc2512cfSRobert Mustacchi.Xr threads.h 3HEAD , 91bbf21555SRichard Lowe.Xr attributes 7 , 92bbf21555SRichard Lowe.Xr threads 7 93