/share/man/man3/pthread_once.3

  1.\" Copyright (c) 1996 John Birrell <jb@cimlogic.com.au>.
  2.\" All rights reserved.
  3.\"
  4.\" Redistribution and use in source and binary forms, with or without
  5.\" modification, are permitted provided that the following conditions
  6.\" are met:
  7.\" 1. Redistributions of source code must retain the above copyright
  8.\"    notice, this list of conditions and the following disclaimer.
  9.\" 2. Redistributions in binary form must reproduce the above copyright
 10.\"    notice, this list of conditions and the following disclaimer in the
 11.\"    documentation and/or other materials provided with the distribution.
 12.\" 3. All advertising materials mentioning features or use of this software
 13.\"    must display the following acknowledgement:
 14.\"	This product includes software developed by John Birrell.
 15.\" 4. Neither the name of the author nor the names of any co-contributors
 16.\"    may be used to endorse or promote products derived from this software
 17.\"    without specific prior written permission.
 18.\"
 19.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND
 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 22.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 29.\" SUCH DAMAGE.
 30.\"
 31.\" $FreeBSD$
 32.\"
 33.Dd April 4, 1996
 34.Dt PTHREAD_ONCE 3
 35.Os
 36.Sh NAME
 37.Nm pthread_once
 38.Nd dynamic package initialization
 39.Sh LIBRARY
 40.Lb libpthread
 41.Sh SYNOPSIS
 42.In pthread.h
 43.Pp
 44pthread_once_t
 45.Fa once_control
 46= PTHREAD_ONCE_INIT;
 47.Ft int
 48.Fn pthread_once "pthread_once_t *once_control" "void (*init_routine)(void)"
 49.Sh DESCRIPTION
 50The first call to
 51.Fn pthread_once
 52by any thread in a process, with a given
 53.Fa once_control ,
 54will call the
 55.Fn init_routine
 56with no arguments.
 57Subsequent calls to
 58.Fn pthread_once
 59with the same
 60.Fa once_control
 61will not call the
 62.Fn init_routine .
 63On return from
 64.Fn pthread_once ,
 65it is guaranteed that
 66.Fn init_routine
 67has completed.
 68The
 69.Fa once_control
 70parameter is used to determine whether the associated initialization
 71routine has been called.
 72.Pp
 73The function
 74.Fn pthread_once
 75is not a cancellation point.
 76However, if
 77.Fn init_routine
 78is a cancellation point and is cancelled, the effect on
 79.Fa once_control
 80is as if
 81.Fn pthread_once
 82was never called.
 83.Pp
 84The constant
 85.Fa PTHREAD_ONCE_INIT
 86is defined by header
 87.In pthread.h .
 88.Pp
 89The behavior of
 90.Fn pthread_once
 91is undefined if
 92.Fa once_control
 93has automatic storage duration or is not initialized by
 94.Fa PTHREAD_ONCE_INIT .
 95.Sh RETURN VALUES
 96If successful, the
 97.Fn pthread_once
 98function will return zero.
 99Otherwise an error number will be returned to
100indicate the error.
101.Sh ERRORS
102None.
103.Sh STANDARDS
104The
105.Fn pthread_once
106function conforms to
107.St -p1003.1-96 .