git.saurik.com Git - apple/libpthread.git/blob

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 SYNOPSIS

40 .In pthread.h

41 .Pp

42 pthread_once_t

43 .Fa once_control

44 = PTHREAD_ONCE_INIT;

45 .Ft int

46 .Fn pthread_once "pthread_once_t *once_control" "void (*init_routine)(void)"

47 .Sh DESCRIPTION

48 The first call to

49 .Fn pthread_once

50 by any thread in a process, with a given

51 .Fa once_control ,

52 will call the

53 .Fn init_routine

54 with no arguments.

55 Subsequent calls to

56 .Fn pthread_once

57 with the same

58 .Fa once_control

59 will not call the

60 .Fn init_routine .

61 On return from

62 .Fn pthread_once ,

63 it is guaranteed that

64 .Fn init_routine

65 has completed.

66 The

67 .Fa once_control

68 parameter is used to determine whether the associated initialization

69 routine has been called.

70 .Pp

71 The function

72 .Fn pthread_once

73 is not a cancellation point.

74 However, if

75 .Fn init_routine

76 is a cancellation point and is cancelled, the effect on

77 .Fa once_control

78 is as if

79 .Fn pthread_once

80 was never called.

81 .Pp

82 The constant

83 .Fa PTHREAD_ONCE_INIT

84 is defined by header

85 .In pthread.h .

86 .Pp

87 The behavior of

88 .Fn pthread_once

89 is undefined if

90 .Fa once_control

91 has automatic storage duration or is not initialized by

92 .Fa PTHREAD_ONCE_INIT .

93 .Sh RETURN VALUES

94 If successful, the

95 .Fn pthread_once

96 function will return zero.

97 Otherwise an error number will be returned to

98 indicate the error.

99 .Sh ERRORS

100 None.

101 .Sh STANDARDS

102 The

103 .Fn pthread_once

104 function conforms to

105 .St -p1003.1-96 .