CALL_ONCE(3C) Standard C Library Functions CALL_ONCE(3C)

NAME

call_once - ensure function is only called once

SYNOPSIS

#include <threads.h>

once_flag once = ONCE_FLAG_INIT;

void
call_once(once_flag *once, void (*func)(void));

DESCRIPTION

The call_once() function is used to ensure that an operation occurs
only once, even across multiple threads. Each instance of a properly
initialized once_flag can be passed to the call_once function; however,
only a single caller will successfully execute the specified function,
func. This ensures that the argument func is called only once. Note,
the argument once is the only thing used as a point of synchronization.
If multiple callers use the same pointer for once, but use different
values for func, then only one of the functions will be successfully
called.

The argument once should always be initialized to the symbol
ONCE_FLAG_INIT before calling call_once(). Failure to do so will
result in undefined behavior.

Like pthread_once(3C), the call_once() function is not itself a
cancellation point; however, if the thread calling func() encounters a
cancellation point and is cancelled, then the value pointed to by once
will be as though call_once() had not been called, as func() had not
completed successfully.

RETURN VALUES

The call_once() function does not return any values. Upon its
completion, it is guaranteed that func will have been called at most
once across the liftime of the once argument .

INTERFACE STABILITY

Standard

MT-LEVEL
MT-Safe

SEE ALSO

pthread_once(3C), threads.h(3HEAD), attributes(7), threads(7)

illumos February 17, 2023 illumos